chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/integral_sum.py

@@ -0,0 +1,77 @@
+"""声明整窗积分数值归约结果和容量门槛，不执行数值求和。
+
+两个独立数值核接收原序面积项，输出尚未分类覆盖状态的冻结数值结果。
+面积先在输入单位乘秒下累计，最终只转换一次；覆盖和来源另由事实 owner 保存。
+本模块不导入 NumPy、不读写文件，也不提供独立内存预算。
+"""
+
+# 共享协议与输入门槛，不共享求和或浮点误差计算。
+from dataclasses import dataclass
+from math import isfinite
+from .types import QualityFlag as Q
+from .validation import require_text
+
+
+class IntegralStateLimitError(ValueError):
+    """表示误差项超过显式容量，调用方须停止当前归约并清理资源。
+
+    不截断误差项，也不把容量不足伪装为正常数值或 NONFINITE。
+    """
+
+
+def require_partial_limit(limit: int) -> int:
+    """校验误差项数量的硬上限。
+
+    参数: limit 为正原生整数。返回: 原值。异常: ValueError 为 bool、非整数或非正数。
+    """
+    # 容量是精确计数，拒绝布尔、浮点或无限制配置。
+    if type(limit) is not int or limit <= 0:
+        raise ValueError('积分误差项容量需要正原生int')
+    return limit
+
+
+def require_sum_finish(unit: str, factor: float) -> tuple[str, float]:
+    """校验纯核的输出标签及一次性转换因子。
+
+    参数: unit 为非空标签；factor 为正有限原生 float。返回: (unit, factor)。
+    异常: TypeError/ValueError 为文字或因子错误；单位维度由外层 calculation_unit 校验。
+    """
+    # 纯核不能凭单位文本推导因子，外层须先核对已注册的维度转换。
+    require_text(unit, 'integral.output_unit')
+    if type(factor) is not float or not isfinite(factor) or factor <= 0:
+        raise ValueError('积分转换因子需要正有限原生float')
+    return unit, factor
+
+
+@dataclass(frozen=True)
+class IntegralSumResult:
+    """保存已换单位的数值快照，不代替覆盖和最终 CalculationResult 分类。
+
+    valid_term_count 统计参与累计的有效面积项，与实际信号更新样本数不同。
+    无有效项时 value 为 None；有有效零面积时 value 为 0.0。
+    """
+
+    value: float | None  # 最终单位下的有限面积，未知或计算失败为 None。
+    unit: str  # 已由调用方声明的最终输出单位。
+    calculation_failed: bool  # 数值求和或最终转换失败，不表示输入全部未知。
+    quality: Q  # 本次数值归约诊断，输入覆盖质量另保留在 IntegralFacts。
+    valid_term_count: int  # 原序有效面积项数，不冒充真实样本计数。
+
+    def __post_init__(self):
+        """拒绝矛盾的冻结结果，不自动补零或修正故障。
+
+        参数: 无。返回: None。异常: TypeError/ValueError 为结构或状态不一致。
+        """
+        # 标签、计数和诊断保持真实类型，拒绝 bool 当作整数计数。
+        require_text(self.unit, 'integral.output_unit')
+        if (type(self.calculation_failed) is not bool or not isinstance(self.quality, Q)
+                or type(self.valid_term_count) is not int or self.valid_term_count < 0):
+            raise TypeError('积分数值结果需要真实状态、质量和非负整数计数')
+        if self.value is not None and (type(self.value) is not float or not isfinite(self.value)):
+            raise ValueError('积分数值结果只接受有限float或None')
+        # 未知与失败都不得借零值冒充成功，成功的有效项必须有明确数值。
+        if self.calculation_failed:
+            if self.value is not None or self.quality == Q.NONE or self.valid_term_count == 0:
+                raise ValueError('积分计算失败需要有效项、None值及明确质量原因')
+        elif ((self.valid_term_count == 0) != (self.value is None)) or self.quality != Q.NONE:
+            raise ValueError('积分成功结果的数值、计数或质量不一致')

chronaxis/core/integral_sum_numpy.py

