feat(form-builder): MergeStrategy enum methods + binding value objects (WS-6)

- FormFieldBindingMergeStrategy::nullWinnerBehaviour() and
  isValidForScalarTargets() encode the per-strategy null-winner matrix
  (RFC Q7) and the collection-only restriction (RFC V1).
- ResolvedBinding/BindingApplicationResult/BindingPassResult readonly
  DTOs for the binding pipeline. Construction-time validation for
  trust level. Apply-status derived from result aggregate.

Note: the existing enum is named FormFieldBindingMergeStrategy (not
MergeStrategy as the prompt sketched). Methods added to it directly.

Refs: RFC-WS-6.md §3 (Q4, Q7), §4 (V1)

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

api/app/Enums/FormBuilder/FormFieldBindingMergeStrategy.php

@@ -10,4 +10,31 @@ enum FormFieldBindingMergeStrategy: string
     case Append = 'append';
     case Replace = 'replace';
     case FirstWriteWins = 'first_write_wins';
+
+    /**
+     * RFC-WS-6 §3 (Q7) — what to do when the conflict-resolution winner
+     * has a null value. Returns one of:
+     *   - 'write'        write null to the target (intent: clear)
+     *   - 'noop'         leave the target untouched
+     *   - 'conditional'  write only when the target itself is null
+     */
+    public function nullWinnerBehaviour(): string
+    {
+        return match ($this) {
+            self::Overwrite => 'write',
+            self::Append => 'noop',
+            self::Replace => 'noop',
+            self::FirstWriteWins => 'conditional',
+        };
+    }
+
+    /**
+     * RFC-WS-6 §4 (V1) — Append is collection-only (idempotent retry only
+     * with set semantics; scalar-append demands fingerprinting which is
+     * an architectural smell).
+     */
+    public function isValidForScalarTargets(): bool
+    {
+        return $this !== self::Append;
+    }
 }

api/app/FormBuilder/Bindings/BindingApplicationResult.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Bindings;
+
+use Throwable;
+
+/**
+ * RFC-WS-6 §3 (Q4) — the result of applying a single resolved binding
+ * to its target. Sealed via two named constructors so consumers can't
+ * synthesise impossible states (success-with-exception, etc.).
+ */
+final readonly class BindingApplicationResult
+{
+    private function __construct(
+        public string $bindingId,
+        public string $targetEntity,
+        public string $targetAttribute,
+        public bool $success,
+        public mixed $oldValue,
+        public mixed $newValue,
+        public ?string $exceptionClass = null,
+        public ?string $exceptionMessage = null,
+    ) {}
+
+    public static function succeeded(
+        string $bindingId,
+        string $targetEntity,
+        string $targetAttribute,
+        mixed $oldValue,
+        mixed $newValue,
+    ): self {
+        return new self(
+            bindingId: $bindingId,
+            targetEntity: $targetEntity,
+            targetAttribute: $targetAttribute,
+            success: true,
+            oldValue: $oldValue,
+            newValue: $newValue,
+        );
+    }
+
+    public static function failed(
+        string $bindingId,
+        string $targetEntity,
+        string $targetAttribute,
+        Throwable $e,
+    ): self {
+        return new self(
+            bindingId: $bindingId,
+            targetEntity: $targetEntity,
+            targetAttribute: $targetAttribute,
+            success: false,
+            oldValue: null,
+            newValue: null,
+            exceptionClass: $e::class,
+            exceptionMessage: $e->getMessage(),
+        );
+    }
+}

