# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-prevent-negative-cache-poisoning-in-agent-discovery-systems.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-prevent-negative-cache-poisoning-in-agent-discovery-systems.warrant.json
# Markdown SHA-256:   66a1178a36b97bcc791da17a7ef8f94172fae09b52df5443ca631d37489d2bd1
# Code AST SHA-256:   15c6c8c697d63f60f9a956faa774e45d0b96096093c5f7576ec77613649ae805
# Verified Classes:   NegativeCacheVerdict, NegativeCacheEntry, NegativeCachePolicy, NegativeCacheManifest, NegativeCachePoisoningGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class NegativeCacheVerdict(Enum):
    UNAUTHENTICATED_NO_CACHE = auto()
    CACHE_WRITE_ALLOWED = auto()
    CACHE_INVALIDATED = auto()
    CACHE_HIT_VALID = auto()

@dataclass(frozen=True)
class NegativeCacheEntry:
    resource_id: str
    write_epoch: float
    ttl_sec: float
    writer_was_authenticated: bool
    superseded_by_creation_event: bool

@dataclass(frozen=True)
class NegativeCachePolicy:
    current_epoch: float
    max_ttl_sec: float
    require_authentication: bool

@dataclass(frozen=True)
class NegativeCacheManifest:
    verdict: NegativeCacheVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_entry(
        cls, entry: NegativeCacheEntry, policy: NegativeCachePolicy
    ) -> NegativeCacheManifest:
        
        # Gate 1: Unauthenticated write prevention
        if policy.require_authentication and not entry.writer_was_authenticated:
            return NegativeCacheManifest(
                verdict=NegativeCacheVerdict.UNAUTHENTICATED_NO_CACHE,
                directive=f"REJECT: Unauthenticated lookup for {entry.resource_id}. Do not cache.",
                manifest_digest=cls._hash(f"UNAUTH:{entry.resource_id}")
            )

        # Gate 2: Creation event invalidation
        if entry.superseded_by_creation_event:
            return NegativeCacheManifest(
                verdict=NegativeCacheVerdict.CACHE_INVALIDATED,
                directive=f"INVALIDATE: Creation event supersedes negative cache for {entry.resource_id}.",
                manifest_digest=cls._hash(f"SUPERSEDED:{entry.resource_id}")
            )

        # Gate 3: TTL bounds
        if entry.ttl_sec > policy.max_ttl_sec:
            return NegativeCacheManifest(
                verdict=NegativeCacheVerdict.CACHE_INVALIDATED,
                directive=f"REJECT: TTL {entry.ttl_sec:.0f}s > {policy.max_ttl_sec:.0f}s. Truncate or reject.",
                manifest_digest=cls._hash(f"TTL:{entry.ttl_sec:.0f}")
            )

        # Gate 4: Cache hit
        age = policy.current_epoch - entry.write_epoch
        if age > entry.ttl_sec:
            return NegativeCacheManifest(
                verdict=NegativeCacheVerdict.CACHE_INVALIDATED,
                directive=f"EXPIRED: Entry age {age:.0f}s > TTL {entry.ttl_sec:.0f}s.",
                manifest_digest=cls._hash(f"EXPIRED:{entry.resource_id}")
            )

        # Gate 5: Valid
        digest = cls._hash(json.dumps({
            "resource": entry.resource_id,
            "age": f"{age:.0f}",
            "ttl": f"{entry.ttl_sec:.0f}",
            "authenticated": str(entry.writer_was_authenticated)
        }, sort_keys=True))
        
        return NegativeCacheManifest(
            verdict=NegativeCacheVerdict.CACHE_HIT_VALID,
            directive=f"PROCEED: Negative cache entry for {entry.resource_id} valid.",
            manifest_digest=digest
        )