test(form-builder): write-path invariant for conflict-resolver candidate set (WS-6)

Asserts the RFC Q7 prerequisite: every visible form_field has a
form_values row after submit (even null/empty), every absent field has
none. This is the invariant the BindingConflictResolver relies on to
distinguish 'explicit clear' from 'skipped by conditional logic'.

Refs: RFC-WS-6.md §3 (Q7)

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

api/tests/Feature/FormBuilder/Bindings/FormValuesWritePathInvariantTest.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\FormBuilder\Bindings;
+
+use App\Enums\FormBuilder\FormFieldType;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\FormBuilder\FormSubmission;
+use App\Models\FormBuilder\FormValue;
+use App\Services\FormBuilder\FormValueService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+/**
+ * RFC-WS-6 §3 (Q7) write-path invariant — every form_field that should
+ * be visible after conditional-logic evaluation has a row in form_values
+ * after submit, even when the user submits an empty/null value. Without
+ * this invariant the BindingConflictResolver cannot distinguish
+ * "explicit clear" from "skipped by conditional logic".
+ *
+ * If this test FAILS, the conflict-resolver's candidate-set semantics
+ * are unsafe and need a fix in FormValueService::upsertMany before
+ * landing the binding pipeline in production.
+ */
+final class FormValuesWritePathInvariantTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_empty_string_value_yields_form_value_row(): void
+    {
+        $schema = FormSchema::factory()->create();
+        $field = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'slug' => 'comments',
+            'field_type' => FormFieldType::TEXT->value,
+        ]);
+        $submission = FormSubmission::factory()->create([
+            'form_schema_id' => $schema->id,
+            'organisation_id' => $schema->organisation_id,
+        ]);
+
+        $this->app->make(FormValueService::class)->upsertMany(
+            $submission,
+            ['comments' => ''],
+            null,
+        );
+
+        $row = FormValue::query()
+            ->withoutGlobalScopes()
+            ->where('form_submission_id', $submission->id)
+            ->where('form_field_id', $field->id)
+            ->first();
+        $this->assertNotNull($row, 'A form_value row MUST exist for an explicitly-blank submitted field (RFC Q7 invariant).');
+    }
+
+    public function test_field_not_submitted_has_no_form_value_row(): void
+    {
+        // Absence in slugToValue → no row written. This is the "skipped by
+        // conditional logic" path that RFC Q7 distinguishes from explicit
+        // null — the resolver excludes it from the candidate set.
+        $schema = FormSchema::factory()->create();
+        $field = FormField::factory()->create([
+            'form_schema_id' => $schema->id,
+            'slug' => 'visible_field',
+        ]);
+        $submission = FormSubmission::factory()->create([
+            'form_schema_id' => $schema->id,
+            'organisation_id' => $schema->organisation_id,
+        ]);
+
+        $this->app->make(FormValueService::class)->upsertMany($submission, [], null);
+
+        $row = FormValue::query()
+            ->withoutGlobalScopes()
+            ->where('form_submission_id', $submission->id)
+            ->where('form_field_id', $field->id)
+            ->first();
+        $this->assertNull($row, 'Absent form_field MUST have no form_value row (RFC Q7 invariant).');
+    }
+}