chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/validation.py

@@ -0,0 +1,94 @@
+"""检查核心模型的文本、简单名称、来源序号和不可变标量。
+
+输入为已经解析的Python对象；文本检查返回原文，序号检查返回精确Python整数，
+标量检查只判断类型。原字段可以含点号；标识符须符合ASCII简单名称规则，
+不得占用Python关键字或已注册的表达式函数名。本模块不裁剪或改名，不把bool
+当整数，不检查样本质量。仅依赖标准库，没有数据读取、日志或会话状态。
+"""
+
+# 标准库提供明确的名称语法和整数协议，不用eval或对象反射。
+import keyword
+import re
+from numbers import Integral
+
+# 名称语法来自设计9.2；两个首版函数名保留给表达式层。
+IDENTIFIER_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+# 首版注册函数名占用统一名称空间，避免信号遮蔽函数语义。
+RESERVED_NAMES = frozenset({"abs", "isclose"})
+# 逻辑标量只接受这些不可变Python类型，数组标量由适配层显式转换。
+SCALAR_TYPES = (int, float, bool, str, type(None))
+
+
+def require_text(value: str, field: str) -> str:
+    """检查非空来源文本并保留原文本身份，不自动strip或改名。
+
+    参数: value (str)为来源名或原字段文本；field (str)用于错误定位。
+    返回: str；原文本，点号及两端非全空白不被改写。
+    异常: TypeError为非文本；ValueError为空或全空白。
+    """
+    # 来源身份不能由任意对象的str猜测。
+    if not isinstance(value, str):
+        # 精确指出哪个模型字段类型错误。
+        raise TypeError(f"{field}必须为字符串")
+    # 全空白不是可定位的来源标识；正常文本不作归一化。
+    if not value.strip():
+        # 缺项不能用空名字继续分析。
+        raise ValueError(f"{field}不能为空或全空白")
+    # 返回原文本以保留字段定位身份。
+    return value
+
+
+def require_identifier(value: str, field: str) -> str:
+    """校验设计9.2的简单标识符，不接受属性路径或隐藏替换。
+
+    参数: value (str)为标识符、来源名或表达式别名；field (str)用于错误定位。
+    返回: str；原合法标识，大小写保留。
+    异常: TypeError为非文本；ValueError为语法、关键字或保留名冲突。
+    """
+    # 先处理缺项和类型，后续regex只看到明确文本。
+    text = require_text(value, field)
+    # fullmatch不允许点号、空格、非ASCII或尾随其他字符。
+    if IDENTIFIER_PATTERN.fullmatch(text) is None or keyword.iskeyword(text) or text in RESERVED_NAMES:
+        # 不自动把点号替换为下划线；保留名按首版契约拒绝。
+        raise ValueError(f"{field}须为非关键字/保留名的ASCII简单标识符")
+    # 名称只做校验，不改变不同大小写的身份。
+    return text
+
+
+def require_sequence(value: int) -> int:
+    """校验来源内非负精确序号，不设置未经设计要求的64位上限。
+
+    参数: value (Integral)为原来源稳定序号；bool不属于序号。
+    返回: int；精确序号，不使用float或取模。
+    异常: TypeError为非整数或bool；ValueError为负序号。
+    """
+    # True不能被当作来源序号1。
+    if isinstance(value, bool) or not isinstance(value, Integral):
+        # 非整数不靠截断转换修补。
+        raise TypeError("sequence必须为非布尔整数")
+    # 不损失位值地归一到Python整数。
+    result = int(value)
+    # 来源序号非负，不自动重编号负输入。
+    if result < 0:
+        # 错误序号不能作为合法样本身份。
+        raise ValueError("sequence必须非负")
+    # 返回不可变精确身份。
+    return result
+
+
+def require_scalar(value: int | float | bool | str | None) -> None:
+    """限制逻辑样本的值类型，允许保留尚未检查质量的原始值。
+
+    参数:
+        value: 原生int、float、bool、str或None；不接受数组、容器和自定义对象。
+    返回:
+        None: 只验证值属于允许的不可变标量类型。有效性、数值范围和声明类型
+        由后续模型及数值层检查，None和非有限浮点可以保留为诊断值。
+    异常:
+        TypeError: 输入不是允许的原生标量类型。
+    """
+    # 精确类型避免自定义数值子类或容器携带可变状态。
+    if type(value) not in SCALAR_TYPES:
+        # 数组标量不能未经适配校验就伪装成逻辑输入。
+        raise TypeError("逻辑值仅接受原生int/float/bool/str/None")

