"""告警节流器（需求说明 §5 失败处理）：每类异常"第 1 次 + 每满 100 次"打印。

语义与 stereo_ranger 的节流器一致，但按前端/测距解耦要求（§7）不跨包复用。
"""

from typing import Dict


class WarnThrottle:
    """按异常类独立计数与限频。"""

    def __init__(self, every: int = 100) -> None:
        if every < 1:
            raise ValueError("every 必须 ≥ 1")
        self._every = every
        self._counts: Dict[str, int] = {}

    def should_emit(self, category: str) -> bool:
        """推进该类异常计数并返回本次是否应打印（第 1 次 + 每满 every 次）。"""
        count = self._counts.get(category, 0) + 1
        self._counts[category] = count
        return count == 1 or count % self._every == 0

    def count(self, category: str) -> int:
        """该类异常的累计次数。"""
        return self._counts.get(category, 0)