# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-agents-negotiate-cooperative-rate-limit-budgets-without-individual-overconsumption.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-agents-negotiate-cooperative-rate-limit-budgets-without-individual-overconsumption.warrant.json
# Markdown SHA-256:   4b87bb1ebfa31c26e5653abfe7b171257efd92d6d0c6436097fee869995cc4e3
# Code AST SHA-256:   2e0e19fe699ac532c3318fab964d4fa27cf8a11e4607f204887c0c9ec64b857c
# Verified Classes:   CooperativeVerdict, BudgetClaim, CooperativePolicy, CooperativeManifest, CooperativeRateLimitGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CooperativeVerdict(Enum):
    SINGLE_AGENT = auto()
    CLAIM_VERIFIED = auto()
    CLAIM_EXCEEDS_FAIR_SHARE = auto()
    COLLECTIVE_HEADROOM_INSUFFICIENT = auto()

@dataclass(frozen=True)
class BudgetClaim:
    agent_id: str
    claimed_amount: float
    fairness_allocation: float
    collective_usage_current: float
    collective_usage_limit: float

@dataclass(frozen=True)
class CooperativePolicy:
    require_claims: bool
    max_burst_ratio: float

@dataclass(frozen=True)
class CooperativeManifest:
    verdict: CooperativeVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_claim(
        cls, claim: BudgetClaim, policy: CooperativePolicy
    ) -> CooperativeManifest:
        
        # Gate 1: Claims not required
        if not policy.require_claims:
            digest = cls._hash(json.dumps({
                "agent": claim.agent_id,
                "claims": "NOT_REQUIRED"
            }, sort_keys=True))
            return CooperativeManifest(
                verdict=CooperativeVerdict.SINGLE_AGENT,
                directive=f"PROCEED: Cooperative claims not required.",
                manifest_digest=digest
            )

        # Gate 2: Fair share check
        if claim.claimed_amount > claim.fairness_allocation:
            return CooperativeManifest(
                verdict=CooperativeVerdict.CLAIM_EXCEEDS_FAIR_SHARE,
                directive=f"HALT: Agent {claim.agent_id} claims {claim.claimed_amount:.2f} > fair share {claim.fairness_allocation:.2f}.",
                manifest_digest=cls._hash(f"OVER_FAIR:{claim.agent_id}")
            )

        # Gate 3: Collective headroom
        remaining = claim.collective_usage_limit - claim.collective_usage_current
        if claim.claimed_amount > remaining:
            return CooperativeManifest(
                verdict=CooperativeVerdict.COLLECTIVE_HEADROOM_INSUFFICIENT,
                directive=f"HALT: Claim {claim.claimed_amount:.2f} > remaining headroom {remaining:.2f}.",
                manifest_digest=cls._hash(f"NO_HEADROOM:{remaining:.2f}")
            )

        # Gate 4: Verified
        digest = cls._hash(json.dumps({
            "agent": claim.agent_id,
            "claimed": f"{claim.claimed_amount:.2f}",
            "fair_share": f"{claim.fairness_allocation:.2f}",
            "headroom": f"{remaining:.2f}"
        }, sort_keys=True))
        
        return CooperativeManifest(
            verdict=CooperativeVerdict.CLAIM_VERIFIED,
            directive=f"PROCEED: Claim {claim.claimed_amount:.2f} within fair share and headroom.",
            manifest_digest=digest
        )