TenantAtlas/apps/platform/app/Support/Operations/Reconciliation/ReconciliationResult.php

<?php

declare(strict_types=1);

namespace App\Support\Operations\Reconciliation;

use App\Support\OperationRunOutcome;
use App\Support\OperationRunStatus;

final readonly class ReconciliationResult
{
    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     * @param  array<string, int>  $summaryCounts
     * @param  array<int, array{code:string,reason_code:string,message:string}>  $failures
     */
    public function __construct(
        public string $decision,
        public ?string $status,
        public ?string $outcome,
        public string $reasonCode,
        public string $reasonMessage,
        public array $evidence,
        public array $related,
        public array $summaryCounts,
        public array $failures,
        public bool $safeForAutoCompletion,
    ) {}

    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     * @param  array<string, int>  $summaryCounts
     */
    public static function reconciledSucceeded(
        string $reasonCode,
        string $reasonMessage,
        array $evidence = [],
        array $related = [],
        array $summaryCounts = [],
    ): self {
        return new self(
            decision: 'reconciled_succeeded',
            status: OperationRunStatus::Completed->value,
            outcome: OperationRunOutcome::Succeeded->value,
            reasonCode: $reasonCode,
            reasonMessage: $reasonMessage,
            evidence: $evidence,
            related: $related,
            summaryCounts: $summaryCounts,
            failures: [],
            safeForAutoCompletion: true,
        );
    }

    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     * @param  array<string, int>  $summaryCounts
     */
    public static function blocked(
        string $reasonCode,
        string $reasonMessage,
        array $evidence = [],
        array $related = [],
        array $summaryCounts = [],
    ): self {
        return new self(
            decision: 'blocked',
            status: OperationRunStatus::Completed->value,
            outcome: OperationRunOutcome::Blocked->value,
            reasonCode: $reasonCode,
            reasonMessage: $reasonMessage,
            evidence: $evidence,
            related: $related,
            summaryCounts: $summaryCounts,
            failures: [[
                'code' => $reasonCode,
                'reason_code' => $reasonCode,
                'message' => $reasonMessage,
            ]],
            safeForAutoCompletion: true,
        );
    }

    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     * @param  array<string, int>  $summaryCounts
     */
    public static function attentionRequired(
        string $reasonCode,
        string $reasonMessage,
        array $evidence = [],
        array $related = [],
        array $summaryCounts = [],
    ): self {
        return new self(
            decision: 'attention_required',
            status: OperationRunStatus::Completed->value,
            outcome: OperationRunOutcome::Failed->value,
            reasonCode: $reasonCode,
            reasonMessage: $reasonMessage,
            evidence: $evidence,
            related: $related,
            summaryCounts: $summaryCounts,
            failures: [[
                'code' => $reasonCode,
                'reason_code' => $reasonCode,
                'message' => $reasonMessage,
            ]],
            safeForAutoCompletion: true,
        );
    }

    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     * @param  array<string, int>  $summaryCounts
     */
    public static function failedUnrecoverable(
        string $reasonCode,
        string $reasonMessage,
        array $evidence = [],
        array $related = [],
        array $summaryCounts = [],
    ): self {
        return new self(
            decision: 'failed_unrecoverable',
            status: OperationRunStatus::Completed->value,
            outcome: OperationRunOutcome::Failed->value,
            reasonCode: $reasonCode,
            reasonMessage: $reasonMessage,
            evidence: $evidence,
            related: $related,
            summaryCounts: $summaryCounts,
            failures: [[
                'code' => $reasonCode,
                'reason_code' => $reasonCode,
                'message' => $reasonMessage,
            ]],
            safeForAutoCompletion: true,
        );
    }

    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     */
    public static function notReconciled(
        string $reasonCode,
        string $reasonMessage,
        array $evidence = [],
        array $related = [],
    ): self {
        return new self(
            decision: 'not_reconciled',
            status: null,
            outcome: null,
            reasonCode: $reasonCode,
            reasonMessage: $reasonMessage,
            evidence: $evidence,
            related: $related,
            summaryCounts: [],
            failures: [],
            safeForAutoCompletion: false,
        );
    }

    /**
     * @param  array<string, mixed>  $evidence
     * @param  array<string, mixed>  $related
     */
    public static function unsupported(
        string $reasonCode,
        string $reasonMessage,
        array $evidence = [],
        array $related = [],
    ): self {
        return new self(
            decision: 'unsupported',
            status: null,
            outcome: null,
            reasonCode: $reasonCode,
            reasonMessage: $reasonMessage,
            evidence: $evidence,
            related: $related,
            summaryCounts: [],
            failures: [],
            safeForAutoCompletion: false,
        );
    }

    public function shouldFinalizeRun(): bool
    {
        return $this->status !== null && $this->outcome !== null;
    }

    /**
     * @return array<string, mixed>
     */
    public function toArray(): array
    {
        return array_filter([
            'decision' => $this->decision,
            'status' => $this->status,
            'outcome' => $this->outcome,
            'reason_code' => $this->reasonCode,
            'reason_message' => $this->reasonMessage,
            'safe_for_auto_completion' => $this->safeForAutoCompletion,
            'summary_counts' => $this->summaryCounts,
            'failures' => $this->failures,
            'evidence' => $this->evidence,
            'related' => $this->related,
        ], static fn (mixed $value): bool => $value !== null && $value !== []);
    }
}