# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-does-a-wall-clock-schedule-fire-twice-or-zero-times-on-a-dst-transition.md
# Remnant Warrant:    https://corpusfetch.com/c/when-does-a-wall-clock-schedule-fire-twice-or-zero-times-on-a-dst-transition.warrant.json
# Markdown SHA-256:   307980e1b50d9b3b03705fca5ee9c835c26f463b363d24ed71a077f5f55dabb6
# Code AST SHA-256:   13f68f2ded0d133c37c25867da7686559dcd1e0a9f9c74c5dd32bc7469bc98ce
# Verified Classes:   ScheduleAmbiguityError, ScheduleGate
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class ScheduleAmbiguityError(RuntimeError):
    """Raised when a wall-clock schedule is not a total function to instants across DST transitions."""


@dataclass(frozen=True)
class ScheduleGate:
    basis: str  # "utc", "wall-clock", "absolute-instant"
    dst_policy: str  # "skip", "shift", "fire-once", "none"
    job_idempotent: bool = False

    def verify(self) -> bool:
        if self.job_idempotent:
            return True
        if self.basis == "utc":
            return True
        if self.basis == "absolute-instant" and self.dst_policy in ("skip", "shift", "fire-once"):
            return True
        if self.basis == "wall-clock" and self.dst_policy == "none":
            raise ScheduleAmbiguityError(
                "wall-clock schedule with no DST policy fires twice or zero times at transitions"
            )
        raise ScheduleAmbiguityError(
            f"basis {self.basis!r} with policy {self.dst_policy!r} is not unambiguous"
        )


def dispatch_schedule(gate: ScheduleGate) -> str:
    try:
        gate.verify()
    except ScheduleAmbiguityError:
        return "utc-with-logical-date"
    return "absolute-instant"