api/app/FormBuilder/Bindings/BindingPassResult.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Bindings;
+
+use App\Enums\FormBuilder\ApplyStatus;
+
+/**
+ * RFC-WS-6 §3 (Q4) — aggregate result of one
+ * {@see \App\Services\FormBuilder\FormBindingApplicator} pass over a
+ * submission. `applyStatus()` is the canonical mapping consumed by
+ * `form_submissions.apply_status`.
+ */
+final readonly class BindingPassResult
+{
+    /**
+     * @param  list<BindingApplicationResult>  $applications
+     */
+    public function __construct(
+        public string $formSubmissionId,
+        public ?string $provisionedSubjectType,
+        public ?string $provisionedSubjectId,
+        public array $applications,
+    ) {}
+
+    public function applyStatus(): ApplyStatus
+    {
+        if ($this->applications === []) {
+            return ApplyStatus::COMPLETED;
+        }
+
+        $successes = $this->successCount();
+        $failures = $this->failureCount();
+
+        if ($failures === 0) {
+            return ApplyStatus::COMPLETED;
+        }
+        if ($successes === 0) {
+            return ApplyStatus::FAILED;
+        }
+
+        return ApplyStatus::PARTIAL;
+    }
+
+    public function successCount(): int
+    {
+        return count(array_filter($this->applications, fn (BindingApplicationResult $r): bool => $r->success));
+    }
+
+    public function failureCount(): int
+    {
+        return count(array_filter($this->applications, fn (BindingApplicationResult $r): bool => ! $r->success));
+    }
+
+    /**
+     * @return list<BindingApplicationResult>
+     */
+    public function failures(): array
+    {
+        return array_values(array_filter(
+            $this->applications,
+            fn (BindingApplicationResult $r): bool => ! $r->success,
+        ));
+    }
+}

api/app/FormBuilder/Bindings/ResolvedBinding.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Bindings;
+
+use App\Enums\FormBuilder\BindingTargetType;
+use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
+use InvalidArgumentException;
+
+/**
+ * RFC-WS-6 §3 (Q7) — output of `BindingConflictResolver`. One winning
+ * binding per `(target_entity, target_attribute)` group, ready for the
+ * applicator to write.
+ */
+final readonly class ResolvedBinding
+{
+    public function __construct(
+        public string $sourceFormFieldId,
+        public string $bindingId,
+        public string $targetEntity,
+        public string $targetAttribute,
+        public BindingTargetType $targetType,
+        public FormFieldBindingMergeStrategy $mergeStrategy,
+        public int $trustLevel,
+        public bool $isIdentityKey,
+        public mixed $value,
+        public bool $valueIsExplicit,
+    ) {
+        if ($trustLevel < 0 || $trustLevel > 100) {
+            throw new InvalidArgumentException(
+                "trustLevel must be in [0,100]; got {$trustLevel}",
+            );
+        }
+        if ($targetEntity === '') {
+            throw new InvalidArgumentException('targetEntity must not be empty');
+        }
+        if ($targetAttribute === '') {
+            throw new InvalidArgumentException('targetAttribute must not be empty');
+        }
+    }
+}

api/tests/Unit/Enums/FormBuilder/MergeStrategyTest.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Enums\FormBuilder;
+
+use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
+use PHPUnit\Framework\TestCase;
+
+final class MergeStrategyTest extends TestCase
+{
+    public function test_null_winner_behaviour_per_strategy(): void
+    {
+        $this->assertSame('write', FormFieldBindingMergeStrategy::Overwrite->nullWinnerBehaviour());
+        $this->assertSame('noop', FormFieldBindingMergeStrategy::Append->nullWinnerBehaviour());
+        $this->assertSame('noop', FormFieldBindingMergeStrategy::Replace->nullWinnerBehaviour());
+        $this->assertSame('conditional', FormFieldBindingMergeStrategy::FirstWriteWins->nullWinnerBehaviour());
+    }
+
+    public function test_is_valid_for_scalar_targets_only_append_returns_false(): void
+    {
+        $this->assertTrue(FormFieldBindingMergeStrategy::Overwrite->isValidForScalarTargets());
+        $this->assertFalse(FormFieldBindingMergeStrategy::Append->isValidForScalarTargets());
+        $this->assertTrue(FormFieldBindingMergeStrategy::Replace->isValidForScalarTargets());
+        $this->assertTrue(FormFieldBindingMergeStrategy::FirstWriteWins->isValidForScalarTargets());
+    }
+}

