# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-distributed-circuit-breakers-coordinate-to-prevent-traffic-migration-cascades.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-distributed-circuit-breakers-coordinate-to-prevent-traffic-migration-cascades.warrant.json
# Markdown SHA-256:   6f34c83547dfc0da2a0217c64204d56a39e4c45a6ef6fa97c95987f38daa89bc
# Code AST SHA-256:   63787cfcf295915f6bfd8898866d2c30bb709f5df304226b07571e373ae089ee
# Verified Classes:   BreakerVerdict, BreakerState, CoordinationPolicy, BreakerManifest, DistributedBreakerGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class BreakerVerdict(Enum):
    LOCAL_BREAKER_CLOSED = auto()
    REGION_LOCAL_OPEN = auto()
    GLOBAL_OPEN = auto()
    TRAFFIC_SHIFT_THROTTLED = auto()

@dataclass(frozen=True)
class BreakerState:
    region_id: str
    local_error_rate: float
    global_error_rate: float
    traffic_shift_incoming_rate: float
    region_capacity_ratio: float

@dataclass(frozen=True)
class CoordinationPolicy:
    global_outage_threshold: float
    local_outage_threshold: float
    max_traffic_shift_rate: float

@dataclass(frozen=True)
class BreakerManifest:
    verdict: BreakerVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_breaker(
        cls, state: BreakerState, policy: CoordinationPolicy
    ) -> BreakerManifest:
        
        # Gate 1: Local healthy
        if state.local_error_rate < policy.local_outage_threshold:
            digest = cls._hash(json.dumps({
                "region": state.region_id,
                "local_error": f"{state.local_error_rate:.3f}",
                "global_error": f"{state.global_error_rate:.3f}"
            }, sort_keys=True))
            return BreakerManifest(
                verdict=BreakerVerdict.LOCAL_BREAKER_CLOSED,
                directive=f"PROCEED: Region {state.region_id} local breaker closed.",
                manifest_digest=digest
            )

        # Gate 2: Global outage
        if state.global_error_rate >= policy.global_outage_threshold:
            digest = cls._hash(json.dumps({
                "region": state.region_id,
                "global_error": f"{state.global_error_rate:.3f}",
                "action": "GLOBAL_OPEN"
            }, sort_keys=True))
            return BreakerManifest(
                verdict=BreakerVerdict.GLOBAL_OPEN,
                directive=f"OPEN: Global outage detected ({state.global_error_rate:.2%}). All regions open.",
                manifest_digest=digest
            )

        # Gate 3: Traffic shift throttling
        if state.traffic_shift_incoming_rate > policy.max_traffic_shift_rate:
            return BreakerManifest(
                verdict=BreakerVerdict.TRAFFIC_SHIFT_THROTTLED,
                directive=f"THROTTLE: Traffic shift {state.traffic_shift_incoming_rate:.0f}/s > {policy.max_traffic_shift_rate:.0f}/s. Slow migration.",
                manifest_digest=cls._hash(f"THROTTLE:{state.region_id}")
            )

        # Gate 4: Region-local open
        digest = cls._hash(json.dumps({
            "region": state.region_id,
            "local_error": f"{state.local_error_rate:.3f}",
            "global_error": f"{state.global_error_rate:.3f}",
            "action": "REGION_LOCAL_OPEN"
        }, sort_keys=True))
        
        return BreakerManifest(
            verdict=BreakerVerdict.REGION_LOCAL_OPEN,
            directive=f"OPEN: Region {state.region_id} local-only open. Route elsewhere carefully.",
            manifest_digest=digest
        )