# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-must-survive-when-a-session-is-rebuilt-from-an-event-sourced-log-with-gaps.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-must-survive-when-a-session-is-rebuilt-from-an-event-sourced-log-with-gaps.warrant.json
# Markdown SHA-256:   3753c598cbc096724339b553c506d11831ecb834f1a4467c3bbe014d518b8e2f
# Code AST SHA-256:   42f1bf847c38e75688bdda5b80051f3fe104eb58bf0034d43d9a917034669b68
# Verified Classes:   GapVerdict, LogGap, EventLogState, LogPolicy, GapManifest, EventLogGapGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class GapVerdict(Enum):
    COMPLETE_LOG = auto()
    DECLARED_GAPS_ONLY = auto()
    UNDECLARED_GAPS_DETECTED = auto()
    STATE_DIVERGENCE = auto()

@dataclass(frozen=True)
class LogGap:
    start_offset: int
    end_offset: int
    declared: bool
    declaration_signature: str | None

@dataclass(frozen=True)
class EventLogState:
    min_offset: int
    max_offset: int
    gaps: tuple[LogGap, ...]
    post_replay_state_hash: str
    expected_state_hash: str

@dataclass(frozen=True)
class LogPolicy:
    require_declaration_for_gaps: bool

@dataclass(frozen=True)
class GapManifest:
    verdict: GapVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_replay(
        cls, state: EventLogState, policy: LogPolicy
    ) -> GapManifest:
        
        # Gate 1: No gaps
        if not state.gaps:
            digest = cls._hash(json.dumps({
                "min": str(state.min_offset),
                "max": str(state.max_offset),
                "gaps": "NONE"
            }, sort_keys=True))
            return GapManifest(
                verdict=GapVerdict.COMPLETE_LOG,
                directive="PROCEED: Log is complete, no gaps.",
                manifest_digest=digest
            )

        # Gate 2: Undeclared gaps
        for gap in state.gaps:
            if not gap.declared and policy.require_declaration_for_gaps:
                return GapManifest(
                    verdict=GapVerdict.UNDECLARED_GAPS_DETECTED,
                    directive=f"HALT: Undeclared gap at offsets {gap.start_offset}-{gap.end_offset}.",
                    manifest_digest=cls._hash(f"UNDECLARED:{gap.start_offset}-{gap.end_offset}")
                )

        # Gate 3: State divergence
        if state.post_replay_state_hash != state.expected_state_hash:
            return GapManifest(
                verdict=GapVerdict.STATE_DIVERGENCE,
                directive=f"HALT: Replayed state {state.post_replay_state_hash} != expected {state.expected_state_hash}.",
                manifest_digest=cls._hash(f"DIVERGED:{state.post_replay_state_hash}")
            )

        # Gate 4: Declared gaps only
        digest = cls._hash(json.dumps({
            "gaps": tuple((g.start_offset, g.end_offset) for g in state.gaps),
            "state": state.post_replay_state_hash
        }, sort_keys=True))
        
        return GapManifest(
            verdict=GapVerdict.DECLARED_GAPS_ONLY,
            directive=f"PROCEED: {len(state.gaps)} declared gaps, state verified.",
            manifest_digest=digest
        )