chronaxis/core/window_delta.py

@@ -0,0 +1,123 @@
+"""声明完整窗口变化量的输入、配置和结果，不读取文件或保存触发状态。
+
+输入是有限ZOH已经划分好的连续片段，坐标为整数纳秒，数值保留声明dtype。
+片段起点的真实点质量可以不同于连续质量，例如真实EOF样本仍有效，但不能
+向EOF后保持。两个后端共用结构检查；数值、覆盖率和单调判断分别实现。
+结果把数值变化量与条件真假分开，缺数据不返回零，也不在这里生成事件。
+"""
+
+from dataclasses import dataclass
+from math import isfinite
+from .types import QualityFlag as Q, SignalDType as D, Truth
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class WindowDeltaSpec:
+    """保存窗口长度、方向、阈值及单调要求；只接受完整覆盖政策。"""
+
+    window_ns: int  # 完整回看长度，必须为正。
+    threshold: int | float  # 非负门槛，单位与输入相同，包含等于门槛。
+    direction: str = 'any'  # rise末减首，fall首减末，any取绝对差。
+    monotonic: bool = False  # rise非降、fall非升、any二者任一。
+    coverage_policy: str = 'full'  # 样本兼容口径不在本核心隐式启用。
+
+    def __post_init__(self):
+        """检查明确参数，不从名字猜时长或单位。
+
+        参数: 无，读取冻结字段。返回: None。异常: 类型、非有限或范围错误。
+        """
+        object.__setattr__(self, 'window_ns', require_int64_ns(self.window_ns))
+        if self.window_ns <= 0 or self.direction not in ('rise', 'fall', 'any'):
+            raise ValueError('window_delta窗口须为正，方向须为rise/fall/any')
+        if type(self.monotonic) is not bool or type(self.threshold) not in (int, float):
+            raise TypeError('monotonic需bool，threshold需数值且不能为bool')
+        if self.threshold < 0 or (type(self.threshold) is float and not isfinite(self.threshold)):
+            raise ValueError('threshold须为非负有限数值')
+        if self.coverage_policy != 'full':
+            raise ValueError('当前window_delta仅支持full覆盖政策')
+
+
+@dataclass(frozen=True)
+class DeltaSpan:
+    """保存一段常值和起点点值；零长度仅用于真实末点。
+
+    quality适用于[start_ns,end_ns)，point_quality适用于start_ns。
+    值为None时两种质量都须说明无效原因。时间到期不能通过延长end_ns补齐。
+    """
+
+    start_ns: int  # 当前更新或有效性边界。
+    end_ns: int  # 连续值排除的右端。
+    value: int | float | None  # 规范后的原生数值，未知可为None。
+    quality: Q = Q.NONE  # 连续区间无效原因。
+    point_quality: Q | None = None  # 默认与连续质量相同。
+
+    def __post_init__(self):
+        """规范纳秒和点质量，并检查有值证据。
+
+        参数: 无。返回: None。异常: 类型、倒序或未知无原因。
+        """
+        object.__setattr__(self, 'start_ns', require_int64_ns(self.start_ns))
+        object.__setattr__(self, 'end_ns', require_int64_ns(self.end_ns))
+        if self.end_ns < self.start_ns:
+            raise ValueError('DeltaSpan终点不得早于起点')
+        if not isinstance(self.quality, Q):
+            raise TypeError('DeltaSpan质量需QualityFlag')
+        if self.point_quality is None:
+            object.__setattr__(self, 'point_quality', self.quality)
+        if not isinstance(self.point_quality, Q):
+            raise TypeError('DeltaSpan点质量需QualityFlag')
+        if self.value is None:
+            if self.quality == Q.NONE or self.point_quality == Q.NONE:
+                raise ValueError('没有数值必须注明未知原因')
+        elif type(self.value) not in (int, float):
+            raise TypeError('DeltaSpan值需原生int/float或None')
+
+
+@dataclass(frozen=True)
+class WindowDeltaResult:
+    """保存一次窗口结果；value与方向一致，condition额外考虑单调要求。
+
+    valid_duration_ns只计完整窗口内已知连续时间；端点无效也会令条件UNKNOWN，
+    即使连续覆盖率恰好为1。monotonic是对应方向的实测结果，未知时为None。
+    """
+
+    time_ns: int  # 当前判断时刻。
+    window_start_ns: int  # 精确Python整数，不因回看低于int64下限回绕。
+    value: int | float | None  # 定宽差值或None，绝不以0替代未知。
+    condition: Truth  # TRUE/FALSE/UNKNOWN。
+    quality: Q  # UNKNOWN原因；已知为NONE。
+    valid_duration_ns: int  # 已知连续时间长度。
+    coverage: float  # 已知时间/完整窗口时长。
+    monotonic: bool | None  # 对应方向是否单调。
+
+
+def validate_delta_input(spec, spans, time_ns, dtype):
+    """检查两个数值核共用的结构及dtype，不计算变化量或单调性。
+
+    参数: spec配置，spans不可变有序片段，time_ns判断时间，dtype声明类型。
+    返回: 规范int判断时间。异常: 类型、重叠、非法值或dtype范围错误。
+    """
+    time_ns = require_int64_ns(time_ns)
+    if not isinstance(spec, WindowDeltaSpec) or type(spans) is not tuple:
+        raise TypeError('窗口需要WindowDeltaSpec及DeltaSpan tuple')
+    if dtype not in (D.INT64, D.UINT64, D.FLOAT64):
+        raise TypeError('window_delta只支持数值信号')
+    previous = None
+    for item in spans:
+        # 重叠输入会重复计算覆盖率，不能在核中悄悄排序或合并。
+        if not isinstance(item, DeltaSpan):
+            raise TypeError('窗口输入需DeltaSpan')
+        if previous is not None and (item.start_ns < previous.end_ns or item.start_ns <= previous.start_ns):
+            raise ValueError('窗口片段必须严格有序且不重叠')
+        previous = item
+        if item.value is None or (item.quality != Q.NONE and item.point_quality != Q.NONE):
+            continue
+        if dtype is D.FLOAT64:
+            if type(item.value) is not float or not isfinite(item.value):
+                raise ValueError('有效float64输入须为有限原生float')
+        elif type(item.value) is not int:
+            raise TypeError('有效整数信号不能隐式转浮点')
+        elif not (-(2**63) <= item.value < 2**63 if dtype is D.INT64 else 0 <= item.value < 2**64):
+            raise ValueError('有效数值超出声明dtype')
+    return time_ns

