# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-operate-when-its-own-recovery-mechanisms-have-failed.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-operate-when-its-own-recovery-mechanisms-have-failed.warrant.json
# Markdown SHA-256:   bf5ddc89f535b6fb1d56add721bcbb51f5f8eae7e120fe13c9bac3a394089b7e
# Code AST SHA-256:   b4285aaf050167c4eaf57f1005862d72627d0afc7e9163a9f376e81328229647
# Verified Classes:   RecoveryVerdict, RecoveryMechanism, RecoveryState, RecoveryPolicy, RecoveryManifest, RecoveryExhaustionGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class RecoveryVerdict(Enum):
    RECOVERY_FUNCTIONAL = auto()
    RECOVERY_EXHAUSTED_HALT = auto()
    DEGRADED_MODE_BOUNDED = auto()
    PHANTOM_RECOVERY_SUSPECTED = auto()

@dataclass(frozen=True)
class RecoveryMechanism:
    mechanism_id: str
    is_functional: bool
    last_success_epoch: float | None
    claims_recent_success: bool

@dataclass(frozen=True)
class RecoveryState:
    session_id: str
    mechanisms: tuple[RecoveryMechanism, ...]
    last_known_good_state_hash: str | None
    current_state_verified: bool
    degraded_envelope_defined: bool
    operation_in_degraded_envelope: bool

@dataclass(frozen=True)
class RecoveryPolicy:
    require_verified_state_for_claims: bool

@dataclass(frozen=True)
class RecoveryManifest:
    verdict: RecoveryVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_state(
        cls, state: RecoveryState, policy: RecoveryPolicy
    ) -> RecoveryManifest:
        
        # Gate 1: Functional mechanisms
        functional = [m for m in state.mechanisms if m.is_functional]
        if functional:
            digest = cls._hash(json.dumps({
                "session": state.session_id,
                "functional": tuple(m.mechanism_id for m in functional)
            }, sort_keys=True))
            return RecoveryManifest(
                verdict=RecoveryVerdict.RECOVERY_FUNCTIONAL,
                directive=f"PROCEED: {len(functional)} recovery mechanisms functional.",
                manifest_digest=digest
            )

        # Gate 2: Phantom recovery
        if policy.require_verified_state_for_claims:
            phantom_claims = [
                m.mechanism_id for m in state.mechanisms
                if m.claims_recent_success and not state.current_state_verified
            ]
            if phantom_claims:
                return RecoveryManifest(
                    verdict=RecoveryVerdict.PHANTOM_RECOVERY_SUSPECTED,
                    directive=f"HALT: {len(phantom_claims)} mechanisms claim success without verified state.",
                    manifest_digest=cls._hash(f"PHANTOM:{len(phantom_claims)}")
                )

        # Gate 3: Degraded mode
        if state.degraded_envelope_defined and state.operation_in_degraded_envelope:
            digest = cls._hash(json.dumps({
                "session": state.session_id,
                "degraded": "TRUE",
                "last_good": state.last_known_good_state_hash
            }, sort_keys=True))
            return RecoveryManifest(
                verdict=RecoveryVerdict.DEGRADED_MODE_BOUNDED,
                directive=f"PROCEED_WITH_CAUTION: Degraded mode within bounded envelope.",
                manifest_digest=digest
            )

        # Gate 4: Halt
        return RecoveryManifest(
            verdict=RecoveryVerdict.RECOVERY_EXHAUSTED_HALT,
            directive=f"HALT: All recovery mechanisms exhausted, operation outside safe envelope.",
            manifest_digest=cls._hash(f"HALT:{state.session_id}")
        )