first commit

utils/visual_track_control/staleness_checker.py

@@ -0,0 +1,19 @@
+"""输入超龄判定（单调毫秒时钟）。
+
+对应 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