# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-multicast-fanout-invariants-must-survive-heterogeneous-receiver-capabilities.md
# Remnant Warrant:    https://corpusfetch.com/c/what-multicast-fanout-invariants-must-survive-heterogeneous-receiver-capabilities.warrant.json
# Markdown SHA-256:   3f7b9186bf6db70a06190a786468f214d8444794042fc9ee5e855607e3a63467
# Code AST SHA-256:   2ddef0fae571078714339022addcc332b4b119dd3dc4da94c2f04ba2ed671a3c
# Verified Classes:   FanoutVerdict, Receiver, FanoutMessage, FanoutPolicy, FanoutManifest, MulticastHeterogeneousGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class FanoutVerdict(Enum):
    HOMOGENEOUS = auto()
    CAPABILITY_AWARE_FANOUT = auto()
    ENCODING_MISMATCH = auto()
    DELIVERY_INCOMPLETE = auto()

@dataclass(frozen=True)
class Receiver:
    receiver_id: str
    supported_versions: frozenset[str]
    buffer_size_bytes: int
    typical_processing_ms: float
    is_critical: bool

@dataclass(frozen=True)
class FanoutMessage:
    message_id: str
    size_bytes: int
    sender_version: str
    receivers: tuple[Receiver, ...]
    acknowledgment_rate: float

@dataclass(frozen=True)
class FanoutPolicy:
    min_acknowledgment_rate: float
    require_critical_acks: bool

@dataclass(frozen=True)
class FanoutManifest:
    verdict: FanoutVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_fanout(
        cls, msg: FanoutMessage, policy: FanoutPolicy
    ) -> FanoutManifest:
        
        if not msg.receivers:
            return FanoutManifest(
                verdict=FanoutVerdict.DELIVERY_INCOMPLETE,
                directive="HALT: No receivers.",
                manifest_digest=cls._hash("NO_RECEIVERS")
            )

        # Gate 1: Homogeneous check
        version_sets = {r.supported_versions for r in msg.receivers}
        buffer_sizes = {r.buffer_size_bytes for r in msg.receivers}
        if len(version_sets) == 1 and len(buffer_sizes) == 1:
            digest = cls._hash(json.dumps({
                "message": msg.message_id,
                "version": msg.sender_version
            }, sort_keys=True))
            return FanoutManifest(
                verdict=FanoutVerdict.HOMOGENEOUS,
                directive=f"PROCEED: Homogeneous receivers, standard multicast.",
                manifest_digest=digest
            )

        # Gate 2: Version compatibility
        incompatible = [r.receiver_id for r in msg.receivers if msg.sender_version not in r.supported_versions]
        if incompatible:
            return FanoutManifest(
                verdict=FanoutVerdict.ENCODING_MISMATCH,
                directive=f"HALT: {len(incompatible)} receivers do not support {msg.sender_version}.",
                manifest_digest=cls._hash(f"VERSION_MISMATCH:{len(incompatible)}")
            )

        # Gate 3: Buffer size check
        undersized = [r.receiver_id for r in msg.receivers if r.buffer_size_bytes < msg.size_bytes]
        if undersized:
            return FanoutManifest(
                verdict=FanoutVerdict.ENCODING_MISMATCH,
                directive=f"ACTION: {len(undersized)} receivers have smaller buffers than message size. Chunk required.",
                manifest_digest=cls._hash(f"SMALL_BUFFER:{len(undersized)}")
            )

        # Gate 4: Acknowledgment
        if msg.acknowledgment_rate < policy.min_acknowledgment_rate:
            return FanoutManifest(
                verdict=FanoutVerdict.DELIVERY_INCOMPLETE,
                directive=f"HALT: Ack rate {msg.acknowledgment_rate:.2%} < {policy.min_acknowledgment_rate:.2%}.",
                manifest_digest=cls._hash(f"LOW_ACK:{msg.acknowledgment_rate:.3f}")
            )

        # Gate 5: Capability-aware fanout
        digest = cls._hash(json.dumps({
            "message": msg.message_id,
            "receivers": tuple(sorted(r.receiver_id for r in msg.receivers)),
            "versions": tuple(sorted(str(v) for v in version_sets)),
            "ack_rate": f"{msg.acknowledgment_rate:.3f}"
        }, sort_keys=True))
        
        return FanoutManifest(
            verdict=FanoutVerdict.CAPABILITY_AWARE_FANOUT,
            directive=f"PROCEED: {len(msg.receivers)} receivers with varied capabilities, {msg.acknowledgment_rate:.1%} ack.",
            manifest_digest=digest
        )