chronaxis/core/window_delta_numpy.py

@@ -0,0 +1,78 @@
+"""用数组掩码计算窗口覆盖、首尾位置和整窗单调性。
+
+输入和输出与独立参考一致；实际使用searchsorted、区间裁剪、质量掩码和
+相邻数组比较，不调用参考核。时间在整数域裁剪后才建立数组，避免下限回绕。
+数值保留int64/uint64/float64，不将大整数转换成浮点。无文件和状态副作用。
+"""
+
+import numpy as np
+from .types import QualityFlag as Q, SignalDType as D, Truth
+from .window_delta import WindowDeltaResult, validate_delta_input
+
+
+def window_delta_numpy(spec, spans, time_ns, dtype):
+    """通过真实数组运算计算一个窗口，不复用参考算法的数值函数。
+
+    参数: spec配置、spans有序DeltaSpan tuple、time_ns纳秒、dtype类型。
+    返回: WindowDeltaResult。异常: 输入错误；数值失败记录质量。
+    """
+    time_ns = validate_delta_input(spec, spans, time_ns, dtype)
+    left = time_ns - spec.window_ns
+    starts = np.asarray([item.start_ns for item in spans], dtype=np.int64)
+    ends = np.asarray([item.end_ns for item in spans], dtype=np.int64)
+    flags = np.asarray([int(item.quality) for item in spans], dtype=np.uint16)
+    points = np.asarray([int(item.point_quality) for item in spans], dtype=np.uint16)
+    # 每个交叠长度不超过window_ns，求和不超过同一窗口，定宽时间运算安全。
+    lower = np.maximum(starts, max(left, -(2**63)))
+    upper = np.minimum(ends, time_ns)
+    overlap = lower < upper
+    lengths = np.zeros(len(spans), dtype=np.int64)
+    np.subtract(upper, lower, out=lengths, where=overlap)
+    duration = int(np.sum(lengths, where=flags == 0, initial=0, dtype=np.int64))
+    quality = Q(int(np.bitwise_or.reduce(flags[overlap], initial=0)))
+    indices = []
+    for boundary in (left, time_ns):
+        # left可能低于int64下限，先处理后再交给searchsorted，防隐式浮点比较。
+        index = -1 if boundary < -(2**63) else int(np.searchsorted(starts, boundary, side='right')) - 1
+        if index < 0 or not (starts[index] == boundary or boundary < ends[index]):
+            quality |= Q.MISSING
+            indices.append(None)
+        else:
+            indices.append(index)
+            quality |= Q(int(points[index] if starts[index] == boundary else flags[index]))
+    middle = (starts > max(left, -(2**63))) & (starts < time_ns)
+    # 当left低于最小时间时，最小时间处仍属于窗口内观测。
+    if left < -(2**63):
+        middle = starts < time_ns
+    quality |= Q(int(np.bitwise_or.reduce(points[middle], initial=0)))
+    if duration != spec.window_ns:
+        quality |= Q.MISSING
+    if quality != Q.NONE:
+        return WindowDeltaResult(time_ns, left, None, Truth.UNKNOWN, quality,
+                                 duration, duration / spec.window_ns, None)
+    first, last = (spans[index].value for index in indices)
+    values = np.asarray([first, *(item.value for item, include in zip(spans, middle) if include), last],
+                        dtype=dtype.value)
+    nondecreasing = bool(np.all(values[1:] >= values[:-1]))
+    nonincreasing = bool(np.all(values[1:] <= values[:-1]))
+    monotonic = (nondecreasing if spec.direction == 'rise' else nonincreasing
+                 if spec.direction == 'fall' else nondecreasing or nonincreasing)
+    a, b = (values[0], values[-1]) if spec.direction == 'fall' else (values[-1], values[0])
+    if spec.direction == 'any' and a < b:
+        a, b = b, a
+    # 减法前用范围不等式证明安全，防止numpy先回绕；无隐藏float提升。
+    if dtype is D.INT64:
+        aa, bb = int(a), int(b)
+        if (bb > 0 and aa < -(2**63) + bb) or (bb < 0 and aa > 2**63 - 1 + bb):
+            quality = Q.OVERFLOW
+    elif dtype is D.UINT64 and a < b:
+        quality = Q.OVERFLOW
+    if quality != Q.NONE:
+        return WindowDeltaResult(time_ns, left, None, Truth.UNKNOWN, quality, duration, 1.0, monotonic)
+    with np.errstate(over='ignore', invalid='ignore'):
+        value = np.subtract(a, b).item()
+    if dtype is D.FLOAT64 and not np.isfinite(value):
+        return WindowDeltaResult(time_ns, left, None, Truth.UNKNOWN, Q.NONFINITE, duration, 1.0, monotonic)
+    satisfied = value >= spec.threshold and (not spec.monotonic or monotonic)
+    return WindowDeltaResult(time_ns, left, value, Truth.TRUE if satisfied else Truth.FALSE,
+                             Q.NONE, duration, 1.0, monotonic)

