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');
+        }
+    }
+}