chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/sequence.py

@@ -0,0 +1,160 @@
+"""定义请求/响应配对输入与结果，不读取日志或改变原事件。
+
+调用者先生成A、B事件，并提供响应条件的完整时间证据；SequenceTick收齐同刻
+事实，SequenceRule规定闭区间延迟。SequenceResult保存原事件、延迟和观测质量，
+与现有point/activity事件表分开，公共AnalysisRunner通过SequenceRow保存其原事实。
+一个规则实例只属于一个dataset/session/group；group由上游分组后显式指定，
+不从车辆名或报文ID猜测。这里只用标准库，不执行配对或保持全局状态。
+"""
+
+# 冻结输入防止跨批处理时调用者改写已确认事实。
+from dataclasses import dataclass
+from .temporal import ConditionTick, Event
+from .types import QualityFlag as Q, Truth
+from .validation import require_identifier, require_text
+from ..timebase.conversion import checked_add_ns, require_int64_ns
+
+
+@dataclass(frozen=True)
+class SequenceRule:
+    """保存同一组内FIFO配对所需的身份和延迟范围。
+
+延迟两端包含，最小值可为0；A/B由既有规则ID指定，以事件confirmed_ns参与配对。
+group_id是调用者已经划分的实体/分析组，实例之间不共享候选或响应。
+    """
+
+    rule_id: str
+    dataset_id: str
+    session_id: str
+    start_rule_id: str
+    response_rule_id: str
+    min_delay_ns: int
+    max_delay_ns: int
+    group_id: str = 'default'
+    record_clock: bool = False  # True时delay按所选记录间隔累计，事件坐标仍是实际时间。
+
+    def __post_init__(self):
+        """验证规则身份与整数延迟，不猜测缺省等待时间。
+
+        参数: 无额外参数，读取冻结字段。
+        返回: None；纳秒规范为Python整数。
+        异常: TypeError/ValueError/OverflowError表示非法身份、范围或类型。
+        """
+        if type(self.record_clock) is not bool:
+            raise TypeError('record_clock需要bool')
+        # 规则名称沿用简单标识符，数据集/会话/分组保留完整文本身份。
+        for field in ('rule_id', 'start_rule_id', 'response_rule_id'):
+            require_identifier(getattr(self, field), field)
+        for field in ('dataset_id', 'session_id', 'group_id'):
+            require_text(getattr(self, field), field)
+        # Python精确整数比较，拒绝负延迟、倒置范围及bool时间。
+        minimum = require_int64_ns(self.min_delay_ns, 'min_delay_ns')
+        maximum = require_int64_ns(self.max_delay_ns, 'max_delay_ns')
+        if not 0 <= minimum <= maximum:
+            raise ValueError('需要0 <= min_delay_ns <= max_delay_ns')
+        object.__setattr__(self, 'min_delay_ns', minimum)
+        object.__setattr__(self, 'max_delay_ns', maximum)
+
+    def check_event(self, event: Event, *, response: bool):
+        """检查事件来自指定规则和当前会话，不按同名信号跨会话配对。
+
+        参数: event为既有Event；response明确表示A或B角色。
+        返回: None，保留原事件及其来源引用。
+        异常: TypeError为类型不符，ValueError为数据集/会话/规则不匹配。
+        """
+        # Event自身已验证边界与来源归属，这里验证配对规则的范围。
+        if not isinstance(event, Event) or type(response) is not bool:
+            raise TypeError('需要Event及bool角色')
+        expected = self.response_rule_id if response else self.start_rule_id
+        if (event.rule.dataset_id, event.rule.session_id, event.rule.rule_id) != (self.dataset_id, self.session_id, expected):
+            raise ValueError('顺序事件的数据集、会话或规则不匹配')
+
+
+@dataclass(frozen=True)
+class SequenceTick:
+    """保存同一时刻全部A/B及响应是否可判断的证据。
+
+condition.state描述此刻之后的连续区间，point_state描述此刻本身；terminal的
+人工连续UNKNOWN不污染真实末点。B出现时点证据必须已知。角色内重复ID拒绝，
+事件顺序不参与业务配对，检测器会按稳定ID处理同刻并列事件。
+    """
+
+    condition: ConditionTick
+    starts: tuple[Event, ...] = ()
+    responses: tuple[Event, ...] = ()
+
+    def __post_init__(self):
+        """验证原子时间组，避免把一半同刻事实先送入检测器。
+
+        参数: 无额外参数；condition及两个事件tuple。
+        返回: None，不排序或修改调用者对象。
+        异常: TypeError/ValueError为结构、时间、重复ID或观测矛盾。
+        """
+        # 输入必须使用已校验的时间证据；每个事件按确认时刻参与顺序判断。
+        if not isinstance(self.condition, ConditionTick):
+            raise TypeError('condition需要ConditionTick')
+        for events in (self.starts, self.responses):
+            if not isinstance(events, tuple) or any(not isinstance(event, Event) for event in events):
+                raise TypeError('同刻事件需要Event tuple')
+            if any(event.confirmed_ns != self.condition.time_ns for event in events):
+                raise ValueError('事件确认时间与同刻组不同')
+            if len({event.event_id for event in events}) != len(events):
+                raise ValueError('同一角色内事件ID重复')
+        # 真实B不能同时被描述为响应条件无法判断，FALSE边沿则仍是已知证据。
+        if self.responses and self.condition.point_state is Truth.UNKNOWN:
+            raise ValueError('响应事件缺少已知的点观测证据')
+
+
+@dataclass(frozen=True)
+class SequenceResult:
+    """保存一个请求的最终处理结果，原请求和响应均可追溯。
+
+matched表示观察到合格响应；no_response表示完整等待后可确定无响应；
+indeterminate表示等待中缺观测或提前结束。observation_quality保留等待期间的未知原因，
+即使最后匹配成功也不隐藏先前缺失。decided_ns为响应、deadline或提前EOF时刻。
+    """
+
+    result_id: str
+    rule: SequenceRule
+    request: Event
+    response: Event | None
+    status: str
+    decided_ns: int
+    delay_ns: int | None
+    observation_quality: Q
+
+    def __post_init__(self):
+        """拒绝不可能的结果组合，防止把未知观测组装成正常超时。
+
+        参数: 无额外参数，读取结果字段。
+        返回: None；不生成事件或写结果文件。
+        异常: TypeError/ValueError/OverflowError为身份、时间或状态矛盾。
+        """
+        # 结果保留强类型规则/原事件，范围检查与输入相同。
+        require_text(self.result_id, 'result_id')
+        if not isinstance(self.rule, SequenceRule) or not isinstance(self.observation_quality, Q):
+            raise TypeError('结果需要SequenceRule及QualityFlag')
+        self.rule.check_event(self.request, response=False)
+        decided = require_int64_ns(self.decided_ns, 'decided_ns')
+        object.__setattr__(self, 'decided_ns', decided)
+        deadline = None if self.rule.record_clock else checked_add_ns(self.request.confirmed_ns, self.rule.max_delay_ns)
+        if decided < self.request.confirmed_ns or deadline is not None and decided > deadline:
+            raise ValueError('决定时刻超出请求等待范围')
+        # 匹配必须在闭区间内；非匹配没有可用延迟值，不能用0冒充。
+        if self.status == 'matched':
+            self.rule.check_event(self.response, response=True)
+            delay = require_int64_ns(self.delay_ns, 'delay_ns')
+            object.__setattr__(self, 'delay_ns', delay)
+            if (decided != self.response.confirmed_ns
+                    or not self.rule.record_clock and delay != decided-int(self.request.confirmed_ns)
+                    or not self.rule.min_delay_ns <= delay <= self.rule.max_delay_ns):
+                raise ValueError('匹配时间或延迟与规则不符')
+        elif self.status in ('no_response', 'indeterminate'):
+            if self.response is not None or self.delay_ns is not None:
+                raise ValueError('未匹配结果不能包含响应或延迟')
+            if self.status == 'no_response' and (deadline is not None and decided != deadline or self.observation_quality != Q.NONE):
+                raise ValueError('no_response需要完整、已知的等待区间')
+            if self.status == 'indeterminate' and self.observation_quality == Q.NONE:
+                raise ValueError('indeterminate必须说明缺失观测原因')
+        else:
+            raise ValueError('未知顺序结果状态')

