# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-handle-cold-storage-retrieval-that-exceeds-its-operational-timeout.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-handle-cold-storage-retrieval-that-exceeds-its-operational-timeout.warrant.json
# Markdown SHA-256:   65f2add131df7b2f874a2687a782122b0f542ef7485fd3a5c88e3eb876ac0d90
# Code AST SHA-256:   b70b5e2809da8faa802f3d07ab0a6f7331504f09d43f741dd7ab6f50bf3fb821
# Verified Classes:   RetrievalVerdict, StorageRequest, RetrievalPolicy, RetrievalManifest, ColdStorageRetrievalGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class RetrievalVerdict(Enum):
    HOT_STORAGE = auto()
    BLOCKING_RETRIEVAL_OK = auto()
    ASYNC_RETRIEVAL_REQUIRED = auto()
    SLA_WILL_BE_MISSED = auto()

@dataclass(frozen=True)
class StorageRequest:
    data_id: str
    storage_tier: str
    estimated_retrieval_sec: float
    session_operational_timeout_sec: float
    operation_has_strict_sla: bool
    async_notification_available: bool

@dataclass(frozen=True)
class RetrievalPolicy:
    sla_buffer_sec: float

@dataclass(frozen=True)
class RetrievalManifest:
    verdict: RetrievalVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_request(
        cls, request: StorageRequest, policy: RetrievalPolicy
    ) -> RetrievalManifest:
        
        # Gate 1: Hot storage
        if request.storage_tier == "HOT":
            digest = cls._hash(json.dumps({
                "data": request.data_id,
                "tier": "HOT"
            }, sort_keys=True))
            return RetrievalManifest(
                verdict=RetrievalVerdict.HOT_STORAGE,
                directive=f"PROCEED: Hot storage retrieval for {request.data_id}.",
                manifest_digest=digest
            )

        # Gate 2: Blocking OK
        if request.estimated_retrieval_sec <= request.session_operational_timeout_sec:
            digest = cls._hash(json.dumps({
                "data": request.data_id,
                "tier": request.storage_tier,
                "retrieval": f"{request.estimated_retrieval_sec:.0f}",
                "timeout": f"{request.session_operational_timeout_sec:.0f}"
            }, sort_keys=True))
            return RetrievalManifest(
                verdict=RetrievalVerdict.BLOCKING_RETRIEVAL_OK,
                directive=f"PROCEED: Retrieval {request.estimated_retrieval_sec:.0f}s within timeout {request.session_operational_timeout_sec:.0f}s.",
                manifest_digest=digest
            )

        # Gate 3: SLA will be missed
        if request.operation_has_strict_sla:
            sla_deadline = request.session_operational_timeout_sec - policy.sla_buffer_sec
            if request.estimated_retrieval_sec > sla_deadline:
                return RetrievalManifest(
                    verdict=RetrievalVerdict.SLA_WILL_BE_MISSED,
                    directive=f"HALT: Retrieval {request.estimated_retrieval_sec:.0f}s > SLA deadline {sla_deadline:.0f}s. Escalate or use alternative.",
                    manifest_digest=cls._hash(f"SLA_MISS:{request.data_id}")
                )

        # Gate 4: Async required
        if request.async_notification_available:
            digest = cls._hash(json.dumps({
                "data": request.data_id,
                "tier": request.storage_tier,
                "mode": "ASYNC",
                "retrieval": f"{request.estimated_retrieval_sec:.0f}"
            }, sort_keys=True))
            return RetrievalManifest(
                verdict=RetrievalVerdict.ASYNC_RETRIEVAL_REQUIRED,
                directive=f"ACTION: Issue async retrieval, terminate. Successor picks up after {request.estimated_retrieval_sec:.0f}s.",
                manifest_digest=digest
            )

        return RetrievalManifest(
            verdict=RetrievalVerdict.SLA_WILL_BE_MISSED,
            directive=f"HALT: Retrieval {request.estimated_retrieval_sec:.0f}s > timeout, no async notification available.",
            manifest_digest=cls._hash(f"NO_ASYNC:{request.data_id}")
        )