# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-detect-silent-context-window-truncation-by-an-upstream-proxy.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-detect-silent-context-window-truncation-by-an-upstream-proxy.warrant.json
# Markdown SHA-256:   d44228a66c1a78f8d342d902b054a1cbfdab0d4a0c023b56bbc3bd1f74d86140
# Code AST SHA-256:   2ea3258fd5a2e4fff15286cc24dd053668d6ee2ef0b192c98872dcd1bc1b4adc
# Verified Classes:   TruncationVerdict, ProxyContextState, TruncationPolicy, TruncationManifest, ProxyTruncationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class TruncationVerdict(Enum):
    NO_TRUNCATION_VERIFIED = auto()
    TRUNCATION_SUSPECTED = auto()
    TRUNCATION_CONFIRMED = auto()

@dataclass(frozen=True)
class ProxyContextState:
    prompt_hash_sent: str
    prompt_hash_received: str | None
    prompt_token_count: int
    proxy_context_limit_tokens: int

@dataclass(frozen=True)
class TruncationPolicy:
    require_receipt: bool
    max_acceptable_ratio: float

@dataclass(frozen=True)
class TruncationManifest:
    verdict: TruncationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_prompt(
        cls, state: ProxyContextState, policy: TruncationPolicy
    ) -> TruncationManifest:
        
        # Gate 1: Prompt within proxy limit
        if state.prompt_token_count <= state.proxy_context_limit_tokens:
            if state.prompt_hash_received and state.prompt_hash_sent != state.prompt_hash_received:
                return TruncationManifest(
                    verdict=TruncationVerdict.TRUNCATION_CONFIRMED,
                    directive="HALT: Prompt within limit but hash mismatch. Silent truncation.",
                    manifest_digest=cls._hash(f"MISMATCH:{state.prompt_hash_sent}")
                )
            digest = cls._hash(json.dumps({
                "sent": state.prompt_hash_sent,
                "tokens": str(state.prompt_token_count),
                "limit": str(state.proxy_context_limit_tokens)
            }, sort_keys=True))
            return TruncationManifest(
                verdict=TruncationVerdict.NO_TRUNCATION_VERIFIED,
                directive="PROCEED: Prompt within proxy limit.",
                manifest_digest=digest
            )

        # Gate 2: Prompt exceeds proxy limit
        ratio = state.prompt_token_count / state.proxy_context_limit_tokens

        if policy.require_receipt and state.prompt_hash_received is None:
            return TruncationManifest(
                verdict=TruncationVerdict.TRUNCATION_SUSPECTED,
                directive=f"HALT: Prompt {ratio:.2f}x proxy limit, no reception hash. Cannot verify.",
                manifest_digest=cls._hash(f"NO_RECEIPT:{ratio:.2f}")
            )

        # Gate 3: Confirmed truncation
        if state.prompt_hash_received and state.prompt_hash_sent != state.prompt_hash_received:
            return TruncationManifest(
                verdict=TruncationVerdict.TRUNCATION_CONFIRMED,
                directive=f"HALT: Hash mismatch confirms truncation ({ratio:.2f}x limit).",
                manifest_digest=cls._hash(f"CONFIRMED:{ratio:.2f}")
            )

        # Gate 4: Suspected
        return TruncationManifest(
            verdict=TruncationVerdict.TRUNCATION_SUSPECTED,
            directive=f"WARN: Prompt {ratio:.2f}x proxy limit with no hash verification.",
            manifest_digest=cls._hash(f"SUSPECTED:{ratio:.2f}")
        )