"""输入超龄判定（单调毫秒时钟）。

对应 C++ 参考实现 reference-c++/visual_track_control/include/visual_track_control/staleness_checker.h
（规格：docs/物理追踪思路.md §7.1：超龄数据只能触发降级或告警）。
"""


def is_stale(sample_time_ms: int, now_ms: int, valid_for_ms: int) -> bool:
    """输入超龄判定。

    sample_time_ms <= 0 视为从未取样，直接判超龄；now_ms < sample_time_ms
    （时间戳不一致：时钟源错配/打戳错误）同样判超龄——单一单调时钟下不应
    发生，宁可降级也不信任不可核实的取样。
    """
    if sample_time_ms <= 0:
        return True
    if now_ms < sample_time_ms:
        return True
    return (now_ms - sample_time_ms) > valid_for_ms