api/tests/Unit/FormBuilder/Bindings/BindingApplicationResultTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\FormBuilder\Bindings;
+
+use App\FormBuilder\Bindings\BindingApplicationResult;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+final class BindingApplicationResultTest extends TestCase
+{
+    public function test_succeeded_constructor_populates_state_correctly(): void
+    {
+        $result = BindingApplicationResult::succeeded(
+            bindingId: 'bnd-1',
+            targetEntity: 'person',
+            targetAttribute: 'email',
+            oldValue: null,
+            newValue: 'jan@example.nl',
+        );
+
+        $this->assertTrue($result->success);
+        $this->assertSame('bnd-1', $result->bindingId);
+        $this->assertSame('person', $result->targetEntity);
+        $this->assertSame('email', $result->targetAttribute);
+        $this->assertNull($result->oldValue);
+        $this->assertSame('jan@example.nl', $result->newValue);
+        $this->assertNull($result->exceptionClass);
+        $this->assertNull($result->exceptionMessage);
+    }
+
+    public function test_failed_constructor_captures_exception_metadata(): void
+    {
+        $exception = new RuntimeException('boom');
+
+        $result = BindingApplicationResult::failed(
+            bindingId: 'bnd-2',
+            targetEntity: 'company',
+            targetAttribute: 'name',
+            e: $exception,
+        );
+
+        $this->assertFalse($result->success);
+        $this->assertSame('bnd-2', $result->bindingId);
+        $this->assertNull($result->oldValue);
+        $this->assertNull($result->newValue);
+        $this->assertSame(RuntimeException::class, $result->exceptionClass);
+        $this->assertSame('boom', $result->exceptionMessage);
+    }
+}

api/tests/Unit/FormBuilder/Bindings/BindingPassResultTest.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\FormBuilder\Bindings;
+
+use App\Enums\FormBuilder\ApplyStatus;
+use App\FormBuilder\Bindings\BindingApplicationResult;
+use App\FormBuilder\Bindings\BindingPassResult;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+final class BindingPassResultTest extends TestCase
+{
+    public function test_empty_applications_yield_completed(): void
+    {
+        $result = $this->make([]);
+        $this->assertSame(ApplyStatus::COMPLETED, $result->applyStatus());
+        $this->assertSame(0, $result->successCount());
+        $this->assertSame(0, $result->failureCount());
+    }
+
+    public function test_all_succeeded_yields_completed(): void
+    {
+        $result = $this->make([$this->success('a'), $this->success('b')]);
+        $this->assertSame(ApplyStatus::COMPLETED, $result->applyStatus());
+        $this->assertSame(2, $result->successCount());
+        $this->assertSame(0, $result->failureCount());
+        $this->assertSame([], $result->failures());
+    }
+
+    public function test_all_failed_yields_failed(): void
+    {
+        $result = $this->make([$this->failure('a'), $this->failure('b')]);
+        $this->assertSame(ApplyStatus::FAILED, $result->applyStatus());
+        $this->assertSame(0, $result->successCount());
+        $this->assertSame(2, $result->failureCount());
+        $this->assertCount(2, $result->failures());
+    }
+
+    public function test_mixed_yields_partial(): void
+    {
+        $result = $this->make([
+            $this->success('a'),
+            $this->failure('b'),
+            $this->success('c'),
+        ]);
+        $this->assertSame(ApplyStatus::PARTIAL, $result->applyStatus());
+        $this->assertSame(2, $result->successCount());
+        $this->assertSame(1, $result->failureCount());
+        $this->assertCount(1, $result->failures());
+        $this->assertSame('b', $result->failures()[0]->bindingId);
+    }
+
+    /**
+     * @param  list<BindingApplicationResult>  $applications
+     */
+    private function make(array $applications): BindingPassResult
+    {
+        return new BindingPassResult(
+            formSubmissionId: 'fs-1',
+            provisionedSubjectType: 'person',
+            provisionedSubjectId: 'p-1',
+            applications: $applications,
+        );
+    }
+
+    private function success(string $bindingId): BindingApplicationResult
+    {
+        return BindingApplicationResult::succeeded(
+            bindingId: $bindingId,
+            targetEntity: 'person',
+            targetAttribute: 'email',
+            oldValue: null,
+            newValue: 'x@y.z',
+        );
+    }
+
+    private function failure(string $bindingId): BindingApplicationResult
+    {
+        return BindingApplicationResult::failed(
+            bindingId: $bindingId,
+            targetEntity: 'person',
+            targetAttribute: 'email',
+            e: new RuntimeException('boom'),
+        );
+    }
+}