chronaxis/core/window_delta_reference.py

@@ -0,0 +1,69 @@
+"""用独立Python遍历计算完整窗口变化量，作为数组实现的数值参考。
+
+输入是有界ZOH片段和一个查询时刻，输出数值、三值条件和覆盖率。
+首尾使用点值，窗内使用实际观测及连续片段；缺口不插值、不延长有效期。
+本模块不依赖NumPy，不读文件，不保存跨调用状态或触发锁存。
+"""
+
+from math import isfinite
+from .types import QualityFlag as Q, SignalDType as D, Truth
+from .window_delta import WindowDeltaResult, validate_delta_input
+
+
+def window_delta_reference(spec, spans, time_ns, dtype):
+    """逐段求完整窗口首尾差和方向单调性。
+
+    参数: spec配置、spans有序DeltaSpan tuple、time_ns纳秒、dtype数值类型。
+    返回: WindowDeltaResult；阈值比较包含等于，UNKNOWN不伪装False。
+    异常: 输入结构错误；定宽数值溢出以质量结果返回。
+    """
+    time_ns = validate_delta_input(spec, spans, time_ns, dtype)
+    left = time_ns - spec.window_ns
+    duration, quality, first, last, observations = 0, Q.NONE, None, None, []
+    first_found = last_found = False
+    for item in spans:
+        # 左端在边界上优先用该边界真实点；内部位置沿有限ZOH。
+        if item.start_ns == left or item.start_ns < left < item.end_ns:
+            first_found = True
+            first = item.value
+            quality |= item.point_quality if item.start_ns == left else item.quality
+        if item.start_ns == time_ns or item.start_ns < time_ns < item.end_ns:
+            last_found = True
+            last = item.value
+            quality |= item.point_quality if item.start_ns == time_ns else item.quality
+        lo, hi = max(left, item.start_ns), min(time_ns, item.end_ns)
+        if lo < hi:
+            if item.quality == Q.NONE:
+                duration += hi - lo
+            else:
+                quality |= item.quality
+        # 边界值与窗内真实观测都参与单调性，不能只比较两个端点。
+        if left < item.start_ns < time_ns:
+            quality |= item.point_quality
+            observations.append(item.value)
+    if not first_found or not last_found or duration != spec.window_ns:
+        quality |= Q.MISSING
+    if quality != Q.NONE:
+        return WindowDeltaResult(time_ns, left, None, Truth.UNKNOWN, quality,
+                                 duration, duration / spec.window_ns, None)
+    values = [first, *observations, last]
+    nondecreasing = all(a <= b for a, b in zip(values, values[1:]))
+    nonincreasing = all(a >= b for a, b in zip(values, values[1:]))
+    monotonic = (nondecreasing if spec.direction == 'rise' else nonincreasing
+                 if spec.direction == 'fall' else nondecreasing or nonincreasing)
+    # Python整数先算真实差值再检查定宽范围，避免溢出后拿回绕值判断阈值。
+    value = first - last if spec.direction == 'fall' else last - first
+    if spec.direction == 'any':
+        value = abs(value)
+    if dtype is D.FLOAT64 and not isfinite(value):
+        quality = Q.NONFINITE
+    elif dtype is D.INT64 and not -(2**63) <= value < 2**63:
+        quality = Q.OVERFLOW
+    elif dtype is D.UINT64 and not 0 <= value < 2**64:
+        quality = Q.OVERFLOW
+    if quality != Q.NONE:
+        return WindowDeltaResult(time_ns, left, None, Truth.UNKNOWN, quality,
+                                 duration, 1.0, monotonic)
+    satisfied = value >= spec.threshold and (not spec.monotonic or monotonic)
+    return WindowDeltaResult(time_ns, left, value, Truth.TRUE if satisfied else Truth.FALSE,
+                             Q.NONE, duration, 1.0, monotonic)

