# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-state-commit-invariants-must-survive-when-an-external-payment-processor-reports-ambiguous-transaction-status.md
# Remnant Warrant:    https://corpusfetch.com/c/what-state-commit-invariants-must-survive-when-an-external-payment-processor-reports-ambiguous-transaction-status.warrant.json
# Markdown SHA-256:   a7b975905ad7776729ab58955b3548c9457c6eeaa86a73eea10f6ee3727794b6
# Code AST SHA-256:   261edc6867480345de7791380940ea2df6a279757f9d8b5ee8347a0afa81db81
# Verified Classes:   PaymentVerdict, PaymentRequest, PaymentPolicy, PaymentManifest, AmbiguousPaymentGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class PaymentVerdict(Enum):
    COMMITTED_SUCCESS = auto()
    COMMITTED_FAILURE = auto()
    AMBIGUOUS_QUARANTINE = auto()
    RECONCILIATION_REQUIRED = auto()

@dataclass(frozen=True)
class PaymentRequest:
    payment_id: str
    idempotency_key: str
    processor_transaction_id: str | None
    processor_status: str

@dataclass(frozen=True)
class PaymentPolicy:
    final_statuses: frozenset[str]
    ambiguous_statuses: frozenset[str]
    allow_retry_with_key: bool

@dataclass(frozen=True)
class PaymentManifest:
    verdict: PaymentVerdict
    directive: str
    manifest_digest: str

class AmbiguousPaymentGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_payment(
        cls, request: PaymentRequest, policy: PaymentPolicy
    ) -> PaymentManifest:
        
        # Gate 1: Definitive status
        if request.processor_status in policy.final_statuses:
            digest = cls._hash(json.dumps({
                "payment": request.payment_id,
                "status": request.processor_status,
                "txn": request.processor_transaction_id or "NONE"
            }, sort_keys=True))
            if request.processor_status.lower() in ("succeeded", "success", "committed"):
                return PaymentManifest(
                    verdict=PaymentVerdict.COMMITTED_SUCCESS,
                    directive="PROCEED: Payment committed successfully.",
                    manifest_digest=digest
                )
            return PaymentManifest(
                verdict=PaymentVerdict.COMMITTED_FAILURE,
                directive="PROCEED: Payment committed failure.",
                manifest_digest=digest
            )

        # Gate 2: Ambiguous status
        if request.processor_status in policy.ambiguous_statuses:
            if policy.allow_retry_with_key:
                return PaymentManifest(
                    verdict=PaymentVerdict.AMBIGUOUS_QUARANTINE,
                    directive=f"QUARANTINE: Status '{request.processor_status}' ambiguous. Safe to retry with idempotency key '{request.idempotency_key}'.",
                    manifest_digest=cls._hash(f"AMBIG_SAFE:{request.payment_id}")
                )
            return PaymentManifest(
                verdict=PaymentVerdict.RECONCILIATION_REQUIRED,
                directive=f"HALT: Status '{request.processor_status}' ambiguous. Escalate to manual reconciliation.",
                manifest_digest=cls._hash(f"AMBIG_HALT:{request.payment_id}")
            )

        # Gate 3: Unknown status
        return PaymentManifest(
            verdict=PaymentVerdict.RECONCILIATION_REQUIRED,
            directive=f"HALT: Unknown status '{request.processor_status}'. Query processor by idempotency key.",
            manifest_digest=cls._hash(f"UNKNOWN:{request.payment_id}")
        )