@@ -0,0 +1,224 @@
+"""用独立 NumPy 误差数组归约原序积分面积，最后一次换算输出单位。
+
+输入是有限块 NumpyIntegralTerms，只消费 valid 为 True 的 float64 面积；
+面积已经带有 input_unit 乘秒的量纲，本核不重复乘区间时长、不累计覆盖事实。
+跨块保存按绝对值递增、互不重叠的误差项，默认最多 4096 项；不保留历史面积。
+原序面积推进属于 state_driver；每项内部用真实 accumulate、ufunc 和掩码处理
+误差数组，不调用参考模块或 math.fsum，也不把整窗宣称为无状态数组求和。
+状态与临时数组均受 partial_limit 限制，输入索引受当前有限块长度限制；
+本纯核不管理预算或关闭资源，调用方须先预约相应空间并负责异常后的生命周期。
+finish 是不破坏状态的快照，单位换算故障只影响返回结果；原量纲累计溢出永久保留。
+"""
+
+# 仅共享结果模型、参数门槛和输入模型；数值误差推进由本模块独立实现。
+import numpy as np
+from .integral_sum import (IntegralStateLimitError, IntegralSumResult,
+                           require_partial_limit, require_sum_finish)
+from .integral_terms_numpy import NumpyIntegralTerms
+from .types import QualityFlag as Q
+
+
+class NumpyIntegralSum:
+    """保存有限 float64 误差项和有效项计数，保持跨块原序及持久溢出状态。
+
+    partials 只在完整单项候选满足容量后安装，不按输入项数增长；中途溢出
+    清空数值状态并永久标失败，但后续有效面积仍计数。输入和已返回结果不被修改。
+    """
+
+    def __init__(self, partial_limit: int = 4096):
+        """建立独立的空数组误差状态。
+
+        参数: partial_limit 为正原生 int，表示误差状态的最大项数。
+        返回: 无；初始化有效项数 0、累计故障 False 及空 float64 数组。
+        异常: TypeError/ValueError 为限额不合法；内存分配错误直接传播。
+        """
+        # 状态容量受显式限额约束；预约责任属于调用方，纯核不另开预算。
+        self._partial_limit = require_partial_limit(partial_limit)
+        self._partials = np.empty(0, dtype=np.float64)
+        self._valid_term_count = 0
+        self._calculation_failed = False
+
+    @property
+    def valid_term_count(self) -> int:
+        """读取已消费的有效面积数，包含导致中途溢出的项及其后续项。
+
+        参数: 无。返回: 非负原生 int。异常: 无。
+        """
+        # 计数不等同于有效时间或真实更新样本数，覆盖信息由外层独立累计。
+        return self._valid_term_count
+
+    @property
+    def calculation_failed(self) -> bool:
+        """读取原量纲累计中途非有限的持久标志。
+
+        参数: 无。返回: bool；finish 的单位换算故障不修改本属性。异常: 无。
+        """
+        # 失败不能通过后来抵消或再调用 finish 恢复为成功。
+        return self._calculation_failed
+
+    @property
+    def partial_count(self) -> int:
+        """读取当前持有的非零误差项数，不暴露可修改的数组。
+
+        参数: 无。返回: 不超过 partial_limit 的原生 int。异常: 无。
+        """
+        # 返回标量规模，调用方不能通过属性改写数值不变量。
+        return len(self._partials)
+
+    def push(self, terms: NumpyIntegralTerms) -> None:
+        """按输入顺序消费当前有限块的有效面积，不先对块求和。
+
+        参数: terms 为已校验的只读 float64 面积、bool 掩码和 IntegralFacts。
+        返回: None；安装成功的单项更新状态和有效计数，输入数组保持原样。
+        异常: TypeError 为输入类型错误；IntegralStateLimitError 为候选容量超限；
+        分配或取消错误传播。超限项不安装，其前面已成功消费的项保留。
+        """
+        try:
+            # typed 输入已保证同长有限面积；UNKNOWN 占位不能作为有效零参与归约。
+            if not isinstance(terms, NumpyIntegralTerms):
+                raise TypeError('数组积分归约需要 NumpyIntegralTerms')
+            # 保留原积分typed门槛，同后端通用入口承接完全相同的数值推进。
+            self.push_values(terms.areas, terms.valid)
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = terms = None
+
+    def push_values(self, values: np.ndarray, valid: np.ndarray) -> None:
+        """用本数组后端累计有限浮点项，不构造虚假的积分事实。
+
+        参数: values/valid 为同长只读普通一维float64/bool数组；未知位置只能存0。
+        返回: None；原序推进、容量、中间溢出及finish行为与积分入口相同。
+        异常: TypeError/ValueError 为结构或写保护错误；容量、分配和取消传播。
+        内存: 检查掩码与索引均为当前有限(N,)临时列，调用方必须先预约预算。
+        """
+        try:
+            # 拒绝自动cast、广播或可写别名；不把未知占位当正常数值。
+            if (type(values) is not np.ndarray or type(valid) is not np.ndarray
+                    or values.ndim != 1 or valid.ndim != 1
+                    or values.dtype != np.dtype('float64') or valid.dtype != np.dtype('bool')
+                    or len(values) != len(valid) or values.flags.writeable or valid.flags.writeable):
+                raise TypeError('数组原序归约需要同长只读float64/bool一维列')
+            if np.any(~np.isfinite(values)) or np.any(values[~valid] != 0):
+                raise ValueError('数组原序项需有限，未知位置只能存0')
+            # 当前块的索引空间为 O(N)，属于调用方有限块预约；不保存索引到跨块状态。
+            indices = np.flatnonzero(valid)
+            if self._calculation_failed:
+                self._valid_term_count += len(indices)
+                return
+            # 原序外层属于 state_driver；每项内的误差推进是独立的真实数组运算。
+            for index in indices:
+                if self._calculation_failed:
+                    self._valid_term_count += 1
+                    continue
+                candidate = self._advance(values[index])
+                # 容量检查已完成才安装；数值溢出单项仍计数，清空不再使用的误差状态。
+                if candidate is None:
+                    self._partials = np.empty(0, dtype=np.float64)
+                    self._calculation_failed = True
+                else:
+                    self._partials = candidate
+                self._valid_term_count += 1
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = values = valid = indices = candidate = None
+
+    def _advance(self, area: np.float64) -> np.ndarray | None:
+        """生成一项的独立误差候选，不提前改写当前状态。
+
+        参数: area 为有限 float64 面积，量纲仍为 input_unit 乘秒。
+        返回: float64 形状 (K,) 的新候选，K 不超过限额；中途非有限返回 None。
+        异常: IntegralStateLimitError 为候选超限；分配和取消错误传播。
+        """
+        try:
+            # (K+1,) accumulate 保留每一步 hi，递推顺序与原序 FastTwoSum 相同。
+            chain = np.concatenate((np.array([area], dtype=np.float64), self._partials))
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                highs = np.add.accumulate(chain, dtype=np.float64)
+            if not np.all(np.isfinite(highs)):
+                return None
+            # 每一步的旧 x 与 partial 并列为 (K,)；交换只用于找出绝对值较大的加数。
+            incoming, old = highs[:-1], self._partials
+            swap = np.abs(incoming) < np.abs(old)
+            large = np.where(swap, old, incoming)
+            small = np.where(swap, incoming, old)
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                lows = np.subtract(small, np.subtract(highs[1:], large))
+            # 非零 lo 按原误差顺序压紧；末 hi 为零时不追加，保留全零的空状态。
+            kept = lows[lows != 0]
+            last = highs[-1]
+            count = len(kept) + int(last != 0)
+            if count > self._partial_limit:
+                raise IntegralStateLimitError('数组积分误差状态超过 partial_limit')
+            # 新数组不借用 chain 的底层空间，跨块状态容量只包含实际保留的 K 项。
+            if last != 0:
+                return np.concatenate((kept, np.array([last], dtype=np.float64)))
+            return kept.copy()
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = area = chain = highs = incoming = old = None
+            swap = large = small = lows = kept = last = None
+
+    def finish(self, unit: str, factor: float = 1.0) -> IntegralSumResult:
+        """正确舍入当前误差状态，再做一次输出单位换算，返回独立快照。
+
+        参数: unit 为非空输出单位；factor 为正有限原生 float，仅在最后相乘。
+        返回: IntegralSumResult；没有有效项为 None，有效全零为 +0.0；累计或
+        换算非有限为 NONFINITE，非零换算下溢为 PRECISION_LOSS，均标计算失败。
+        异常: TypeError/ValueError 为参数错误；分配或取消错误传播。
+        """
+        try:
+            # 参数先校验；快照不消费或清空状态，外层 owner 决定是否锁定后续输入。
+            unit, factor = require_sum_finish(unit, factor)
+            if self._calculation_failed:
+                return IntegralSumResult(None, unit, True, Q.NONFINITE, self._valid_term_count)
+            if self._valid_term_count == 0:
+                return IntegralSumResult(None, unit, False, Q.NONE, 0)
+            # 空误差状态表示有效面积精确抵消或全零，不等同于没有有效面积。
+            raw = self._rounded() if len(self._partials) else np.float64(0.0)
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                converted = np.multiply(raw, np.float64(factor))
+            if not np.isfinite(raw) or not np.isfinite(converted):
+                return IntegralSumResult(None, unit, True, Q.NONFINITE, self._valid_term_count)
+            if raw != 0 and converted == 0:
+                return IntegralSumResult(None, unit, True, Q.PRECISION_LOSS, self._valid_term_count)
+            # 转为 Python float 仅用于冻结结果，不把数值推进交给参考或标量求和核。
+            return IntegralSumResult(float(converted), unit, False, Q.NONE, self._valid_term_count)
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = unit = factor = raw = converted = None
+
+    def _rounded(self) -> np.float64:
+        """从最大误差项向小项求和，在首个舍入误差处完成半偶修正。
+
+        参数: 无；当前状态必须至少包含一个非零有限 partial。
+        返回: 当前原量纲的正确舍入 float64；不修改误差数组。
+        异常: 分配或取消错误传播；数值非有限由 finish 分类。
+        """
+        try:
+            # 逆序是只读视图；后续向量计算全部局限于 (K,) 或 (K-1,) 的固定容量。
+            reverse = self._partials[::-1]
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                highs = np.add.accumulate(reverse, dtype=np.float64)
+                lows = np.subtract(reverse[1:], np.subtract(highs[1:], highs[:-1]))
+            inexact = np.flatnonzero(lows != 0)
+            if len(inexact) == 0:
+                return highs[-1]
+            # 首个非零 lo 已界定舍入位置，不能用后来多算的 hi 或故障污染这个结果。
+            position = int(inexact[0])
+            hi, lo = highs[position + 1], lows[position]
+            next_position = position + 2
+            if next_position < len(reverse):
+                smaller = reverse[next_position]
+                if (lo < 0 and smaller < 0) or (lo > 0 and smaller > 0):
+                    # 与下一更小 partial 同号时探测半偶修正；比较差值确保只跨正确的 ULP。
+                    with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                        doubled = np.multiply(lo, np.float64(2.0))
+                        corrected = np.add(hi, doubled)
+                        difference = np.subtract(corrected, hi)
+                    if doubled == difference:
+                        hi = corrected
+            return hi
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = reverse = highs = lows = inexact = None
+            hi = lo = smaller = doubled = corrected = difference = None

