# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-mask-cold-start-latency-without-hiding-behavioral-differences.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-mask-cold-start-latency-without-hiding-behavioral-differences.warrant.json
# Markdown SHA-256:   bf0995dc720fbface0834663f9d210ca5553c770a101eaa166cab7234f92d843
# Code AST SHA-256:   bfc73a35042a134a63b627344470a7cf26f150d9d943cede213baa5e28e4135a
# Verified Classes:   ColdStartVerdict, InferenceResponse, ColdStartPolicy, ColdStartManifest, ColdStartMaskingGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ColdStartVerdict(Enum):
    WARM_PATH = auto()
    COLD_PATH_MASKED = auto()
    COLD_PATH_CACHE_ADMISSION_BLOCKED = auto()
    COLD_PATH_UNFLAGGED = auto()

@dataclass(frozen=True)
class InferenceResponse:
    response_id: str
    cold_start_flag: bool
    cold_start_flag_receipt: str | None
    cache_admission_requested: bool
    cache_admission_authorized: bool

@dataclass(frozen=True)
class ColdStartPolicy:
    require_flag: bool
    require_cache_block: bool

@dataclass(frozen=True)
class ColdStartManifest:
    verdict: ColdStartVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_response(
        cls, response: InferenceResponse, policy: ColdStartPolicy
    ) -> ColdStartManifest:
        
        # Gate 1: Warm path
        if not response.cold_start_flag:
            digest = cls._hash(json.dumps({
                "response": response.response_id,
                "path": "WARM"
            }, sort_keys=True))
            return ColdStartManifest(
                verdict=ColdStartVerdict.WARM_PATH,
                directive=f"PROCEED: Response {response.response_id} from warm path.",
                manifest_digest=digest
            )

        # Gate 2: Flag receipt
        if policy.require_flag and not response.cold_start_flag_receipt:
            return ColdStartManifest(
                verdict=ColdStartVerdict.COLD_PATH_UNFLAGGED,
                directive=f"HALT: Cold-path response {response.response_id} lacks flag receipt.",
                manifest_digest=cls._hash(f"NO_FLAG:{response.response_id}")
            )

        # Gate 3: Cache admission block
        if policy.require_cache_block and response.cache_admission_requested:
            if not response.cache_admission_authorized:
                return ColdStartManifest(
                    verdict=ColdStartVerdict.COLD_PATH_CACHE_ADMISSION_BLOCKED,
                    directive=f"BLOCK: Cold-path response {response.response_id} cache admission not authorized.",
                    manifest_digest=cls._hash(f"CACHE_BLOCK:{response.response_id}")
                )

        # Gate 4: Masked
        digest = cls._hash(json.dumps({
            "response": response.response_id,
            "flag": "COLD",
            "flag_receipt": response.cold_start_flag_receipt,
            "cache_admitted": str(response.cache_admission_authorized)
        }, sort_keys=True))
        
        return ColdStartManifest(
            verdict=ColdStartVerdict.COLD_PATH_MASKED,
            directive=f"PROCEED: Cold-path response {response.response_id} masked with flag.",
            manifest_digest=digest
        )