# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-must-survive-a-retry-after-a-partial-failure-that-was-not-observed-at-the-source.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-must-survive-a-retry-after-a-partial-failure-that-was-not-observed-at-the-source.warrant.json
# Markdown SHA-256:   7b7ac55cb1dd534dae4ed40181e67f29c85ae9212ad5eae5e20ebb7aa5bbb12a
# Code AST SHA-256:   49ac39f67d71148e5abada00951892093e56ed17d2ac370a91209559cea0b49e
# Verified Classes:   RetryVerdict, RetryState, RetryPolicy, RetryManifest, PartialFailureRetryGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class RetryVerdict(Enum):
    IDEMPOTENT_SAFE = auto()
    QUERY_FIRST_REQUIRED = auto()
    IDEMPOTENCY_KEY_SAFE = auto()
    UNSAFE_RETRY = auto()

@dataclass(frozen=True)
class RetryState:
    source_supports_idempotency_key: bool
    source_state_queryable: bool
    source_idempotent_by_nature: bool
    has_idempotency_key: bool
    source_query_indicates_prior_success: bool | None

@dataclass(frozen=True)
class RetryPolicy:
    allow_blind_retry: bool

@dataclass(frozen=True)
class RetryManifest:
    verdict: RetryVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_retry(
        cls, state: RetryState, policy: RetryPolicy
    ) -> RetryManifest:
        
        # Gate 1: Naturally idempotent
        if state.source_idempotent_by_nature:
            digest = cls._hash(json.dumps({
                "idempotent": "NATURAL"
            }, sort_keys=True))
            return RetryManifest(
                verdict=RetryVerdict.IDEMPOTENT_SAFE,
                directive="PROCEED: Source is naturally idempotent.",
                manifest_digest=digest
            )

        # Gate 2: Query-first
        if state.source_state_queryable:
            if state.source_query_indicates_prior_success is True:
                digest = cls._hash(json.dumps({
                    "query": "PRIOR_SUCCESS",
                    "status": "RECONCILED"
                }, sort_keys=True))
                return RetryManifest(
                    verdict=RetryVerdict.QUERY_FIRST_REQUIRED,
                    directive="PROCEED: Source query confirms prior success. Treat as complete, do not retry.",
                    manifest_digest=digest
                )
            if state.source_query_indicates_prior_success is False:
                digest = cls._hash(json.dumps({
                    "query": "NO_PRIOR",
                    "status": "SAFE_TO_RETRY"
                }, sort_keys=True))
                return RetryManifest(
                    verdict=RetryVerdict.QUERY_FIRST_REQUIRED,
                    directive="PROCEED: Source query confirms no prior success. Safe to retry.",
                    manifest_digest=digest
                )
            return RetryManifest(
                verdict=RetryVerdict.QUERY_FIRST_REQUIRED,
                directive="HALT: Query source before retry. Unobserved partial failure risk.",
                manifest_digest=cls._hash("QUERY_PENDING")
            )

        # Gate 3: Idempotency key
        if state.source_supports_idempotency_key and state.has_idempotency_key:
            digest = cls._hash(json.dumps({
                "idempotency_key": "PRESENT"
            }, sort_keys=True))
            return RetryManifest(
                verdict=RetryVerdict.IDEMPOTENCY_KEY_SAFE,
                directive="PROCEED: Retry with idempotency key, source will deduplicate.",
                manifest_digest=digest
            )

        # Gate 4: Unsafe
        return RetryManifest(
            verdict=RetryVerdict.UNSAFE_RETRY,
            directive="HALT: Non-idempotent, non-queryable, no idempotency key. Retry would duplicate.",
            manifest_digest=cls._hash("UNSAFE")
        )