chronaxis/core/integral_sum_reference.py

@@ -0,0 +1,148 @@
+"""独立按原序累计积分面积，用有界浮点误差项保留大数抵消后的低位。
+
+输入为 ReferenceIntegralTerms，输出为最终单位下的 IntegralSumResult 快照。
+每项使用标量精确拆分，保存非重叠误差项；结束时用标准库 fsum 归约误差项。
+任何原序中间溢出永久失败；不会靠后续抵消恢复，也不会按块先求和。
+状态最多 partial_limit 项，不保存整窗面积；容量不足明确抛错而不截断。
+纯核无文件副作用，状态及候选内存由外层 owner 在调用前申请预算。
+"""
+
+# 参考实现独立依赖标准库，不调用数组归约、数组面积或数组对齐实现。
+from math import fsum, isfinite
+from .integral_sum import (IntegralSumResult, IntegralStateLimitError,
+                           require_partial_limit, require_sum_finish)
+from .integral_terms import ReferenceIntegralTerms
+from .types import QualityFlag as Q
+
+
+class ReferenceIntegralSum:
+    """持有有界非重叠误差项、有效面积计数及持久累计故障。
+
+    push 为原序状态驱动；finish 不清空状态，最终转换故障仅影响返回快照。
+    调用方在任意推进异常后须放弃当前累计并清理，不能接着使用半段输入。
+    """
+
+    def __init__(self, partial_limit: int = 4096):
+        """建立空累计状态。参数: partial_limit 为硬容量。返回: None。异常: 非法容量。
+        """
+        # 初始零项没有面积证据；不能提前返回正常零值。
+        self._limit = require_partial_limit(partial_limit)
+        self._partials = []
+        self._valid_terms = 0
+        self._failed = False
+
+    @property
+    def valid_term_count(self) -> int:
+        """读取有效面积项数。参数: 无。返回: int。异常: 无。"""
+        return self._valid_terms  # 与真实更新样本计数分开。
+
+    @property
+    def calculation_failed(self) -> bool:
+        """读取持久累计故障。参数: 无。返回: bool。异常: 无。"""
+        return self._failed  # 后续抵消不会清除此状态。
+
+    @property
+    def partial_count(self) -> int:
+        """读取当前误差项数量。参数: 无。返回: int。异常: 无。"""
+        return len(self._partials)  # 仅报告有界数值状态，不含输入面积。
+
+    def push(self, terms: ReferenceIntegralTerms) -> None:
+        """按原顺序推进有效面积，保留块间误差状态。
+
+        参数: terms 为有限冻结面积块。返回: None。
+        异常: TypeError 为后端不符；IntegralStateLimitError/MemoryError 为状态容量或分配失败。
+        """
+        try:
+            # 后端模型必须明确，不隐式把 NumPy 数据搬入标量参考核。
+            if not isinstance(terms, ReferenceIntegralTerms):
+                raise TypeError('参考归约需要ReferenceIntegralTerms')
+            # 原积分入口仍检查真实模型；同后端数值推进可用于其他已定义的原序浮点项。
+            self.push_values(terms.areas, terms.valid)
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = terms = None
+
+    def push_values(self, values: tuple[float, ...], valid: tuple[bool, ...]) -> None:
+        """累计有限原序浮点项，不要求调用方伪造积分事实。
+
+        参数: values/valid 为同长冻结tuple；数值为有限原生float，未知位置必须存0。
+        返回: None；使用与原积分入口相同的误差状态、容量及中间失败规则。
+        异常: TypeError/ValueError 为列结构；容量、分配或取消原样传播。
+        边界: 仅复用本参考后端数值算法；调用方负责量纲、覆盖与候选内存预算。
+        """
+        try:
+            # 完整门槛在推进前检查，错误输入不能留下半段新增状态。
+            if type(values) is not tuple or type(valid) is not tuple or len(values) != len(valid):
+                raise TypeError('原序参考归约需要同长tuple数值与掩码')
+            # 显式循环保持原any的逐项/短路顺序；取消时没有genexpr的隐藏zip保留整列。
+            for value, keep in zip(values, valid):
+                if (type(value) is not float or not isfinite(value) or type(keep) is not bool
+                        or not keep and value != 0):
+                    raise ValueError('参考归约需有限float及bool，未知位置存0')
+            # 保留原积分算法、原序、中间溢出和有界误差状态，不先归约块和。
+            for area, keep in zip(values, valid):
+                # 无效存储零不是数值证据；累计失败后仍统计后续有效项。
+                if not keep:
+                    continue
+                if self._failed or area == 0:
+                    self._valid_terms += 1
+                    continue
+                # state_driver: 每项在原序状态上拆分，不把块和作为新的输入。
+                candidate, current = [], area
+                for partial in self._partials:
+                    large, small = (current, partial) if abs(current) >= abs(partial) else (partial, current)
+                    high = large + small
+                    if not isfinite(high):
+                        # 原序中途溢出保持失败，后续负项不能把已失败计算恢复正常。
+                        self._failed = True
+                        candidate = []
+                        break
+                    low = small - (high - large)
+                    if low != 0:
+                        candidate.append(low)
+                    current = high
+                if self._failed:
+                    self._partials = []
+                    self._valid_terms += 1
+                    continue
+                # 零和不占用误差项；容量检查后才安装该项及其计数。
+                if current != 0:
+                    candidate.append(current)
+                if len(candidate) > self._limit:
+                    raise IntegralStateLimitError('积分误差项超过容量，不能截断继续')
+                self._partials = candidate
+                self._valid_terms += 1
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = values = valid = candidate = None
+            current = area = partial = large = small = high = low = None
+            value = keep = None
+
+    def finish(self, unit: str, factor: float = 1.0) -> IntegralSumResult:
+        """归约有界误差项并只转换一次，保留原累计状态。
+
+        参数: unit/factor 为外层核实的最终单位及倍率。返回: 冻结数值快照。
+        异常: 非法配置或分配错误传播；数值溢出/转换下溢写入失败结果。
+        """
+        try:
+            # 配置先校验，空证据和持久溢出保持 None，不能回退为零。
+            unit, factor = require_sum_finish(unit, factor)
+            if self._failed:
+                return IntegralSumResult(None, unit, True, Q.NONFINITE, self._valid_terms)
+            if self._valid_terms == 0:
+                return IntegralSumResult(None, unit, False, Q.NONE, 0)
+            try:
+                # 仅归约有界误差项；独立标准库求和不调用 NumPy 内核。
+                total = fsum(self._partials)
+            except OverflowError:
+                return IntegralSumResult(None, unit, True, Q.NONFINITE, self._valid_terms)
+            value = total * factor
+            if not isfinite(value):
+                return IntegralSumResult(None, unit, True, Q.NONFINITE, self._valid_terms)
+            if total != 0 and value == 0:
+                return IntegralSumResult(None, unit, True, Q.PRECISION_LOSS, self._valid_terms)
+            # 零值规范为 +0.0；成功的结果不混入输入未知质量。
+            return IntegralSumResult(0.0 if value == 0 else value, unit, False, Q.NONE, self._valid_terms)
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = unit = factor = total = value = None

