# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-record-timezone-and-daylight-saving-boundaries-to-prevent-temporal-collapse.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-record-timezone-and-daylight-saving-boundaries-to-prevent-temporal-collapse.warrant.json
# Markdown SHA-256:   b43d7df64c8c0b7a0031c5c4e950661b5bcf894365091af17c85eadc0ec9c5af
# Code AST SHA-256:   b4a75525637473a13dfee08d5e230dd7738504a7f44d903216a40abbf85905d9
# Verified Classes:   TemporalVerdict, TemporalEvent, TemporalContext, TemporalManifest, DSTBoundaryGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class TemporalVerdict(Enum):
    UNAMBIGUOUS_TIME = auto()
    DST_AMBIGUITY_RESOLVED = auto()
    DST_AMBIGUITY_UNRESOLVED = auto()
    MISSING_HOUR_DETECTED = auto()

@dataclass(frozen=True)
class TemporalEvent:
    event_id: str
    absolute_utc_epoch: float
    local_time_string: str
    timezone_iana_id: str
    dst_transition_anchor: str | None
    is_within_dst_window: bool
    is_spring_forward_gap: bool

@dataclass(frozen=True)
class TemporalContext:
    requires_dst_disambiguation: bool

@dataclass(frozen=True)
class TemporalManifest:
    verdict: TemporalVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_event(
        cls, event: TemporalEvent, ctx: TemporalContext
    ) -> TemporalManifest:
        
        # Gate 1: Abbreviation rejection
        if len(event.timezone_iana_id) < 4 or "/" not in event.timezone_iana_id:
            return TemporalManifest(
                verdict=TemporalVerdict.DST_AMBIGUITY_UNRESOLVED,
                directive=f"HALT: Timezone ID {event.timezone_iana_id} is ambiguous. Use IANA format (e.g., America/New_York).",
                manifest_digest=cls._hash(f"ABBREV:{event.event_id}")
            )

        # Gate 2: Spring-forward gap
        if event.is_spring_forward_gap:
            return TemporalManifest(
                verdict=TemporalVerdict.MISSING_HOUR_DETECTED,
                directive=f"HALT: Local time {event.local_time_string} does not exist in {event.timezone_iana_id} (spring-forward). Recompute.",
                manifest_digest=cls._hash(f"GAP:{event.event_id}")
            )

        # Gate 3: DST window without anchor
        if ctx.requires_dst_disambiguation and event.is_within_dst_window:
            if not event.dst_transition_anchor:
                return TemporalManifest(
                    verdict=TemporalVerdict.DST_AMBIGUITY_UNRESOLVED,
                    directive=f"HALT: Event within DST window but lacks occurrence anchor. Ambiguous.",
                    manifest_digest=cls._hash(f"NO_ANCHOR:{event.event_id}")
                )
            digest = cls._hash(json.dumps({
                "event": event.event_id,
                "utc": str(event.absolute_utc_epoch),
                "tz": event.timezone_iana_id,
                "anchor": event.dst_transition_anchor
            }, sort_keys=True))
            return TemporalManifest(
                verdict=TemporalVerdict.DST_AMBIGUITY_RESOLVED,
                directive=f"PROCEED: DST ambiguity resolved via anchor {event.dst_transition_anchor}.",
                manifest_digest=digest
            )

        # Gate 4: Unambiguous
        digest = cls._hash(json.dumps({
            "event": event.event_id,
            "utc": str(event.absolute_utc_epoch),
            "tz": event.timezone_iana_id
        }, sort_keys=True))
        
        return TemporalManifest(
            verdict=TemporalVerdict.UNAMBIGUOUS_TIME,
            directive="PROCEED: Event time is unambiguous.",
            manifest_digest=digest
        )