chronaxis/core/sequence_reference.py

@@ -0,0 +1,248 @@
+"""按时间组将请求与响应FIFO配对，区分未响应和无法确定。
+
+输入为同一组完整有序的SequenceTick，输出为每次push新确定的SequenceResult。
+检测器保存尚未决定的请求；返回的结果不再在内部累积。候选数有明确上限，
+任何失败均封闭实例，调用者不能把部分结果宣告为完整任务成功。
+响应可判断性来自既有ConditionTick的连续/点视图，TTL等边界必须由上游提供。
+状态循环只依赖标准库，不冒称NumPy数组优化，不读取来源或写盘。
+"""
+
+# FIFO候选入队出队为常数时间；身份使用稳定内容，避免批次影响结果ID。
+from collections import deque
+from hashlib import sha256
+from .binding import _identity
+from .models import Interval
+from .sequence import SequenceResult, SequenceRule, SequenceTick
+from .temporal import ConditionTimeline, Event
+from .temporal_reference import require_batch
+from .types import QualityFlag as Q, Truth
+from ..timebase.conversion import checked_add_ns
+
+# 固定质量位前缀计数避免每次输入都遍历全部待响应请求。
+_QUALITY_BITS = tuple(Q)
+
+
+class SequenceDetector:
+    """维护一个dataset/session/group/rule的等待队列与观测状态。
+
+候选按A时间和同刻稳定ID排序。B只消费最早的合格A；截止点先匹配再超时。
+输入跨批连续、批尾不当EOF；每次push立即转交已决定结果。max_pending限制
+同时存在的请求数量，不是整进程RAM保证，公共AnalysisRunner的SequenceRows另行计费。
+    """
+
+    def __init__(self, rule: SequenceRule, start_ns: int, end_ns: int, *, max_pending: int = 65536):
+        """建立独立状态，不从别的组或会话复制候选。
+
+        参数: rule；start_ns/end_ns为明确会话范围；max_pending为正原生整数。
+        返回: 新检测器，尚未消费任何时间组。
+        异常: TypeError/ValueError/OverflowError为规则、范围或容量错误。
+        """
+        # 会话范围和容量在任何状态分配前校验。
+        if not isinstance(rule, SequenceRule) or type(max_pending) is not int or max_pending <= 0:
+            raise TypeError('需要SequenceRule及正int max_pending')
+        domain = Interval(start_ns, end_ns)
+        self.rule, self.start_ns, self.end_ns = rule, domain.start_ns, domain.end_ns
+        self.max_pending = max_pending
+        self._pending = deque()
+        self._counts = [0] * len(_QUALITY_BITS)
+        self._quality = Q.NONE
+        self._cursor = self.start_ns
+        self._last_time = None
+        self._record_elapsed = 0
+        self._ended = self._finished = self._failed = False
+
+    @property
+    def pending_count(self):
+        """返回尚未决定的请求数量，不暴露可修改队列。
+
+        参数: 无。
+        返回: 非负整数；已结束或失败时为0。
+        异常: 无主动异常。
+        """
+        # 不为查看数量复制全部事件。
+        return len(self._pending)
+
+    def _note(self, quality):
+        """累计本段未知原因，供各请求按自己的起点查询。
+
+        参数: quality为已校验的质量位。
+        返回: None，更新固定长度计数器。
+        异常: 无主动异常；只由内部协议调用。
+        """
+        # 每段最多检查固定9位，不按候选数做重复状态更新。
+        for index, bit in enumerate(_QUALITY_BITS):
+            if quality & bit:
+                self._counts[index] += 1
+
+    def _advance(self, time_ns):
+        """结算上个时间组至指定时刻的连续观测，不推断额外响应。
+
+        参数: time_ns为不早于内部游标的时间。
+        返回: None；正长度未知区间计入质量，零长度不增加区间证据。
+        异常: 无主动异常，外层已验证时间顺序。
+        """
+        # 同刻处理不伪造时长；此段状态由上个完整输入组确定。
+        if time_ns > self._cursor and self._quality != Q.NONE:
+            self._note(self._quality)
+        self._cursor = time_ns
+
+    def _result(self, pending, time_ns, response=None, *, early_end=False):
+        """把一个请求的最终事实转换为稳定结果，保留原事件引用。
+
+        参数: pending含请求/质量快照/deadline；time_ns为决定时刻；response可空；early_end表示提前EOF。
+        返回: SequenceResult，匹配或有质量依据的未匹配结果。
+        异常: 模型校验或内存异常传播，不输出伪成功。
+        """
+        # 只累积请求之后出现的未知位，之前的缺失不能污染新请求。
+        request, snapshot, _deadline = pending
+        quality = Q.NONE
+        for bit, before, after in zip(_QUALITY_BITS, snapshot, self._counts):
+            if after > before:
+                quality |= bit
+        if early_end:
+            quality |= Q.MISSING
+        status = 'matched' if response is not None else 'indeterminate' if quality != Q.NONE else 'no_response'
+        delay = None if response is None else (self._record_elapsed - _deadline + self.rule.max_delay_ns
+            if self.rule.record_clock else time_ns-int(request.confirmed_ns))
+        # 身份包括组、规则参数及原事件；批大小/候选容量不影响业务身份。
+        identity = (self.rule.dataset_id, self.rule.session_id, self.rule.group_id, self.rule.rule_id,
+                    self.rule.start_rule_id, self.rule.response_rule_id, self.rule.min_delay_ns,
+                    self.rule.max_delay_ns, request.event_id, int(request.confirmed_ns),
+                    None if response is None else response.event_id, time_ns, status)
+        if self.rule.record_clock:
+            identity += ('record_clock', delay)
+        result_id = sha256(_identity(identity).encode('utf-8')).hexdigest()
+        return SequenceResult(result_id, self.rule, request, response, status, time_ns, delay, quality)
+
+    def _consume(self, tick, output, advance=None):
+        """按先前截止点、同刻配对、同刻超时、EOF的顺序处理一组。
+
+        参数: tick为已检查的SequenceTick，output是本批局部输出列表。
+        返回: None；更新候选和游标，不存储已经转交的结果。
+        异常: MemoryError为候选上限；结果构造失败传播。
+        """
+        # 上游允许NumPy整数；这里规范容器，避免后续运算/身份编码继承数组标量。
+        time = int(tick.condition.time_ns)
+        if self.rule.record_clock:
+            self._record_elapsed += advance
+            self._advance(time)
+        clock = self._record_elapsed if self.rule.record_clock else time
+        # 无新消息也在精确deadline结算；严格小于当前时间的候选已无匹配机会。
+        while self._pending and self._pending[0][2] < clock:
+            deadline = self._pending[0][2]
+            if not self.rule.record_clock:
+                self._advance(deadline)
+            output.append(self._result(self._pending.popleft(), time if self.rule.record_clock else deadline))
+        self._advance(time)
+        # 同刻A必须先收齐，B的输入顺序不能影响零延迟匹配。
+        if len(self._pending) + len(tick.starts) > self.max_pending:
+            raise MemoryError('sequence待响应请求超过max_pending')
+        for event in sorted(tick.starts, key=lambda item: item.event_id):
+            self._pending.append((event, tuple(self._counts), clock + self.rule.max_delay_ns
+                if self.rule.record_clock else checked_add_ns(time, self.rule.max_delay_ns)))
+        # 独立点UNKNOWN也不能被当作完整观察；terminal人工连续UNKNOWN不计入。
+        if tick.condition.point_state is Truth.UNKNOWN:
+            self._note(tick.condition.point_quality)
+        for response in sorted(tick.responses, key=lambda item: item.event_id):
+            # 所有请求使用同一min_delay；最老的还太新时，其余也不能匹配。
+            if self._pending and (clock - self._pending[0][2] + self.rule.max_delay_ns
+                    if self.rule.record_clock else time-int(self._pending[0][0].confirmed_ns)) >= self.rule.min_delay_ns:
+                output.append(self._result(self._pending.popleft(), time, response))
+        # 只有同刻合格B都使用过后，才决定截止点仍剩余的请求。
+        while self._pending and self._pending[0][2] == clock:
+            output.append(self._result(self._pending.popleft(), time))
+        if tick.condition.terminal:
+            # 观察先结束不能证明设备未响应；不把deadline裁短成正常超时。
+            while self._pending:
+                output.append(self._result(self._pending.popleft(), time, early_end=True))
+            self._ended = True
+        self._quality = tick.condition.quality
+        self._last_time = time
+
+    def push(self, ticks: tuple[SequenceTick, ...], *, advances=None) -> tuple[SequenceResult, ...]:
+        """消费一批完整时间组并仅返回本批确定的结果。
+
+        参数: ticks为有序tuple，可为空，首末与声明会话范围一致；advances仅规则
+            record_clock模式使用，保存一个必要累计计数而不存逐点时间对照。
+        返回: 新SequenceResult tuple；调用者负责消费，不在实例中重复保留。
+        异常: TypeError/ValueError/OverflowError为协议错误；MemoryError为容量不足。
+        副作用: 失败后释放候选并封闭实例，已转交的早先批次不能视为完整成功。
+        """
+        # 失败或finish后的实例不允许继续使用，避免部分状态拼成另一个任务。
+        if self._failed or self._finished:
+            raise ValueError('sequence实例已失败或finish')
+        try:
+            if not isinstance(ticks, tuple) or any(not isinstance(tick, SequenceTick) for tick in ticks):
+                raise TypeError('push需要SequenceTick tuple')
+            require_batch(tuple(tick.condition for tick in ticks), self.start_ns, self.end_ns, self._last_time, self._ended)
+            from .temporal_clock import require_clock_advances
+            require_clock_advances(tuple(t.condition for t in ticks), advances, self.rule.record_clock, self._last_time)
+            # 整批先检查归属及deadline溢出，再推进；错误事件不能污染另一组。
+            for tick in ticks:
+                for event in tick.starts:
+                    self.rule.check_event(event, response=False)
+                    if not self.rule.record_clock:
+                        checked_add_ns(event.confirmed_ns, self.rule.max_delay_ns)
+                for event in tick.responses:
+                    self.rule.check_event(event, response=True)
+            output = []
+            for index, tick in enumerate(ticks):
+                self._consume(tick, output, None if advances is None else advances[index])
+            return tuple(output)
+        except Exception:
+            # 超限/坏输入均使任务失败，不能跳过该批继续生产正常结果。
+            self._failed = True
+            self._pending.clear()
+            raise
+
+    def finish(self):
+        """确认已经收到真正EOF，不制造额外响应或超时。
+
+        参数: 无。
+        返回: None；结果已经由各次push转交。
+        异常: ValueError为缺EOF、失败或重复finish。
+        """
+        # 与批尾区分，只有terminal之后可以声明消费完成。
+        if self._failed or self._finished or not self._ended:
+            raise ValueError('finish需要完整terminal且实例未关闭')
+        self._finished = True
+
+
+def pair_sequence(rule: SequenceRule, starts: tuple[Event, ...], responses: tuple[Event, ...],
+                  timeline: ConditionTimeline, *, batch_rows: int = 65536, max_pending: int = 65536):
+    """将既有事件与完整响应条件轴接到顺序核心，适合可控内存分析。
+
+    参数: rule；starts/responses为已确认事件tuple；timeline含全部条件变化、TTL及EOF；
+        batch_rows为每批完整时间组数，max_pending限制等待队列。
+    返回: SequenceResult tuple；只为此内存便利入口收集全部输出。
+    异常: TypeError/ValueError为类型/归属/缺失事件时刻；容量与时间溢出传播。
+    边界: 不补采样、解析文件或推断同步；大数据上层直接分批使用SequenceDetector。
+    """
+    # 完整轴定义了可判断区间，来源范围不允许继承其他会话。
+    if not isinstance(timeline, ConditionTimeline) or type(batch_rows) is not int or batch_rows <= 0:
+        raise TypeError('需要ConditionTimeline及正int batch_rows')
+    detector = SequenceDetector(rule, timeline.start_ns, timeline.end_ns, max_pending=max_pending)
+    if any(ref.session_id != rule.session_id for ref in timeline.source_refs):
+        raise ValueError('响应观测来源不属于当前会话')
+    groups = ({}, {})
+    for events, group, response in ((starts, groups[0], False), (responses, groups[1], True)):
+        if not isinstance(events, tuple):
+            raise TypeError('完整事件输入需要tuple')
+        seen = set()
+        for event in events:
+            rule.check_event(event, response=response)
+            if event.event_id in seen:
+                raise ValueError('同一角色内事件ID重复')
+            seen.add(event.event_id)
+            group.setdefault(event.confirmed_ns, []).append(event)
+    # 事件时刻必须有明确条件点证据，不由本入口伪造TTL、点状态或EOF。
+    times = {tick.time_ns for tick in timeline.ticks}
+    if any(time not in times for group in groups for time in group):
+        raise ValueError('事件确认时刻不在响应条件时间轴中')
+    results = []
+    for offset in range(0, len(timeline.ticks), batch_rows):
+        ticks = tuple(SequenceTick(tick, tuple(groups[0].get(tick.time_ns, ())), tuple(groups[1].get(tick.time_ns, ())))
+                      for tick in timeline.ticks[offset:offset+batch_rows])
+        results.extend(detector.push(ticks))
+    detector.finish()
+    return tuple(results)

