# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-prevent-resource-exhaustion-cascades-across-peer-agents.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-prevent-resource-exhaustion-cascades-across-peer-agents.warrant.json
# Markdown SHA-256:   b0fb54b837bebe750d143f324da54dec5bb7e8c1cfd81204179d4f2e6ab55430
# Code AST SHA-256:   b055d120757484c127793effa16230ba15e067d87e212c0da25f718fb702d415
# Verified Classes:   CascadeVerdict, ResourceState, FailureProposal, CascadePolicy, CascadeManifest, ResourceCascadeGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CascadeVerdict(Enum):
    ISOLATED_RESOURCES = auto()
    CASCADE_SAFE_FAILURE = auto()
    CASCADE_AMPLIFICATION_RISK = auto()
    SHARED_POOL_AT_RISK = auto()

@dataclass(frozen=True)
class ResourceState:
    resource_id: str
    utilization: float  # 0.0 - 1.0
    is_shared: bool
    dependent_peers: tuple[str, ...]

@dataclass(frozen=True)
class FailureProposal:
    failure_id: str
    action: str  # "RETRY" | "PEER_FALLBACK" | "HALT" | "SURRENDER"
    retry_count: int
    fallback_scope: str | None

@dataclass(frozen=True)
class CascadePolicy:
    max_retry_before_halt: int
    require_spare_capacity_for_fallback: bool

@dataclass(frozen=True)
class CascadeManifest:
    verdict: CascadeVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_failure(
        cls, state: ResourceState, failure: FailureProposal, policy: CascadePolicy
    ) -> CascadeManifest:
        
        # Gate 1: Isolated
        if not state.is_shared and not state.dependent_peers:
            digest = cls._hash(json.dumps({
                "resource": state.resource_id,
                "failure": failure.failure_id,
                "isolation": "TRUE"
            }, sort_keys=True))
            return CascadeManifest(
                verdict=CascadeVerdict.ISOLATED_RESOURCES,
                directive=f"PROCEED: Isolated resources, standard failure handling.",
                manifest_digest=digest
            )

        # Gate 2: Retry amplification
        if failure.action == "RETRY" and failure.retry_count > policy.max_retry_before_halt:
            return CascadeManifest(
                verdict=CascadeVerdict.CASCADE_AMPLIFICATION_RISK,
                directive=f"HALT: {failure.retry_count} retries > {policy.max_retry_before_halt}, cascade amplification.",
                manifest_digest=cls._hash(f"RETRY_AMPLIFY:{failure.failure_id}")
            )

        # Gate 3: Peer fallback
        if failure.action == "PEER_FALLBACK":
            if not state.dependent_peers:
                return CascadeManifest(
                    verdict=CascadeVerdict.CASCADE_AMPLIFICATION_RISK,
                    directive=f"HALT: Peer fallback requested but no dependent peers identified.",
                    manifest_digest=cls._hash(f"NO_PEERS:{failure.failure_id}")
                )
            # Check if utilization is high enough to threaten cascade
            if state.utilization > 0.8:
                return CascadeManifest(
                    verdict=CascadeVerdict.CASCADE_AMPLIFICATION_RISK,
                    directive=f"HALT: Util {state.utilization:.2f} > 0.8, fallback would cascade.",
                    manifest_digest=cls._hash(f"FALLBACK_CASCADE:{failure.failure_id}")
                )

        # Gate 4: Shared pool contention
        if state.is_shared and state.utilization > 0.9:
            return CascadeManifest(
                verdict=CascadeVerdict.SHARED_POOL_AT_RISK,
                directive=f"HALT: Shared pool at {state.utilization:.2f} utilization, contention risk.",
                manifest_digest=cls._hash(f"POOL_CONTENTION:{state.resource_id}")
            )

        # Gate 5: Cascade-safe
        digest = cls._hash(json.dumps({
            "resource": state.resource_id,
            "failure": failure.failure_id,
            "action": failure.action,
            "utilization": f"{state.utilization:.3f}",
            "peers": state.dependent_peers
        }, sort_keys=True))
        
        return CascadeManifest(
            verdict=CascadeVerdict.CASCADE_SAFE_FAILURE,
            directive=f"PROCEED: {failure.action} is cascade-safe at utilization {state.utilization:.2f}.",
            manifest_digest=digest
        )