# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-must-survive-when-shared-vocabulary-drifts-between-agent-generations.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-must-survive-when-shared-vocabulary-drifts-between-agent-generations.warrant.json
# Markdown SHA-256:   7375c6bda426f54ee82eb49b7f4cbfcd7eb21bf704d8c814d1585f79e32fbe99
# Code AST SHA-256:   60730bc2f836b0a8229d5975616f5633560e070d4d8b8cb94ad7222d61a09e7a
# Verified Classes:   VocabularyVerdict, TermUsage, VocabularyMessage, VocabularyPolicy, VocabularyManifest, VocabularyDriftGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class VocabularyVerdict(Enum):
    SAME_GENERATION = auto()
    MAPPED_DRIFT = auto()
    UNMAPPED_DRIFT = auto()
    NO_VOCABULARY_DEPENDENCY = auto()

@dataclass(frozen=True)
class TermUsage:
    term: str
    semantic_fingerprint: str

@dataclass(frozen=True)
class VocabularyMessage:
    message_id: str
    sender_generation: str
    receiver_generation: str
    used_terms: tuple[TermUsage, ...]
    term_mapping_available: dict[str, str]  # term -> mapped definition fingerprint

@dataclass(frozen=True)
class VocabularyPolicy:
    require_mapping_on_drift: bool

@dataclass(frozen=True)
class VocabularyManifest:
    verdict: VocabularyVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_message(
        cls, msg: VocabularyMessage, policy: VocabularyPolicy
    ) -> VocabularyManifest:
        
        # Gate 1: No vocabulary dependency
        if not msg.used_terms:
            digest = cls._hash(json.dumps({
                "message": msg.message_id,
                "terms": "NONE"
            }, sort_keys=True))
            return VocabularyManifest(
                verdict=VocabularyVerdict.NO_VOCABULARY_DEPENDENCY,
                directive=f"PROCEED: Message {msg.message_id} has no vocabulary terms.",
                manifest_digest=digest
            )

        # Gate 2: Same generation
        if msg.sender_generation == msg.receiver_generation:
            digest = cls._hash(json.dumps({
                "message": msg.message_id,
                "generation": msg.sender_generation,
                "terms": tuple(t.term for t in msg.used_terms)
            }, sort_keys=True))
            return VocabularyManifest(
                verdict=VocabularyVerdict.SAME_GENERATION,
                directive=f"PROCEED: Same generation {msg.sender_generation}.",
                manifest_digest=digest
            )

        # Gate 3: Mapping coverage
        unmapped_terms = []
        for term_usage in msg.used_terms:
            if term_usage.term not in msg.term_mapping_available:
                unmapped_terms.append(term_usage.term)

        if unmapped_terms:
            if policy.require_mapping_on_drift:
                return VocabularyManifest(
                    verdict=VocabularyVerdict.UNMAPPED_DRIFT,
                    directive=f"HALT: {len(unmapped_terms)} terms unmapped between {msg.sender_generation} and {msg.receiver_generation}.",
                    manifest_digest=cls._hash(f"UNMAPPED:{len(unmapped_terms)}")
                )

        # Gate 4: Mapped drift
        digest = cls._hash(json.dumps({
            "message": msg.message_id,
            "from": msg.sender_generation,
            "to": msg.receiver_generation,
            "terms": tuple(t.term for t in msg.used_terms),
            "mappings": tuple(sorted(msg.term_mapping_available.keys()))
        }, sort_keys=True))
        
        return VocabularyManifest(
            verdict=VocabularyVerdict.MAPPED_DRIFT,
            directive=f"PROCEED: Drift mapped for {len(msg.used_terms)} terms.",
            manifest_digest=digest
        )