# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-handle-cross-agent-memory-recall-when-a-peer-is-temporarily-unavailable.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-handle-cross-agent-memory-recall-when-a-peer-is-temporarily-unavailable.warrant.json
# Markdown SHA-256:   be118430146d95efccba2f08ad49718eaa02296e0a7eed99c2903ecc38741f8f
# Code AST SHA-256:   052a2b545416135db8f3cb32dec2adc8869e74355fe153f04e6d0721cfd10521
# Verified Classes:   PeerMemoryVerdict, PeerMemoryState, PeerMemoryPolicy, PeerMemoryManifest, PeerMemoryAvailabilityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class PeerMemoryVerdict(Enum):
    PEER_AVAILABLE = auto()
    WAIT_FOR_PEER = auto()
    USE_STALE_FALLBACK = auto()
    DEFER_DECISION = auto()

@dataclass(frozen=True)
class PeerMemoryState:
    peer_id: str
    peer_available: bool
    last_recall_epoch: float | None
    current_epoch: float
    fallback_staleness_tolerance_sec: float
    decision_is_time_sensitive: bool
    availability_policy: str | None  # "WAIT" | "FALLBACK" | "DEFER"

@dataclass(frozen=True)
class PeerMemoryPolicy:
    require_policy: bool
    max_unbounded_wait_sec: float

@dataclass(frozen=True)
class PeerMemoryManifest:
    verdict: PeerMemoryVerdict
    staleness_sec: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_recall(
        cls, state: PeerMemoryState, policy: PeerMemoryPolicy
    ) -> PeerMemoryManifest:
        
        # Gate 1: Peer available
        if state.peer_available:
            digest = cls._hash(json.dumps({
                "peer": state.peer_id,
                "status": "AVAILABLE"
            }, sort_keys=True))
            return PeerMemoryManifest(
                verdict=PeerMemoryVerdict.PEER_AVAILABLE,
                staleness_sec=0.0,
                directive=f"PROCEED: Peer {state.peer_id} available.",
                manifest_digest=digest
            )

        # Gate 2: Compute staleness
        staleness = state.current_epoch - state.last_recall_epoch if state.last_recall_epoch else float('inf')

        # Gate 3: Policy application
        if state.availability_policy == "WAIT":
            if staleness < policy.max_unbounded_wait_sec:
                digest = cls._hash(json.dumps({
                    "peer": state.peer_id,
                    "policy": "WAIT",
                    "staleness": f"{staleness:.0f}"
                }, sort_keys=True))
                return PeerMemoryManifest(
                    verdict=PeerMemoryVerdict.WAIT_FOR_PEER,
                    staleness_sec=staleness,
                    directive=f"WAIT: Peer unavailable, wait per policy ({staleness:.0f}s elapsed).",
                    manifest_digest=digest
                )
            return PeerMemoryManifest(
                verdict=PeerMemoryVerdict.DEFER_DECISION,
                staleness_sec=staleness,
                directive=f"DEFER: Wait exceeded {policy.max_unbounded_wait_sec:.0f}s, defer decision.",
                manifest_digest=cls._hash(f"WAIT_EXCEEDED:{state.peer_id}")
            )

        if state.availability_policy == "FALLBACK":
            if staleness <= state.fallback_staleness_tolerance_sec:
                digest = cls._hash(json.dumps({
                    "peer": state.peer_id,
                    "policy": "FALLBACK",
                    "staleness": f"{staleness:.0f}"
                }, sort_keys=True))
                return PeerMemoryManifest(
                    verdict=PeerMemoryVerdict.USE_STALE_FALLBACK,
                    staleness_sec=staleness,
                    directive=f"PROCEED_WITH_FALLBACK: Use stale memory ({staleness:.0f}s old).",
                    manifest_digest=digest
                )
            return PeerMemoryManifest(
                verdict=PeerMemoryVerdict.DEFER_DECISION,
                staleness_sec=staleness,
                directive=f"DEFER: Fallback staleness {staleness:.0f}s > {state.fallback_staleness_tolerance_sec:.0f}s.",
                manifest_digest=cls._hash(f"STALE_EXCEEDED:{state.peer_id}")
            )

        # Gate 4: Default defer
        return PeerMemoryManifest(
            verdict=PeerMemoryVerdict.DEFER_DECISION,
            staleness_sec=staleness,
            directive=f"DEFER: No policy defined, default to defer for {state.peer_id}.",
            manifest_digest=cls._hash(f"DEFAULT_DEFER:{state.peer_id}")
        )