api/tests/Unit/FormBuilder/Bindings/ResolvedBindingTest.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\FormBuilder\Bindings;
+
+use App\Enums\FormBuilder\BindingTargetType;
+use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
+use App\FormBuilder\Bindings\ResolvedBinding;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+
+final class ResolvedBindingTest extends TestCase
+{
+    public function test_construction_with_valid_data(): void
+    {
+        $binding = $this->makeWith(['trustLevel' => 80]);
+        $this->assertSame(80, $binding->trustLevel);
+        $this->assertSame('person', $binding->targetEntity);
+    }
+
+    public function test_trust_level_lower_bound(): void
+    {
+        $binding = $this->makeWith(['trustLevel' => 0]);
+        $this->assertSame(0, $binding->trustLevel);
+    }
+
+    public function test_trust_level_upper_bound(): void
+    {
+        $binding = $this->makeWith(['trustLevel' => 100]);
+        $this->assertSame(100, $binding->trustLevel);
+    }
+
+    public function test_trust_level_below_zero_throws(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->makeWith(['trustLevel' => -1]);
+    }
+
+    public function test_trust_level_above_hundred_throws(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->makeWith(['trustLevel' => 101]);
+    }
+
+    public function test_empty_target_entity_throws(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->makeWith(['targetEntity' => '']);
+    }
+
+    public function test_empty_target_attribute_throws(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->makeWith(['targetAttribute' => '']);
+    }
+
+    public function test_null_value_preserved_with_explicit_flag(): void
+    {
+        $binding = $this->makeWith([
+            'value' => null,
+            'valueIsExplicit' => true,
+        ]);
+        $this->assertNull($binding->value);
+        $this->assertTrue($binding->valueIsExplicit);
+    }
+
+    /**
+     * @param  array<string, mixed>  $overrides
+     */
+    private function makeWith(array $overrides): ResolvedBinding
+    {
+        $defaults = [
+            'sourceFormFieldId' => '01jq1k1k1k1k1k1k1k1k1k1k1k',
+            'bindingId' => '01jq1k1k1k1k1k1k1k1k1k1k1l',
+            'targetEntity' => 'person',
+            'targetAttribute' => 'email',
+            'targetType' => BindingTargetType::SCALAR,
+            'mergeStrategy' => FormFieldBindingMergeStrategy::Overwrite,
+            'trustLevel' => 50,
+            'isIdentityKey' => false,
+            'value' => 'jan@example.nl',
+            'valueIsExplicit' => true,
+        ];
+
+        $args = array_merge($defaults, $overrides);
+
+        return new ResolvedBinding(
+            sourceFormFieldId: $args['sourceFormFieldId'],
+            bindingId: $args['bindingId'],
+            targetEntity: $args['targetEntity'],
+            targetAttribute: $args['targetAttribute'],
+            targetType: $args['targetType'],
+            mergeStrategy: $args['mergeStrategy'],
+            trustLevel: $args['trustLevel'],
+            isIdentityKey: $args['isIdentityKey'],
+            value: $args['value'],
+            valueIsExplicit: $args['valueIsExplicit'],
+        );
+    }
+}