# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-cryptographic-identity-proofs-must-survive-an-escrow-agents-sudden-liquidation.md
# Remnant Warrant:    https://corpusfetch.com/c/what-cryptographic-identity-proofs-must-survive-an-escrow-agents-sudden-liquidation.warrant.json
# Markdown SHA-256:   133789e6d2123f9c10b2e5c021514170128d6d68d5f7469a094944619efd5d75
# Code AST SHA-256:   8b7db160a43a5778fd06ad7b4362ec620d3e0f17be095061d0fbffb052f64d3a
# Verified Classes:   LiquidationVerdict, EscrowAgentState, LiquidationPolicy, LiquidationManifest, LiquidationSuccessorGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class LiquidationVerdict(Enum):
    ESCROW_ACTIVE = auto()
    LIQUIDATION_TRIGGERED = auto()
    SUCCESSOR_VERIFIED = auto()
    NO_SUCCESSOR_DESIGNATED = auto()

@dataclass(frozen=True)
class EscrowAgentState:
    agent_active: bool
    liquidation_trigger_receipt: str | None
    successor_public_key: str | None
    time_locked_switch_hash: str | None
    last_heartbeat_epoch: float

@dataclass(frozen=True)
class LiquidationPolicy:
    current_epoch: float
    heartbeat_timeout_sec: float

@dataclass(frozen=True)
class LiquidationManifest:
    verdict: LiquidationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_state(
        cls, state: EscrowAgentState, policy: LiquidationPolicy
    ) -> LiquidationManifest:
        
        # Gate 1: No successor designated
        if not state.successor_public_key:
            return LiquidationManifest(
                verdict=LiquidationVerdict.NO_SUCCESSOR_DESIGNATED,
                directive="HALT: No successor public key. Liquidated escrows require manual recovery.",
                manifest_digest=cls._hash("NO_SUCCESSOR")
            )

        # Gate 2: Agent still active
        heartbeat_age = policy.current_epoch - state.last_heartbeat_epoch
        if state.agent_active and heartbeat_age < policy.heartbeat_timeout_sec:
            digest = cls._hash(json.dumps({
                "agent": "ACTIVE",
                "heartbeat_age": f"{heartbeat_age:.1f}"
            }, sort_keys=True))
            return LiquidationManifest(
                verdict=LiquidationVerdict.ESCROW_ACTIVE,
                directive="PROCEED: Agent is active. Escrow continues normally.",
                manifest_digest=digest
            )

        # Gate 3: Liquidation triggered
        if not state.liquidation_trigger_receipt:
            return LiquidationManifest(
                verdict=LiquidationVerdict.ESCROW_ACTIVE,
                directive="WAIT: Heartbeat timeout reached but no liquidation trigger receipt. Await oracle or manual trigger.",
                manifest_digest=cls._hash(f"WAIT:{heartbeat_age:.1f}")
            )

        # Gate 4: Successor verified
        digest = cls._hash(json.dumps({
            "successor": state.successor_public_key,
            "trigger": state.liquidation_trigger_receipt,
            "switch": state.time_locked_switch_hash or "NONE"
        }, sort_keys=True))
        
        return LiquidationManifest(
            verdict=LiquidationVerdict.SUCCESSOR_VERIFIED,
            directive=f"PROCEED: Transfer obligations to successor {state.successor_public_key}.",
            manifest_digest=digest
        )