# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-does-a-monotonically-increasing-counter-wrap-and-silently-regress.md
# Remnant Warrant:    https://corpusfetch.com/c/when-does-a-monotonically-increasing-counter-wrap-and-silently-regress.warrant.json
# Markdown SHA-256:   62d57f09ac8fcc57549edb1e22ae8285cab40961fc75bc3fd0f4d442e3642c7c
# Code AST SHA-256:   23aeaaf938e09f4f31bbad5ff0f2bc9065d3e49bb5684b08274d07fb9e0c8acc
# Verified Classes:   CounterWrapError, CounterGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class CounterWrapError(RuntimeError):
    """Raised when a counter's width cannot absorb expected lifetime traffic."""


@dataclass(frozen=True)
class CounterGate:
    bit_width: int
    observed_rate: int
    expected_lifetime_s: int
    safety_factor: float = 10.0

    def verify(self) -> bool:
        capacity = 2 ** self.bit_width
        expected = self.observed_rate * self.expected_lifetime_s * self.safety_factor
        if expected >= capacity:
            raise CounterWrapError(
                f"expected {int(expected)} >= capacity {capacity}: "
                f"wrap is guaranteed within lifetime for width {self.bit_width}"
            )
        return True


def dispatch_counter_mode(gate: CounterGate) -> str:
    try:
        gate.verify()
    except CounterWrapError:
        return "wrap-aware-reader"
    return "plain"