"""告警节流器（§4/§5）：每类异常"第 1 次 + 每满 100 次"打印，带累计计数。

高频热路径（每帧数学）不打日志；所有异常日志走本通道，且不落在数学热路径
的决策上（§11.3 单周期处理无阻塞、无 IO）。
"""

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)

    def clear(self) -> None:
        self._counts.clear()