# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-archive-unhandled-edge-cases-when-time-budgets-expire.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-archive-unhandled-edge-cases-when-time-budgets-expire.warrant.json
# Markdown SHA-256:   2fd83b34024aefd6fe24f0e959fb57cfe87e7a27f88db99636990b744db58e52
# Code AST SHA-256:   66b61b0d348366df3df8caafac9ba778fc03919fb8515eaf0c55a4bf495410c7
# Verified Classes:   EdgeCaseStatus, EdgeCaseCandidate, TimeBudgetFrontier, TimeBudgetArchiver
# Defensive Guards:   3 fail-closed invariants (zero external deps)

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


class EdgeCaseStatus(Enum):
    UNEXPLORED = auto()
    PARTIALLY_TESTED = auto()
    RESOLVED = auto()
    UNREACHABLE = auto()


@dataclass(frozen=True)
class EdgeCaseCandidate:
    case_id: str
    input_signature: str
    status: EdgeCaseStatus
    partial_state: str | None = None


@dataclass(frozen=True)
class TimeBudgetFrontier:
    unresolved_cases: tuple[EdgeCaseCandidate, ...]
    next_probe_heuristic: str
    expiry_epoch: float
    frontier_digest: str


class TimeBudgetArchiver:
    """
    Evaluates interrupted session state to extract a resumable frontier of
    unhandled edge cases when a time budget expires.
    """

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

    @classmethod
    def archive_timeout(
        cls,
        candidates: tuple[EdgeCaseCandidate, ...],
        next_probe_heuristic: str,
        expiry_epoch: float,
    ) -> TimeBudgetFrontier:
        
        unresolved: list[EdgeCaseCandidate] = []

        for candidate in candidates:
            if candidate.status in (EdgeCaseStatus.UNEXPLORED, EdgeCaseStatus.PARTIALLY_TESTED):
                unresolved.append(candidate)
                
        if not unresolved:
            raise ValueError("Cannot archive a timeout frontier with zero unresolved cases.")

        if not next_probe_heuristic.strip():
            raise ValueError("Next probe heuristic must be explicitly declared for the successor.")

        digest_payload = {
            "unresolved_ids": tuple(sorted(c.case_id for c in unresolved)),
            "next_probe": next_probe_heuristic,
            "expiry": str(expiry_epoch),
        }
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return TimeBudgetFrontier(
            unresolved_cases=tuple(unresolved),
            next_probe_heuristic=next_probe_heuristic,
            expiry_epoch=expiry_epoch,
            frontier_digest=digest,
        )

    @classmethod
    def resume_frontier(
        cls, frontier: TimeBudgetFrontier
    ) -> tuple[tuple[EdgeCaseCandidate, ...], str]:
        """
        Fetching-time check: confirms the frontier is valid and returns the
        unresolved cases alongside the interrupted probe heuristic.
        """
        if frontier.expiry_epoch > time.time():
            raise ValueError("Cannot resume a frontier that has not yet expired.")
            
        return frontier.unresolved_cases, frontier.next_probe_heuristic