chronaxis/core/integral_terms.py

@@ -0,0 +1,119 @@
+"""声明尚未归约的ZOH积分项及其覆盖、质量和来源事实。
+
+输入来自有限CalculationSeries块，输出按原区间顺序保留面积和有效掩码。
+面积单位为原输入单位乘秒，尚未应用输出单位因子；未知存储0必须结合掩码。
+本模块只校验冻结协议，不执行数值积分、文件读取或资源分配策略。
+纯核输出在调用方CalculationBlock的workspace内消费，独立留存须另计预算。
+参考模型用原生tuple；数组模型在对应NumPy模块定义，通用模型不导入NumPy。
+"""
+
+# 只共享typed事实与门槛，两数值核各自计算面积、有效性及覆盖。
+from dataclasses import dataclass
+from math import isfinite
+from .calculations import CalculationSeries, CalculationDefinition, calculation_unit
+from .calculations_reference import require_calculation
+from .models import Interval, SourceRef
+from .types import QualityFlag as Q
+from .validation import require_text
+
+
+@dataclass(frozen=True)
+class IntegralFacts:
+    """保留当前块的原请求、实际范围、可核实覆盖与来源，不负责最终归约。
+
+    只有value_valid_duration_ns表示有效面积时长；源诊断与计算质量完整OR。
+    此处没有条件FALSE证据，不能由空项推断条件空选择为零。
+    """
+
+    spec: CalculationDefinition  # 原请求窗口及最终部分结果政策，不按块覆盖重写。
+    actual_window: Interval | None  # 当前块与请求交集，无交集保持None。
+    value_valid_duration_ns: int  # 可核实面积时长，整数ns。
+    valid_sample_count: int  # 半开当前块内实际更新且可核实的样本数。
+    value_unknown_ranges: tuple[Interval, ...]  # 请求明细时的连续未知范围；未请求为空，不据此推断覆盖完整。
+    quality: Q  # 来源及精度/非有限/下溢等计算诊断。
+    input_unit: str  # 输入工程单位，面积尚未换为J/Ah等输出单位。
+    binding_identity: str  # 当前真实表达式身份。
+    source_refs: tuple[SourceRef, ...]  # 当前块完整真实定位，保留子类。
+
+    def __post_init__(self):
+        """校验事实结构和覆盖边界，不更正错误事实。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为类型或不可能覆盖。
+        """
+        # 原请求和实际交集需真实类型；覆盖计数的上界由实际纳秒跨度决定。
+        if not isinstance(self.spec, CalculationDefinition) or self.spec.operation != 'integral':
+            raise TypeError('积分项事实需要integral CalculationDefinition')
+        if self.actual_window is not None and not isinstance(self.actual_window, Interval):
+            raise TypeError('积分项实际范围需要Interval或None')
+        duration = 0 if self.actual_window is None else self.actual_window.end_ns - self.actual_window.start_ns
+        # 原生非负整数与真实时长上界，不把bool或浮点秒当ns。
+        if (type(self.value_valid_duration_ns) is not int or not 0 <= self.value_valid_duration_ns <= duration
+                or type(self.valid_sample_count) is not int or self.valid_sample_count < 0):
+            raise ValueError('积分项覆盖或样本数不合法')
+        # 未知范围是正区间，不能越过当前实际窗口或凭空建立观测。
+        if (type(self.value_unknown_ranges) is not tuple
+                or any(not isinstance(item, Interval) or item.start_ns >= item.end_ns
+                       or self.actual_window is None or item.start_ns < self.actual_window.start_ns
+                       or item.end_ns > self.actual_window.end_ns for item in self.value_unknown_ranges)):
+            raise ValueError('积分项未知范围必须位于实际窗口')
+        # 保留typed质量和完整来源子类，不把任意文字当来源事实。
+        if not isinstance(self.quality, Q) or type(self.source_refs) is not tuple or any(not isinstance(item, SourceRef) for item in self.source_refs):
+            raise TypeError('积分项需要typed质量与完整来源tuple')
+        # 来源文字不作为绑定证明，保留上层已验证身份和单位。
+        require_text(self.input_unit, 'integral.input_unit')
+        require_text(self.binding_identity, 'integral.binding_identity')
+
+
+@dataclass(frozen=True)
+class ReferenceIntegralTerms:
+    """保存标量参考的原序面积和显式有效掩码，不累计全窗口项。"""
+
+    areas: tuple[float, ...]  # 每个原区间的面积，未观察/无效位置为0存储占位。
+    valid: tuple[bool, ...]  # 只有True位置可参与后续数值归约。
+    facts: IntegralFacts  # 当前块覆盖/原请求/诊断，不是最终CalculationResult。
+
+    def __post_init__(self):
+        """校验同长冻结列及有限面积，拒绝用无效非零占位。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为列/掩码/面积错误。
+        """
+        # 面积/掩码必须同长冻结；有效与未知都不允许非有限存储。
+        if type(self.areas) is not tuple or type(self.valid) is not tuple or len(self.areas) != len(self.valid) or not isinstance(self.facts, IntegralFacts):
+            raise TypeError('参考积分项需要同长tuple及IntegralFacts')
+        if any(type(value) is not float or not isfinite(value) or type(keep) is not bool
+               or not keep and value != 0 for value, keep in zip(self.areas, self.valid)):
+            raise ValueError('参考积分面积需有限float，未知使用掩码及0存储')
+
+
+def require_valid_until(times, valid_until_ns):
+    """校验有限块的必要有效截止列。参数: 时间tuple/可选截止tuple。返回: None。异常: 类型/长度/范围错误。"""
+    if valid_until_ns is not None:
+        if type(valid_until_ns) is not tuple or len(valid_until_ns) != len(times):
+            raise TypeError('有效截止需要与驱动点同长的tuple')
+        for deadline in valid_until_ns:
+            if deadline is not None and (type(deadline) is not int or not -(1 << 63) <= deadline < (1 << 63)):
+                raise ValueError('有效截止需要int64实际时间或None')
+
+
+def require_integral_terms(series, spec, *, step_ns=None, valid_until_ns=None):
+    """共享输入/单位/可表示时长门槛，不共享数值内核。
+
+    参数: series为CalculationSeries，spec为原integral请求；step_ns为可选固定/DBC周期。
+        valid_until_ns为可选同长实际截止tuple，None项表示无额外有效截止。
+        指定周期时每点必须为所选驱动的真实更新，不能把TTL/窗口边界当报文。
+        调用方负责选驱动；本接口不接受尚未分配权重的混合时间轴。返回: None。
+    异常: 类型/dtype/算子/条件/单位配置错误；OverflowError为int64不可表示跨度。
+    """
+    # 沿用原输入类型门槛，条件与其他算子需待各自独立归约契约实现。
+    require_calculation(series, spec, step_ns=step_ns)
+    # 截止仅用于当前块的必要有效性计算；None沿用原无额外截止路径。
+    require_valid_until(series.times_ns, valid_until_ns)
+    if spec.operation != 'integral' or series.conditions is not None:
+        raise ValueError('当前积分项只支持无选择条件的integral')
+    # 预先验证最终单位配置，但本层不把返回因子应用到每块。
+    calculation_unit(spec, series.unit)
+    # 只防守正交集跨度，不以绝对坐标转浮点，也不延长原观测。
+    left = max(spec.window.start_ns, series.observation.start_ns)
+    right = min(spec.window.end_ns, series.observation.end_ns)
+    if right - left > 2 ** 63 - 1:
+        raise OverflowError('积分区间时长不能超过正int64')