# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-record-memory-state-after-a-jvm-gc-pause-that-exceeded-the-heartbeat-window.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-record-memory-state-after-a-jvm-gc-pause-that-exceeded-the-heartbeat-window.warrant.json
# Markdown SHA-256:   43b50299116249d668e4d3a9813a6c948e4f1c7cb5df30cbb2ee358e14d289ba
# Code AST SHA-256:   e694442b7e9c51ea10afdf4a0452e73349d3645c48560e01d508e821d61ff5e7
# Verified Classes:   GCPauseVerdict, GCPauseState, GCPolicy, GCPauseManifest, GCPauseGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class GCPauseVerdict(Enum):
    NO_MISSED_HEARTBEAT = auto()
    PAUSED_BUT_ALIVE = auto()
    GENUINE_FAILURE = auto()
    STATE_MUTATED_DURING_PAUSE = auto()

@dataclass(frozen=True)
class GCPauseState:
    missed_heartbeats: int
    gc_pause_start_epoch: float | None
    gc_pause_end_epoch: float | None
    pre_pause_state_hash: str | None
    post_pause_state_hash: str | None
    fencing_token_issued_epoch: float | None

@dataclass(frozen=True)
class GCPolicy:
    heartbeat_interval_sec: float
    failover_grace_multiplier: float

@dataclass(frozen=True)
class GCPauseManifest:
    verdict: GCPauseVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_pause(
        cls, state: GCPauseState, policy: GCPolicy
    ) -> GCPauseManifest:
        
        # Gate 1: No missed heartbeats
        if state.missed_heartbeats == 0:
            digest = cls._hash(json.dumps({
                "missed": "0",
                "status": "HEALTHY"
            }, sort_keys=True))
            return GCPauseManifest(
                verdict=GCPauseVerdict.NO_MISSED_HEARTBEAT,
                directive="PROCEED: No missed heartbeats.",
                manifest_digest=digest
            )

        # Gate 2: GC pause evidence
        if state.gc_pause_start_epoch is not None and state.gc_pause_end_epoch is not None:
            pause_duration = state.gc_pause_end_epoch - state.gc_pause_start_epoch
            max_grace = policy.heartbeat_interval_sec * policy.failover_grace_multiplier

            if state.pre_pause_state_hash and state.post_pause_state_hash:
                if state.pre_pause_state_hash != state.post_pause_state_hash:
                    return GCPauseManifest(
                        verdict=GCPauseVerdict.STATE_MUTATED_DURING_PAUSE,
                        directive=f"HALT: State hash changed during GC pause ({pause_duration:.1f}s). Unexpected mutation.",
                        manifest_digest=cls._hash(f"MUTATED:{pause_duration:.1f}")
                    )

            if pause_duration > max_grace:
                return GCPauseManifest(
                    verdict=GCPauseVerdict.PAUSED_BUT_ALIVE,
                    directive=f"HALT_FAILOVER: GC pause {pause_duration:.1f}s > grace {max_grace:.1f}s. Pause verified, but original alive. Fence before replacing.",
                    manifest_digest=cls._hash(f"LONG_PAUSE:{pause_duration:.1f}")
                )

            digest = cls._hash(json.dumps({
                "missed": str(state.missed_heartbeats),
                "pause_duration": f"{pause_duration:.1f}",
                "status": "PAUSED_ALIVE"
            }, sort_keys=True))
            return GCPauseManifest(
                verdict=GCPauseVerdict.PAUSED_BUT_ALIVE,
                directive=f"PROCEED_WITH_CAUTION: Paused for {pause_duration:.1f}s, resumed. Treat as alive.",
                manifest_digest=digest
            )

        # Gate 3: Genuine failure
        return GCPauseManifest(
            verdict=GCPauseVerdict.GENUINE_FAILURE,
            directive=f"HALT: {state.missed_heartbeats} missed heartbeats, no GC pause evidence. Treat as failed.",
            manifest_digest=cls._hash(f"FAILURE:{state.missed_heartbeats}")
        )