# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-tool-result-caches-invalidate-across-tool-generation-changes.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-tool-result-caches-invalidate-across-tool-generation-changes.warrant.json
# Markdown SHA-256:   85945e5d026152138b997f790c07871c4df6eaec6297da2241efcac44cd2bd5d
# Code AST SHA-256:   44f0c1d6b0e05f58ca80e35145a27597619c20289d3f5d21292d368d90b847cc
# Verified Classes:   CacheVerdict, ToolCacheEntry, ToolCachePolicy, ToolCacheManifest, ToolGenerationCacheGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CacheVerdict(Enum):
    NO_CACHE = auto()
    GENERATION_VERIFIED = auto()
    STALE_GENERATION = auto()
    NO_GENERATION_SIGNATURE = auto()

@dataclass(frozen=True)
class ToolCacheEntry:
    cache_key: str
    cached_generation: str | None
    current_tool_generation: str
    compatible_across_generations: bool

@dataclass(frozen=True)
class ToolCachePolicy:
    require_generation_signature: bool

@dataclass(frozen=True)
class ToolCacheManifest:
    verdict: CacheVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_cache_hit(
        cls, entry: ToolCacheEntry, policy: ToolCachePolicy
    ) -> ToolCacheManifest:
        
        # Gate 1: No cache entry
        if not entry.cache_key:
            digest = cls._hash(json.dumps({
                "cache": "MISS"
            }, sort_keys=True))
            return ToolCacheManifest(
                verdict=CacheVerdict.NO_CACHE,
                directive="PROCEED: Cache miss, execute tool.",
                manifest_digest=digest
            )

        # Gate 2: Generation signature presence
        if policy.require_generation_signature and not entry.cached_generation:
            return ToolCacheManifest(
                verdict=CacheVerdict.NO_GENERATION_SIGNATURE,
                directive=f"HALT: Cache entry {entry.cache_key} lacks generation signature.",
                manifest_digest=cls._hash(f"NO_GEN:{entry.cache_key}")
            )

        # Gate 3: Compatible across generations
        if entry.compatible_across_generations:
            digest = cls._hash(json.dumps({
                "cache": entry.cache_key,
                "compatible": "TRUE"
            }, sort_keys=True))
            return ToolCacheManifest(
                verdict=CacheVerdict.GENERATION_VERIFIED,
                directive=f"PROCEED: Cache {entry.cache_key} cross-generation compatible.",
                manifest_digest=digest
            )

        # Gate 4: Generation drift
        if entry.cached_generation and entry.cached_generation != entry.current_tool_generation:
            return ToolCacheManifest(
                verdict=CacheVerdict.STALE_GENERATION,
                directive=f"HALT: Cache {entry.cache_key} generation {entry.cached_generation} != current {entry.current_tool_generation}.",
                manifest_digest=cls._hash(f"STALE:{entry.cache_key}")
            )

        # Gate 5: Verified
        digest = cls._hash(json.dumps({
            "cache": entry.cache_key,
            "generation": entry.current_tool_generation
        }, sort_keys=True))
        
        return ToolCacheManifest(
            verdict=CacheVerdict.GENERATION_VERIFIED,
            directive=f"PROCEED: Cache {entry.cache_key} verified for current generation.",
            manifest_digest=digest
        )