# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-distributed-rate-limit-invariants-prevent-agents-from-collectively-exceeding-shared-api-quotas.md
# Remnant Warrant:    https://corpusfetch.com/c/what-distributed-rate-limit-invariants-prevent-agents-from-collectively-exceeding-shared-api-quotas.warrant.json
# Markdown SHA-256:   d0da3111ed7082bfdee89c1c1d3703d349094ba222da7c40753ef53119f4bc68
# Code AST SHA-256:   67d13b4afc01bba562b222fe3203f15cbcc100412eb00b52c28a9f6f36844399
# Verified Classes:   QuotaVerdict, SharedQuotaState, QuotaPolicy, QuotaManifest, DistributedRateLimitGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class QuotaVerdict(Enum):
    DEDICATED_QUOTA = auto()
    WITHIN_FAIR_SHARE = auto()
    EXCEEDS_FAIR_SHARE = auto()
    INSUFFICIENT_AGGREGATE_HEADROOM = auto()

@dataclass(frozen=True)
class SharedQuotaState:
    shared_quota_limit: float
    aggregate_consumed: float
    active_session_count: int
    session_planned_usage: float
    receipt_freshness_sec: float

@dataclass(frozen=True)
class QuotaPolicy:
    max_receipt_staleness_sec: float
    fairness_weight: float  # 1.0 = equal shares, <1 = lenient, >1 = stricter

@dataclass(frozen=True)
class QuotaManifest:
    verdict: QuotaVerdict
    fair_share: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_usage(
        cls, state: SharedQuotaState, policy: QuotaPolicy
    ) -> QuotaManifest:
        
        # Gate 1: Receipt freshness
        if state.receipt_freshness_sec > policy.max_receipt_staleness_sec:
            return QuotaManifest(
                verdict=QuotaVerdict.INSUFFICIENT_AGGREGATE_HEADROOM,
                fair_share=0.0,
                directive=f"HALT: Aggregate receipt {state.receipt_freshness_sec:.0f}s stale.",
                manifest_digest=cls._hash(f"STALE:{state.receipt_freshness_sec:.0f}")
            )

        # Gate 2: Fair share computation
        if state.active_session_count <= 0:
            fair_share = state.shared_quota_limit
        else:
            fair_share = (state.shared_quota_limit / state.active_session_count) * policy.fairness_weight

        # Gate 3: Fair share check
        if state.session_planned_usage > fair_share:
            return QuotaManifest(
                verdict=QuotaVerdict.EXCEEDS_FAIR_SHARE,
                fair_share=fair_share,
                directive=f"THROTTLE: Planned {state.session_planned_usage:.0f} > fair share {fair_share:.0f}.",
                manifest_digest=cls._hash(f"EXCEED_FAIR:{state.session_planned_usage:.0f}")
            )

        # Gate 4: Aggregate headroom
        remaining = state.shared_quota_limit - state.aggregate_consumed
        if state.session_planned_usage > remaining:
            return QuotaManifest(
                verdict=QuotaVerdict.INSUFFICIENT_AGGREGATE_HEADROOM,
                fair_share=fair_share,
                directive=f"HALT: Planned {state.session_planned_usage:.0f} > headroom {remaining:.0f}.",
                manifest_digest=cls._hash(f"NO_HEADROOM:{remaining:.0f}")
            )

        # Gate 5: Within bounds
        digest = cls._hash(json.dumps({
            "fair_share": f"{fair_share:.1f}",
            "remaining": f"{remaining:.1f}",
            "planned": f"{state.session_planned_usage:.1f}",
            "sessions": str(state.active_session_count)
        }, sort_keys=True))
        
        return QuotaManifest(
            verdict=QuotaVerdict.WITHIN_FAIR_SHARE,
            fair_share=fair_share,
            directive=f"PROCEED: Planned {state.session_planned_usage:.0f} within fair share {fair_share:.0f}.",
            manifest_digest=digest
        )