<?php

declare(strict_types=1);

namespace App\Enums\FormBuilder;

enum FormFieldBindingMergeStrategy: string
{
    case Overwrite = 'overwrite';
    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;
    }

    /**
     * Whether this strategy is structurally valid against the given target
     * type.
     *
     * Per RFC-WS-6 §V1 + ARCH-BINDINGS §4.2 (strategy x target-type validity matrix).
     *
     *                  | SCALAR | COLLECTION | RELATION |
     *  Overwrite       | valid  | valid*     | valid    |
     *  Append          | INVALID| valid      | INVALID  |
     *  Replace         | valid  | valid      | valid    |
     *  FirstWriteWins  | valid  | valid      | valid    |
     *
     *  * unusual but valid (overwrites entire collection)
     *
     * The PublishGuard AppendStrategyRequiresCollectionTarget uses this
     * method to validate at publish time. Append on scalars is rejected
     * because it requires a fingerprint mechanism for retry-idempotency
     * that would embed implementation detail in domain data.
     */
    public function validForTargetType(BindingTargetType $type): bool
    {
        return match ($this) {
            self::Append => $type === BindingTargetType::COLLECTION,
            default => true,
        };
    }
}