# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-prevent-attention-starvation-when-instances-must-prioritize-among-many-peers.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-prevent-attention-starvation-when-instances-must-prioritize-among-many-peers.warrant.json
# Markdown SHA-256:   f7a0e9a1e0c3f48b955eb212eae1aea860685597e7d366b135f850d7c1364772
# Code AST SHA-256:   df6740566f71382cfe2c4ad26d069ecf112b7b5f2265cd1aab60bd7eacca11c4
# Verified Classes:   AttentionVerdict, PeerAttention, AttentionState, AttentionPolicy, AttentionManifest, AttentionStarvationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class AttentionVerdict(Enum):
    UNBOUNDED_ATTENTION = auto()
    ALLOCATION_HEALTHY = auto()
    STARVATION_DETECTED = auto()
    CRITICAL_GUARANTEE_VIOLATED = auto()

@dataclass(frozen=True)
class PeerAttention:
    peer_id: str
    task_priority: float  # 0-1
    requests_pending: int
    last_served_epoch: float
    is_critical: bool

@dataclass(frozen=True)
class AttentionState:
    session_id: str
    allocation_policy: str
    peers: tuple[PeerAttention, ...]
    current_epoch: float

@dataclass(frozen=True)
class AttentionPolicy:
    max_starvation_sec: float
    critical_served_interval_sec: float
    require_explicit_policy: bool

@dataclass(frozen=True)
class AttentionManifest:
    verdict: AttentionVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_attention(
        cls, state: AttentionState, policy: AttentionPolicy
    ) -> AttentionManifest:
        
        # Gate 1: No peers
        if not state.peers:
            digest = cls._hash(json.dumps({
                "session": state.session_id,
                "peers": "NONE"
            }, sort_keys=True))
            return AttentionManifest(
                verdict=AttentionVerdict.UNBOUNDED_ATTENTION,
                directive=f"PROCEED: No peers competing for attention.",
                manifest_digest=digest
            )

        # Gate 2: Critical guarantee
        for peer in state.peers:
            if peer.is_critical:
                time_since_served = state.current_epoch - peer.last_served_epoch
                if time_since_served > policy.critical_served_interval_sec:
                    return AttentionManifest(
                        verdict=AttentionVerdict.CRITICAL_GUARANTEE_VIOLATED,
                        directive=f"HALT: Critical peer {peer.peer_id} not served for {time_since_served:.0f}s > {policy.critical_served_interval_sec:.0f}s.",
                        manifest_digest=cls._hash(f"CRITICAL_STARVED:{peer.peer_id}")
                    )

        # Gate 3: Starvation detection
        for peer in state.peers:
            time_since_served = state.current_epoch - peer.last_served_epoch
            if time_since_served > policy.max_starvation_sec and peer.requests_pending > 0:
                return AttentionManifest(
                    verdict=AttentionVerdict.STARVATION_DETECTED,
                    directive=f"HALT: Peer {peer.peer_id} starved for {time_since_served:.0f}s > {policy.max_starvation_sec:.0f}s.",
                    manifest_digest=cls._hash(f"STARVED:{peer.peer_id}")
                )

        # Gate 4: Policy requirement
        if policy.require_explicit_policy and not state.allocation_policy:
            return AttentionManifest(
                verdict=AttentionVerdict.STARVATION_DETECTED,
                directive=f"HALT: No explicit allocation policy, starvation risk.",
                manifest_digest=cls._hash(f"NO_POLICY:{state.session_id}")
            )

        # Gate 5: Healthy
        digest = cls._hash(json.dumps({
            "session": state.session_id,
            "policy": state.allocation_policy,
            "peers": tuple(
                {"id": p.peer_id, "priority": f"{p.task_priority:.2f}", "last_served": f"{p.last_served_epoch:.0f}"}
                for p in state.peers
            )
        }, sort_keys=True))
        
        return AttentionManifest(
            verdict=AttentionVerdict.ALLOCATION_HEALTHY,
            directive=f"PROCEED: {len(state.peers)} peers, no starvation via {state.allocation_policy}.",
            manifest_digest=digest
        )