chronaxis/core/windows.py

@@ -0,0 +1,224 @@
+"""声明事件窗口和片段结果，校验归属并保存请求、实际边界与原活动关联。
+
+输入是WindowSpec、已完成Event元组及真实观测Interval；独立后端负责扩展、
+分组和裁剪，再由本模块包装Segment。片段合并不重写Event或填平条件未知。
+核心执行模型独立于上层JSON WindowPlan，由执行层显式转换，避免核心导入配置/I/O。
+本模块只验证协议、归类和生成稳定ID；不计算窗口数值、不读取旧日志或调用writer。
+输入与返回均为完整内存模型；资源预算和原始报文导出由上层负责。
+"""
+
+# 冻结结构保留边界和身份，标准库hash只生成结果标识。
+from dataclasses import dataclass
+from hashlib import sha256
+import json
+from math import isclose, isfinite
+# 所有时间与来源位置为typed模型。
+from .models import Interval, SourceRef
+from .temporal import Event
+from .types import QualityFlag as Q
+from .validation import require_identifier, require_text
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class WindowSpec:
+    """声明围绕同一规则事件的前后范围及明确合并政策。
+
+    anchor为point或activity；pre/post为非负int64纳秒。point至少一项正。
+    exit_delay仅用于activity且post=0，根据真实活动间隔分组，不能按pre重叠扩大。
+    实例不保存执行状态，不依赖上层配置或旧模式的隐式参数解释。
+    """
+
+    window_id: str  # 当前窗口唯一简单标识。
+    event_rule_id: str  # 已完成事件的规则标识。
+    anchor: str  # point或activity，以onset/点时刻为锚。
+    pre_ns: int = 0  # 非负前扩展，不使用confirmed代替onset。
+    post_ns: int = 0  # 非负后扩展，exit_delay模式必须0。
+    merge: str = 'none'  # none/overlap/overlap_and_adjacent/exit_delay。
+    exit_delay_ns: int | None = None  # 只用于同名合并模式，不能重复附加post。
+
+    def __post_init__(self):
+        """检查窗口声明，不计算边界或创建运行状态。
+
+        参数: 无；读取冻结字段。
+        返回: None。
+        异常: TypeError/ValueError/OverflowError为标识、参数或时间协议错误。
+        """
+        # 名称与真实引用分开，不能用自由路径冒充规则标识。
+        require_identifier(self.window_id, 'window_id')
+        require_identifier(self.event_rule_id, 'event_rule_id')
+        # 精确非负纳秒，不接受bool、float或非法模式。
+        object.__setattr__(self, 'pre_ns', require_int64_ns(self.pre_ns, 'pre_ns'))
+        object.__setattr__(self, 'post_ns', require_int64_ns(self.post_ns, 'post_ns'))
+        if self.pre_ns < 0 or self.post_ns < 0 or self.anchor not in ('point', 'activity') or self.merge not in ('none', 'overlap', 'overlap_and_adjacent', 'exit_delay'):
+            raise ValueError('窗口锚点、扩展或合并政策错误')
+        # 点本身没有持续长度，必须明确扩展出窗口。
+        if self.anchor == 'point' and self.pre_ns == self.post_ns == 0:
+            raise ValueError('point窗口至少一个扩展为正')
+        # single只有退出延迟扩展，不能再附加同值post。
+        if self.merge == 'exit_delay':
+            object.__setattr__(self, 'exit_delay_ns', require_int64_ns(self.exit_delay_ns, 'exit_delay_ns'))
+            if self.anchor != 'activity' or self.post_ns != 0 or self.exit_delay_ns < 0:
+                raise ValueError('exit_delay要求activity、post=0及非负delay')
+        elif self.exit_delay_ns is not None:
+            raise ValueError('exit_delay_ns仅用于exit_delay合并')
+
+
+@dataclass(frozen=True)
+class Segment:
+    """保存一个片段的请求与实际范围，并关联全部原事件。
+
+    requested永不因EOF裁剪重写；actual为真实交集或None。覆盖为实际/请求时长。
+    status为complete、partial或empty；event_statuses保留closed/timeout/interrupted/truncated/point。
+    parent_event_ids、质量和字段来源不可变；合并不改变原事件数量或统计scope。
+    """
+
+    segment_id: str  # 内容SHA，区别于旧整数秒文件名。
+    dataset_id: str  # 当前数据集归属。
+    session_id: str  # 当前真实会话，不跨会话合并。
+    window: WindowSpec  # 原窗口声明，保留合并政策。
+    requested: Interval  # 完整请求半开范围。
+    actual: Interval | None  # 裁剪后实际范围，无交集为None。
+    requested_coverage: float  # 两后端独立计算的时长比。
+    status: str  # complete/partial/empty，不冒充文件发布完成。
+    parent_event_ids: tuple[str, ...]  # 全部原活动/点事件稳定关联。
+    event_statuses: tuple[str, ...]  # 同长原事件结束状态，UNKNOWN中断不改closed。
+    quality: Q  # 全部原事件的结束质量及依赖诊断。
+    source_refs: tuple[SourceRef, ...]  # 当前所有依赖原字段引用。
+
+    def __post_init__(self):
+        """检查片段归属、范围、覆盖及原事件引用的一致性。
+
+        参数: 无；读取全部冻结字段。
+        返回: None，不补范围或静默改覆盖。
+        异常: TypeError/ValueError/OverflowError为非法结果模型。
+        """
+        # 稳定文本与简单会话标识各自校验。
+        require_text(self.segment_id, 'segment_id')
+        require_identifier(self.dataset_id, 'dataset_id')
+        require_identifier(self.session_id, 'session_id')
+        if not isinstance(self.window, WindowSpec) or not isinstance(self.requested, Interval) or self.requested.duration_ns() == 0:
+            raise TypeError('Segment需WindowSpec及正请求Interval')
+        # 交集必须在原请求内，不能外推或接受自由对象。
+        if self.actual is not None and (not isinstance(self.actual, Interval) or self.actual.start_ns < self.requested.start_ns or self.actual.end_ns > self.requested.end_ns):
+            raise ValueError('Segment实际范围必须是请求子区间')
+        actual_duration = 0 if self.actual is None else self.actual.duration_ns()
+        # 完整/部分/空范围由真实边界判定，不仅靠浮点比值。
+        expected_status = 'complete' if self.actual == self.requested else 'partial' if actual_duration else 'empty'
+        if self.status != expected_status or type(self.requested_coverage) not in (int, float) or not isfinite(self.requested_coverage) or not 0 <= self.requested_coverage <= 1:
+            raise ValueError('Segment状态或覆盖错误')
+        # 独立float64比值只容许相对舍入差；绝对容差为0，极小正覆盖不能伪报为0。
+        if not isclose(self.requested_coverage, actual_duration / self.requested.duration_ns(), rel_tol=1e-15, abs_tol=0.):
+            raise ValueError('Segment覆盖与时间事实不一致')
+        # 每个原事件都有唯一ID与保留的结束状态。
+        if not isinstance(self.parent_event_ids, tuple) or not self.parent_event_ids or len(set(self.parent_event_ids)) != len(self.parent_event_ids):
+            raise ValueError('Segment需非空唯一parent_event_ids')
+        for identity in self.parent_event_ids:
+            require_text(identity, 'parent_event_id')
+        if not isinstance(self.event_statuses, tuple) or len(self.event_statuses) != len(self.parent_event_ids) or any(status not in ('closed', 'timeout', 'interrupted', 'truncated', 'point') for status in self.event_statuses):
+            raise ValueError('Segment事件状态需同长完整tuple')
+        if not isinstance(self.quality, Q) or not isinstance(self.source_refs, tuple) or any(not isinstance(ref, SourceRef) for ref in self.source_refs):
+            raise TypeError('Segment质量与来源需typed模型')
+
+
+def require_windows(events, spec, observation):
+    """验证已完成事件的排序、规则/会话归属和真实观测范围。
+
+    参数: events为已排序Event tuple；spec为WindowSpec；observation为真实Interval。
+    返回: None，只校验协议，不扩展或合并窗口。
+    异常: TypeError/ValueError为类型、重复、回退、归属或锚点不匹配。
+    """
+    # 上层负责取得真实观测，不以请求domain补齐EOF。
+    if not isinstance(events, tuple) or not isinstance(spec, WindowSpec) or not isinstance(observation, Interval) or any(not isinstance(event, Event) for event in events):
+        raise TypeError('窗口执行需Event tuple/WindowSpec/Interval')
+    identities = set()
+    previous = None
+    for event in events:
+        # 同一窗口仅使用同一规则/数据集/会话；不重新排序以掩盖回退。
+        if event.rule.rule_id != spec.event_rule_id or event.event_type != spec.anchor or event.event_id in identities:
+            raise ValueError('窗口事件规则、锚点或唯一性不匹配')
+        # start_only的固定结束与抑制时长是同一声明，不能额外合并或改变post。
+        if event.rule.rule_type == 'start_only' and (spec.merge != 'none' or spec.post_ns != event.rule.window_duration_ns):
+            raise ValueError('start_only窗口需merge=none且post等于固定时长')
+        if previous is not None and (event.start_ns < previous.start_ns or (event.rule.dataset_id, event.rule.session_id) != (previous.rule.dataset_id, previous.rule.session_id)):
+            raise ValueError('窗口事件不能回退或跨会话合并')
+        # 相同持续规则的真实活动不能重叠；点同刻不同规则已被上面拒绝。
+        if previous is not None and spec.anchor == 'activity' and event.start_ns < previous.end_ns:
+            raise ValueError('同一规则真实活动不能重叠')
+        if event.start_ns < observation.start_ns or (event.start_ns if event.end_ns is None else event.end_ns) > observation.end_ns:
+            raise ValueError('事件事实超出实际观测范围')
+        identities.add(event.event_id)
+        previous = event
+
+
+@dataclass(frozen=True)
+class CompactSegment:
+    """仅保实际业务范围和父事件关联，不输出重复请求边界、覆盖比例或来源副本。"""
+    segment_id: str
+    dataset_id: str
+    session_id: str
+    window_id: str
+    actual: Interval | None
+    status: str
+    parent_event_ids: tuple[str,...]
+    quality: Q
+    coverage: float | None = None  # 仅下游明确设置覆盖门槛时计算，默认不保存。
+
+
+def require_resolved_windows(events,bounds,compact):
+    """检查预先按选定周期取得的实际边界，未提供时沿旧实际扩展。
+
+    参数: 原事件、可选同长(start,end,left_clipped,right_clipped)tuple、精简开关。
+    返回: None。异常: 类型/长度/边界错误。副作用: 不构造另一时间轴。
+    """
+    if type(compact) is not bool:
+        raise TypeError('compact需要bool')
+    if bounds is None:
+        return
+    if not compact or type(bounds) is not tuple or len(bounds)!=len(events):
+        raise ValueError('已解析边界仅用于精简窗口且需同长tuple')
+    for item in bounds:
+        if type(item) is not tuple or len(item)!=4 or any(type(v) is not bool for v in item[2:]):
+            raise TypeError('窗口边界需起止与两侧裁剪标识')
+        Interval(item[0],item[1])
+
+
+def make_segment(spec, requested, actual, coverage, parents, *, compact=False, clipped=False):
+    """包装独立后端的边界/覆盖事实，保留全部原活动元数据。
+
+    参数: spec原窗口；requested/actual已算边界；coverage独立时长比；parents非空Event tuple；
+        compact仅构造精简业务输出，clipped说明选定周期已在输入首尾裁剪。
+    返回: Segment，稳定ID包含窗口语义、原事件引用与请求/实际边界。
+    异常: 输出模型不满足约束时传播检查异常。
+    副作用: 无；不计算扩展、分组或窗口覆盖，不修改Event。
+    """
+    # 原活动ID与状态保持顺序；元数据归并不涉及数值或旧扫描。
+    identities = tuple(event.event_id for event in parents)
+    if compact:
+        quality=Q.NONE
+        for event in parents:
+            quality|=event.quality
+        if actual is not None and not actual.duration_ns():
+            actual=None
+        status='empty' if actual is None else 'partial' if clipped or actual!=requested else 'complete'
+        payload=('window-v2',spec.window_id,identities,None if actual is None else (actual.start_ns,actual.end_ns),status)
+        identity=sha256(json.dumps(payload,separators=(',',':')).encode('utf-8')).hexdigest()
+        return CompactSegment(identity,parents[0].rule.dataset_id,parents[0].rule.session_id,
+                              spec.window_id,actual,status,identities,quality)
+    statuses = tuple(event.status for event in parents)
+    quality = Q.NONE
+    refs = []
+    for event in parents:
+        quality |= event.quality | event.dependency_quality
+        for ref in event.source_refs:
+            if ref not in refs:
+                refs.append(ref)
+    # 稳定规范JSON生成ID；裁剪范围和配置变化对应不同片段身份。
+    payload = ('window-v1', spec.window_id, spec.event_rule_id, spec.anchor, spec.pre_ns, spec.post_ns,
+               spec.merge, spec.exit_delay_ns, identities, requested.start_ns, requested.end_ns,
+               None if actual is None else (actual.start_ns, actual.end_ns))
+    identity = sha256(json.dumps(payload, separators=(',', ':')).encode('utf-8')).hexdigest()
+    # 分类只是输出政策，不复用任一后端的扩展或分组算法。
+    status = 'complete' if actual == requested else 'partial' if actual is not None and actual.duration_ns() else 'empty'
+    return Segment(identity, parents[0].rule.dataset_id, parents[0].rule.session_id, spec, requested, actual,
+                   coverage, status, identities, statuses, quality, tuple(refs))