# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-communication-invariants-must-survive-when-agents-speak-different-protocol-versions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-communication-invariants-must-survive-when-agents-speak-different-protocol-versions.warrant.json
# Markdown SHA-256:   c5cfdac1e787b1221fc5069c857426bdb656b89cd3058ec25a5f75cd2046b257
# Code AST SHA-256:   834dcd2cf221eaa2d1a8bf3750f3c2dd1b3c09e52ddb8ba0a779947b6122e76b
# Verified Classes:   ProtocolCompatVerdict, VersionPair, FieldDelta, CompatibilityProfile, CompatManifest, ProtocolVersionGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ProtocolCompatVerdict(Enum):
    SAME_VERSION = auto()
    COMPATIBLE_WITH_PROFILE = auto()
    SEMANTIC_DRIFT_DETECTED = auto()
    CONSTRAINT_VIOLATION = auto()

@dataclass(frozen=True)
class VersionPair:
    sender_version: str
    receiver_version: str

@dataclass(frozen=True)
class FieldDelta:
    field_name: str
    sender_meaning: str
    receiver_meaning: str
    constraint_changed: bool

@dataclass(frozen=True)
class CompatibilityProfile:
    profile_hash: str
    known_deltas: tuple[FieldDelta, ...]

@dataclass(frozen=True)
class CompatManifest:
    verdict: ProtocolCompatVerdict
    drift_fields: tuple[str, ...]
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_compatibility(
        cls, pair: VersionPair, profile: CompatibilityProfile
    ) -> CompatManifest:
        
        # Gate 1: Same version
        if pair.sender_version == pair.receiver_version:
            digest = cls._hash(json.dumps({
                "version": pair.sender_version
            }, sort_keys=True))
            return CompatManifest(
                verdict=ProtocolCompatVerdict.SAME_VERSION,
                drift_fields=tuple(),
                directive="PROCEED: Same protocol version.",
                manifest_digest=digest
            )

        # Gate 2: Profile hash presence
        if not profile.profile_hash:
            return CompatManifest(
                verdict=ProtocolCompatVerdict.SEMANTIC_DRIFT_DETECTED,
                drift_fields=tuple(),
                directive="HALT: No compatibility profile. Cannot verify cross-version safety.",
                manifest_digest=cls._hash("NO_PROFILE")
            )

        # Gate 3: Semantic drift
        drift_fields = tuple(
            d.field_name for d in profile.known_deltas
            if d.sender_meaning != d.receiver_meaning
        )
        if drift_fields:
            return CompatManifest(
                verdict=ProtocolCompatVerdict.SEMANTIC_DRIFT_DETECTED,
                drift_fields=drift_fields,
                directive=f"HALT: Semantic drift in fields {drift_fields}.",
                manifest_digest=cls._hash(f"DRIFT:{','.join(drift_fields)}")
            )

        # Gate 4: Constraint violations
        constraint_fields = tuple(
            d.field_name for d in profile.known_deltas if d.constraint_changed
        )
        if constraint_fields:
            return CompatManifest(
                verdict=ProtocolCompatVerdict.CONSTRAINT_VIOLATION,
                drift_fields=constraint_fields,
                directive=f"HALT: Constraint changes in fields {constraint_fields}.",
                manifest_digest=cls._hash(f"CONSTRAINT:{','.join(constraint_fields)}")
            )

        # Gate 5: Compatible
        digest = cls._hash(json.dumps({
            "sender": pair.sender_version,
            "receiver": pair.receiver_version,
            "profile": profile.profile_hash
        }, sort_keys=True))
        
        return CompatManifest(
            verdict=ProtocolCompatVerdict.COMPATIBLE_WITH_PROFILE,
            drift_fields=tuple(),
            directive=f"PROCEED: Cross-version compatible via profile {profile.profile_hash}.",
            manifest_digest=digest
        )