# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-does-an-iso8601-timestamp-without-a-timezone-silently-shift-the-event-time.md
# Remnant Warrant:    https://corpusfetch.com/c/when-does-an-iso8601-timestamp-without-a-timezone-silently-shift-the-event-time.warrant.json
# Markdown SHA-256:   78eefe4fec47284f4cd788ce5af5ff1214c536f4b2632b9e09d9f889b8ac7bd4
# Code AST SHA-256:   13a636f8daf53f45aa610110942124e4fad096c3adbf1f0ee93b3f82d8060013
# Verified Classes:   NaiveTimestampError, TimestampGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import re
from dataclasses import dataclass


class NaiveTimestampError(ValueError):
    """Raised when a timestamp lacks a timezone and its instant is ambiguous."""


OFFSET_RE = re.compile(r"(Z|[+-]\d{2}:?\d{2})$")


@dataclass(frozen=True)
class TimestampGate:
    value: str
    naive_means_utc: bool = False

    def verify(self) -> bool:
        if OFFSET_RE.search(self.value):
            return True
        if not self.naive_means_utc:
            raise NaiveTimestampError(
                "timestamp lacks timezone; producer and consumer may disagree on the instant"
            )
        return True


def dispatch_timestamp_parse(gate: TimestampGate) -> str:
    try:
        gate.verify()
    except NaiveTimestampError:
        return "reject-naive"
    return "parse"