chronaxis/core/stability.py

@@ -0,0 +1,249 @@
+"""把进入/退出条件转换为带迟滞和双向防抖的活动。
+
+输入为同一会话、同一时刻的两组ConditionTick和非负纳秒防抖时长。
+先结算此前已持续满足的条件，再处理当前更新；中间区间保持已确定状态，
+UNKNOWN清除候选和此前状态。普通批次/文件边界不参与状态重置。
+输出沿用活动Event，起点等于实际进入确认时刻；退出等待期间仍属于活动。
+本模块仅实现有序状态转换，活动组装委托既有独立参考/NumPy检测器；
+不声称状态循环是数值数组化，不读取文件，也不保存全量信号历史。
+"""
+
+from dataclasses import dataclass, replace
+from .temporal import ConditionTick
+from .temporal_reference import ReferenceTemporalDetector, require_batch, require_detector
+from .types import QualityFlag as Q, Truth
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class StabilitySpec:
+    """保存进入和退出的独立等待时长；0表示条件满足即可转换。
+
+    状态属于运行实例，本声明不保存已报警标志或候选计时。
+    """
+
+    enter_ns: int = 0  # 进入条件连续满足多久才切换为活动。
+    exit_ns: int = 0  # 退出条件连续满足多久才切换为非活动。
+    track_duration: bool = False  # 仅显式需求累计，普通规则不增加逐步统计。
+
+    def __post_init__(self):
+        """拒绝负值、bool及超int64时长。参数: 无。返回: None。异常: 类型/范围错误。"""
+        if type(self.track_duration) is not bool:
+            raise TypeError('track_duration必须bool')
+        for name in ('enter_ns', 'exit_ns'):
+            value = require_int64_ns(getattr(self, name), name)
+            if value < 0:
+                raise ValueError('防抖时长不能为负')
+            object.__setattr__(self, name, value)
+
+
+def invert_tick(tick):
+    """取得普通防抖条件的退出证据，UNKNOWN保留原原因。
+
+    参数: tick为ConditionTick。返回: 点/连续状态分别取反的新证据。
+    异常: TypeError为非ConditionTick；不修改输入。
+    """
+    if not isinstance(tick, ConditionTick):
+        raise TypeError('防抖条件需要ConditionTick')
+    opposite = {Truth.TRUE: Truth.FALSE, Truth.FALSE: Truth.TRUE, Truth.UNKNOWN: Truth.UNKNOWN}
+    return replace(tick, state=opposite[tick.state], point_state=opposite[tick.point_state])
+
+
+class StabilityDetector:
+    """维护一个规则/会话的已确定状态、单个待转换候选及活动输出。
+
+    未知起点不猜未报警；两条件都假时保持前态，二者同时为真则报告配置冲突。
+    一个条件未知会中断活动；恢复时从未知开始重新确认，不能跨缺口累计防抖。
+    每次push可有多组，只有真实terminal才能finish；drain只取走输出。
+    """
+
+    def __init__(self, rule, start_ns, end_ns, spec, source_refs=(), *, backend='reference', record_clock=False):
+        """建立独立迟滞状态，复用零时长活动检测器。
+
+        参数: rule为condition_duration=0规则；start_ns/end_ns为会话域；spec为StabilitySpec；
+            source_refs为来源定位；backend为reference或numpy。
+        返回: None；初始化实例状态。异常: 规则、域、类型或后端错误。
+        """
+        require_detector(rule, start_ns, end_ns, source_refs)
+        if not isinstance(spec, StabilitySpec) or rule.rule_type != 'condition_duration' or rule.minimum_duration_ns != 0:
+            raise ValueError('迟滞需要StabilitySpec及duration=0活动规则')
+        if backend not in ('reference', 'numpy'):
+            raise ValueError('迟滞后端需reference或numpy')
+        # 参考入口不导入NumPy；两者共用状态转换协议，活动核独立执行。
+        detector_type = ReferenceTemporalDetector
+        if backend == 'numpy':
+            from .temporal_numpy import NumpyTemporalDetector
+            detector_type = NumpyTemporalDetector
+        self.rule, self.spec = rule, spec
+        self.start_ns, self.end_ns = int(start_ns), int(end_ns)
+        self.state, self.quality = Truth.UNKNOWN, Q.MISSING
+        self.pending, self.deadline = None, None
+        self.record_clock, self.remaining = record_clock, 0
+        self.last_time, self.ended, self.finished = None, False, False
+        self._core = detector_type(rule, self.start_ns, self.end_ns, source_refs, record_clock=record_clock)
+        # 固定三个整数/一个状态，不保存逐点轨迹或额外扫描。UNKNOWN时间不会算成未报警。
+        self._duration_time, self._duration_state = self.start_ns, Truth.UNKNOWN
+        self._active_ns = self._known_ns = 0
+
+    def _push_core(self, tick, advance=None):
+        """把已确认状态交给活动核，并按需累计左侧半开区间。
+
+        参数: tick为状态转换后的证据，advance为记录模式本组累计量。返回: 原活动核Event tuple。
+        异常: 原活动核校验错误；失败实例不能继续使用。
+        """
+        if self.spec.track_duration:
+            duration = advance if self.record_clock else int(tick.time_ns) - self._duration_time
+            if self._duration_state is not Truth.UNKNOWN:
+                self._known_ns += duration
+                if self._duration_state is Truth.TRUE:
+                    self._active_ns += duration
+            self._duration_time, self._duration_state = int(tick.time_ns), tick.state
+        return self._core.push((tick,), advances=(advance,) if self.record_clock else None)
+
+    @property
+    def duration_counts(self):
+        """读取完成后的已知报警/已知观测整数纳秒。
+
+        参数: 无。返回: (active_ns,known_ns)或None（未请求统计）。
+        异常: ValueError表示请求统计但尚未正常finish。
+        """
+        if not self.spec.track_duration:
+            return None
+        if not self.finished:
+            raise ValueError('迟滞累计只能在finish后读取')
+        return self._active_ns, self._known_ns
+
+    @property
+    def next_deadline_ns(self):
+        """读取域内待转换时间。参数: 无。返回: int或None。异常: 无。
+
+        加法使用Python整数，域外结果不转换为int64或回绕。
+        """
+        return self.deadline if not self.record_clock and self.deadline is not None and self.deadline <= self.end_ns else None
+
+    @staticmethod
+    def _target(enter, exit, quality):
+        """区分明确方向、中间区间、未知与矛盾条件。
+
+        参数: enter/exit为Truth；quality为两个条件原因并集。
+        返回: Truth或None（中间区间）。异常: ValueError为同时满足进出条件。
+        """
+        if enter is Truth.TRUE and exit is Truth.TRUE:
+            raise ValueError('迟滞进入和退出条件同时成立，请设置不重叠的条件')
+        if enter is Truth.UNKNOWN or exit is Truth.UNKNOWN:
+            return Truth.UNKNOWN
+        if enter is Truth.TRUE:
+            return Truth.TRUE
+        if exit is Truth.TRUE:
+            return Truth.FALSE
+        return None
+
+    def _settle(self):
+        """兑现已持续达到门槛的转换。参数: 无。返回: None。异常: 无。"""
+        self.state, self.quality = self.pending, Q.NONE
+        self.pending, self.deadline = None, None
+        self.remaining = 0
+
+    def _point(self, target, quality):
+        """判断当前点状态，不把零长度点累计到等待时间。
+
+        参数: target为目标或None，quality为点原因。返回: (Truth,Q)。异常: 无。
+        """
+        if target is Truth.UNKNOWN:
+            return Truth.UNKNOWN, quality
+        if target is not None:
+            delay = self.spec.enter_ns if target is Truth.TRUE else self.spec.exit_ns
+            if delay == 0:
+                return target, Q.NONE
+        return self.state, self.quality
+
+    def _continuous(self, target, quality, time_ns):
+        """更新右侧持续状态和唯一候选，取消不连续的计时。
+
+        参数: target为目标/None；quality为原因；time_ns为当前纳秒。
+        返回: None，修改实例。异常: 无；超域deadline仅用于比较。
+        """
+        if target is Truth.UNKNOWN:
+            self.state, self.quality = Truth.UNKNOWN, quality
+            self.pending, self.deadline = None, None
+        elif target is None or target is self.state:
+            # 返回中间区间仍保留已确认状态，但未满时长的进/出请求撤销。
+            self.pending, self.deadline = None, None
+        else:
+            delay = self.spec.enter_ns if target is Truth.TRUE else self.spec.exit_ns
+            if delay == 0:
+                self.state, self.quality = target, Q.NONE
+                self.pending, self.deadline = None, None
+            elif self.pending is not target:
+                self.pending = target
+                self.deadline = None if self.record_clock else time_ns + delay
+                self.remaining = delay
+
+    def push(self, ticks, exit_ticks=None, *, advances=None):
+        """推进成对条件组，可在两次实际更新之间精确兑现防抖计时。
+
+        参数: ticks为进入条件tuple；exit_ticks为同刻退出tuple，省略时为not进入；
+            advances仅record_clock模式传入本组周期增量，无驱动边界为0。
+        返回: 本次新Event tuple；活动起点为进入转换时刻，不回填等待区间。
+        异常: 输入/顺序/同刻冲突/finish后推进错误；发生错误后调用方应丢弃实例。
+        """
+        if self.finished:
+            raise ValueError('迟滞检测器已finish')
+        require_batch(ticks, self.start_ns, self.end_ns, self.last_time, self.ended)
+        from .temporal_clock import require_clock_advances
+        require_clock_advances(ticks, advances, self.record_clock, self.last_time)
+        if exit_ticks is None:
+            exit_ticks = tuple(invert_tick(tick) for tick in ticks)
+        require_batch(exit_ticks, self.start_ns, self.end_ns, self.last_time, self.ended)
+        if len(ticks) != len(exit_ticks) or any(a.time_ns != b.time_ns for a, b in zip(ticks, exit_ticks)):
+            raise ValueError('迟滞两个条件必须在相同的完整时间组求值')
+        output = []
+        for index, (enter, exit) in enumerate(zip(ticks, exit_ticks)):
+            time_ns = int(enter.time_ns)
+            advance = None if advances is None else advances[index]
+            # 先结算前一个半开区间，即使当前点恰好变假或失效也不抹去已得时长。
+            if self.record_clock and self.pending is not None:
+                self.remaining = max(0, self.remaining - advance)
+            settled = (self.pending is not None and self.remaining == 0 if self.record_clock
+                       else self.deadline is not None and self.deadline <= time_ns)
+            if settled:
+                deadline = time_ns if self.record_clock else self.deadline
+                self._settle()
+                if deadline < time_ns:
+                    output.extend(self._push_core(ConditionTick(deadline, self.state)))
+            diagnostic = enter.diagnostic_quality | exit.diagnostic_quality | enter.quality | exit.quality
+            diagnostic |= enter.point_quality | exit.point_quality
+            point_quality = enter.point_quality | exit.point_quality
+            point_target = self._target(enter.point_state, exit.point_state, point_quality)
+            point_state, point_quality = self._point(point_target, point_quality)
+            # 退出等待已在左侧完整满足；同刻EOF/失效不能把这个已知退出改成缺观测。
+            if settled and self.state is Truth.FALSE and point_state is Truth.UNKNOWN:
+                point_state, point_quality = Truth.FALSE, Q.NONE
+            if enter.terminal:
+                # 末点能解除旧活动，但不能开始新的正长度活动或假造末点后的保持。
+                state, quality = Truth.UNKNOWN, enter.quality | exit.quality | Q.MISSING
+                self.pending, self.deadline = None, None
+            else:
+                quality = enter.quality | exit.quality
+                target = self._target(enter.state, exit.state, quality)
+                self._continuous(target, quality, time_ns)
+                state, quality = self.state, self.quality
+            tick = ConditionTick(time_ns, state, quality,
+                actual_update=enter.actual_update or exit.actual_update or settled,
+                observation_end=enter.observation_end or exit.observation_end, terminal=enter.terminal,
+                point_state=point_state, point_quality=point_quality,
+                actual_unknown=(enter.actual_unknown or exit.actual_unknown) and point_state is Truth.UNKNOWN,
+                diagnostic_quality=diagnostic)
+            output.extend(self._push_core(tick, advance))
+            self.last_time, self.ended = time_ns, enter.terminal
+        return tuple(output)
+
+    def drain_events(self):
+        """取走最终活动而不清计时。参数: 无。返回: Event tuple。异常: 分配错误。"""
+        return self._core.drain_events()
+
+    def finish(self):
+        """只在真实会话末尾封闭。参数: 无。返回: 未取走活动。异常: 缺terminal/重复。"""
+        result = self._core.finish()
+        self.finished = True
+        return result