chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/conditional_integral_terms.py

@@ -0,0 +1,146 @@
+"""声明有限条件积分项及值、条件各自的覆盖事实，不执行数值计算。
+
+条件为BOOL三值：TRUE且值可核实才产生面积，FALSE属于已知未选择，UNKNOWN
+不是FALSE。两种未知区间分别划分实际窗口，真实样本只计有效值更新且条件TRUE。
+ReferenceConditionalIntegralTerms保留原序面积与显式有效掩码，面积单位仍为
+原输入单位乘秒；不在块内归约或转换最终单位，空归约不代表正常零。
+本模块只校验冻结模型和公共输入门槛，不读文件、不改输入，也不申请预算；
+有限临时列和事实须由调用方owner事先预约，独立留存须另行计费。
+"""
+
+# 冻结协议与范围检查只依赖标准库；两面积核仅共享非数值输入门槛。
+from dataclasses import dataclass
+from math import isfinite
+from .calculations import CalculationDefinition, CalculationSeries, calculation_unit
+from .models import Interval, SourceRef
+from .types import QualityFlag as Q, SignalDType as D
+from .validation import require_text
+
+
+def _unknown_duration(ranges, actual):
+    """校验一种未知范围完整有序、不重叠且不越过实际窗口。
+
+    参数: ranges为冻结Interval tuple，actual为实际交集或None。
+    返回: 原生int纳秒未知总时长。异常: TypeError/ValueError为结构或不可能范围。
+    """
+    if type(ranges) is not tuple:
+        raise TypeError('条件积分未知范围需要tuple')
+    cursor, total = (actual.start_ns if actual is not None else 0), 0
+    # 只验证诊断几何，不能按总长度掩盖重复区间或已知缺口。
+    for item in ranges:
+        if (not isinstance(item, Interval) or actual is None or item.start_ns < cursor
+                or item.start_ns >= item.end_ns or item.end_ns > actual.end_ns):
+            raise ValueError('条件积分未知范围必须有序、不重叠且在实际窗口内')
+        cursor, total = item.end_ns, total + item.end_ns - item.start_ns
+    return total
+
+
+@dataclass(frozen=True)
+class ConditionalIntegralFacts:
+    """保存当前块原请求与完整覆盖，值缺失和条件未知分别说明。
+
+    known包含TRUE和FALSE；selected只计TRUE且面积可核实的时长。
+    selected_value_unknown只计TRUE而值/面积不可核实的时长，不混入条件UNKNOWN。
+    FALSE不乘面积，原值的类型和精度检查仍保留在值覆盖及质量中。
+    """
+
+    spec: CalculationDefinition  # 原integral请求、scope和部分结果政策。
+    actual_window: Interval | None  # 当前实际交集，不外推EOF。
+    value_valid_duration_ns: int  # 原值经积分可用性检查后的有效时长。
+    condition_known_duration_ns: int  # 可判断TRUE或FALSE的时长。
+    selected_duration_ns: int  # TRUE且值/面积可核实的时长。
+    selected_value_unknown_duration_ns: int  # TRUE但值/面积不可核实的时长。
+    false_duration_ns: int  # 已知FALSE时长，只有完整窗才证明空选择零。
+    valid_sample_count: int  # 半开当前块内原值真实更新且有效/TRUE的数量。
+    value_unknown_ranges: tuple[Interval, ...]  # 值及面积计算不可核实的正区间。
+    condition_unknown_ranges: tuple[Interval, ...]  # BOOL UNKNOWN正区间，与值未知独立。
+    quality: Q  # 输入、依赖和精度/面积故障原因完整OR。
+    input_unit: str  # 原输入工程单位，面积尚未转换输出单位。
+    binding_identity: str  # 实际联合输入中原值表达式身份。
+    source_refs: tuple[SourceRef, ...]  # 完整来源子类与原定位，不只保存字段名。
+    ranges_retained: bool = True  # 仅明确请求时保留未知范围；False不能用于完整明细归约。
+
+    def __post_init__(self):
+        """验证两完整分区、选中与FALSE恒等式，不修复矛盾事实。
+
+        参数: 无。返回: 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')
+        actual, request = self.actual_window, self.spec.window
+        span = 0 if actual is None else actual.end_ns - actual.start_ns
+        if actual is not None and not request.start_ns <= actual.start_ns <= actual.end_ns <= request.end_ns:
+            raise ValueError('条件积分实际范围越过原请求')
+        durations = (self.value_valid_duration_ns, self.condition_known_duration_ns, self.selected_duration_ns,
+                     self.selected_value_unknown_duration_ns, self.false_duration_ns)
+        # 所有时长与样本计数为原生整数，不能把bool或浮点秒作纳秒。
+        if any(type(value) is not int or not 0 <= value <= span for value in durations):
+            raise ValueError('条件积分覆盖时长需要实际跨度内的非负原生int')
+        if (type(self.valid_sample_count) is not int or not 0 <= self.valid_sample_count <= self.selected_duration_ns
+                or self.selected_duration_ns > self.value_valid_duration_ns
+                or self.selected_value_unknown_duration_ns > span - self.value_valid_duration_ns
+                or self.false_duration_ns > self.condition_known_duration_ns
+                or self.selected_duration_ns + self.selected_value_unknown_duration_ns !=
+                   self.condition_known_duration_ns - self.false_duration_ns):
+            raise ValueError('条件积分样本、选择、FALSE与已知时长矛盾')
+        # 分别核对值与条件的完整实际域，不将UNKNOWN当FALSE合并。
+        if type(self.ranges_retained) is not bool:
+            raise TypeError('范围保留标志需要bool')
+        if not self.ranges_retained and (self.value_unknown_ranges != () or self.condition_unknown_ranges != ()):
+            raise ValueError('未请求范围时不能附带范围明细')
+        if self.ranges_retained and _unknown_duration(self.value_unknown_ranges, actual) + self.value_valid_duration_ns != span:
+            raise ValueError('条件积分值有效与未知未完整划分实际窗口')
+        if self.ranges_retained and _unknown_duration(self.condition_unknown_ranges, actual) + self.condition_known_duration_ns != span:
+            raise ValueError('条件积分已知与条件未知未完整划分实际窗口')
+        if not isinstance(self.quality, Q) or type(self.source_refs) is not tuple or any(not isinstance(ref, SourceRef) for ref in self.source_refs):
+            raise TypeError('条件积分事实需要typed质量和完整来源tuple')
+        require_text(self.input_unit, 'conditional_integral.input_unit')
+        require_text(self.binding_identity, 'conditional_integral.binding_identity')
+
+
+@dataclass(frozen=True)
+class ReferenceConditionalIntegralTerms:
+    """保存有限原序面积，未知占位0只能与False掩码一起解释。"""
+
+    areas: tuple[float, ...]  # 形状N-1的原序有限float面积，未换最终单位。
+    valid: tuple[bool, ...]  # 只有TRUE选择且正常面积为True。
+    facts: ConditionalIntegralFacts  # 当前块覆盖与完整定位，不是整窗最终状态。
+
+    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, ConditionalIntegralFacts)):
+            raise TypeError('参考条件积分项需要同长tuple及ConditionalIntegralFacts')
+        if any(type(area) is not float or not isfinite(area) or type(keep) is not bool
+               or not keep and area != 0 for area, keep in zip(self.areas, self.valid)):
+            raise ValueError('条件积分面积需有限float/bool，无效位置只能存0')
+
+
+def require_conditional_integral_terms(series, spec, *, step_ns=None, valid_until_ns=None, condition_valid_until_ns=None):
+    """校验typed数值、BOOL条件、明确积分单位及可表示正跨度。
+
+    参数: series为有限CalculationSeries，spec为原integral请求。
+        step_ns为所选周期，两个until列为值/条件的实际有效截止，均可省略保原行为。
+    返回: None。异常: TypeError/ValueError/OverflowError为模型、能力、单位或时间错误。
+    """
+    # 仅共享结构门槛；两后端独立计算转换、面积、掩码、时长与样本。
+    if not isinstance(series, CalculationSeries) or not isinstance(spec, CalculationDefinition):
+        raise TypeError('条件积分需要CalculationSeries和CalculationDefinition')
+    from .record_intervals import require_record_step
+    from .integral_terms import require_valid_until
+    require_record_step(step_ns, series.actual_value_updates)
+    require_valid_until(series.times_ns, valid_until_ns)
+    require_valid_until(series.times_ns, condition_valid_until_ns)
+    if (spec.operation != 'integral' or series.conditions is None
+            or series.values[0].dtype not in (D.INT64, D.UINT64, D.FLOAT64)
+            or any(value.dtype is not D.BOOL for value in series.conditions)):
+        raise ValueError('条件积分只支持数值integral及显式BOOL选择条件')
+    calculation_unit(spec, series.unit)
+    left, right = max(spec.window.start_ns, series.observation.start_ns), min(spec.window.end_ns, series.observation.end_ns)
+    if right - left > 2 ** 63 - 1:
+        raise OverflowError('条件积分正交集跨度超过int64')

chronaxis/core/conditional_integral_terms_numpy.py

@@ -0,0 +1,148 @@
+"""用真实NumPy列运算生成有限条件积分面积与各自的覆盖事实。
+
+输入有限数值CalculationSeries、显式BOOL条件与原integral请求，输出只读一维float64
+面积、bool掩码及ConditionalIntegralFacts。先按整数ns裁剪，再按TRUE/有效掩码乘秒。
+数值转换、面积、故障和覆盖归约独立于标量参考；元数据循环只恢复诊断Interval。
+FALSE、UNKNOWN不做乘法，不把未知存储零视为正常结果，不提前归约或换单位。
+不修改输入、不读来源；N/N-1临时列及输出由调用方有限workspace预约并消费。
+"""
+
+# 只共享非数值模型门槛；计算采用独立NumPy转换与真实ufunc/掩码。
+from dataclasses import dataclass
+import numpy as np
+from .conditional_integral_terms import ConditionalIntegralFacts, require_conditional_integral_terms
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric_numpy import DTYPES, NumericArray, to_float_numpy
+from .types import QualityFlag as Q
+
+
+@dataclass(frozen=True)
+class NumpyConditionalIntegralTerms:
+    """保存原序只读面积与明确掩码，不借用可写输入或隐式掩码数组。"""
+
+    areas: np.ndarray  # float64形状(N-1,)，未转换的输入单位乘秒。
+    valid: np.ndarray  # bool形状(N-1,)，仅TRUE且正常面积可归约。
+    facts: ConditionalIntegralFacts  # 当前块双覆盖、样本与来源，不是全窗结果。
+
+    def __post_init__(self):
+        """检查普通一维同长只读列、有限面积及冻结事实。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为类型、形状、可写或占位错误。
+        """
+        # 拒绝自定义/隐藏掩码子类；纯输出不能依赖调用侧数组行为。
+        if (type(self.areas) is not np.ndarray or type(self.valid) is not np.ndarray
+                or self.areas.dtype != np.float64 or self.valid.dtype != bool
+                or self.areas.ndim != 1 or self.areas.shape != self.valid.shape
+                or not isinstance(self.facts, ConditionalIntegralFacts)):
+            raise TypeError('数组条件积分项需要同长一维float64/bool及ConditionalIntegralFacts')
+        if (self.areas.flags.writeable or self.valid.flags.writeable
+                or not np.all(np.isfinite(self.areas)) or np.any(~self.valid & (self.areas != 0))):
+            raise ValueError('数组条件积分项必须只读且有限，无效位置只能0存储')
+
+
+def compute_conditional_integral_terms_numpy(series, spec, *, step_ns=None, valid_until_ns=None,
+                                           condition_valid_until_ns=None, retain_unknown_ranges=True):
+    """按真实数组掩码生成面积，独立归约值、条件和选择覆盖。
+
+    参数: series为有限数值CalculationSeries及显式BOOL条件，spec为原integral请求。
+        step_ns选择固定/DBC周期；两个until列给实际有效截止；范围明细可显式关闭。
+    返回: NumpyConditionalIntegralTerms；只读面积/掩码形状N-1，临时列形状N或N-1。
+    异常: 输入、单位、时间和分配错误传播；浮点故障写质量并使对应值/面积失效。
+    """
+    # 时间不先转float，实际交集为整数域；所有有限输入先过公共结构门槛。
+    require_conditional_integral_terms(series, spec, step_ns=step_ns, valid_until_ns=valid_until_ns,
+                                      condition_valid_until_ns=condition_valid_until_ns)
+    if type(retain_unknown_ranges) is not bool:
+        raise TypeError('未知范围保留选项需要bool')
+    start = max(series.observation.start_ns, spec.window.start_ns)
+    end = min(series.observation.end_ns, spec.window.end_ns)
+    actual = Interval(start, end) if start <= end else None
+    # N个真实typed值经独立数组精度核；无效0仅是受valid约束的存储。
+    column = NumericArray(series.values[0].dtype,
+        np.array([value.value if value.valid else 0 for value in series.values], dtype=DTYPES[series.values[0].dtype]),
+        np.array([value.valid for value in series.values], dtype=bool),
+        np.array([int(value.quality) for value in series.values], dtype=np.uint16))
+    values = to_float_numpy(column)
+    # BOOL列按已知和真值两个(N,)掩码处理，UNKNOWN占位False不进入FALSE覆盖。
+    known = np.array([condition.valid for condition in series.conditions], dtype=bool)
+    truth = np.array([condition.value if condition.valid else False for condition in series.conditions], dtype=bool)
+    condition_quality = np.array([int(condition.quality) for condition in series.conditions], dtype=np.uint16)
+    times = np.array(series.times_ns, dtype=np.int64)
+    left, right = np.maximum(times[:-1], np.int64(start)), np.minimum(times[1:], np.int64(end))
+    observed = right > left
+    durations = np.zeros(len(left), dtype=np.int64)
+    np.subtract(right, left, out=durations, where=observed)
+    # 当前块副本可标记面积故障；只对TRUE有效正区间执行input_unit乘秒的ufunc。
+    valid_values, quality_values = values.valid.copy(), values.quality.copy()
+    value_right, condition_right = right, right
+    value_durations, condition_durations = durations, durations
+    # 两种有效性各有实际截止，不能用一个联合截止丢掉已知FALSE或值覆盖。
+    for deadlines, is_value in ((valid_until_ns, True), (condition_valid_until_ns, False)):
+        if deadlines is None:
+            continue
+        expiry = np.array([item if item is not None else (1 << 63) - 1 for item in deadlines], dtype=np.int64)
+        has_expiry = np.array([item is not None for item in deadlines], dtype=bool)
+        expired = has_expiry & (times >= expiry)
+        clipped = np.maximum(left, np.minimum(right, expiry[:-1]))
+        clipped_durations = np.zeros(len(left), dtype=np.int64)
+        np.subtract(clipped, left, out=clipped_durations, where=observed)
+        if is_value:
+            valid_values[expired] = False
+            quality_values[expired] |= int(Q.STALE)
+            quality_values[:-1][observed & (clipped < right)] |= int(Q.STALE)
+            value_right, value_durations = clipped, clipped_durations
+        else:
+            known[expired] = False
+            condition_quality[expired] |= int(Q.STALE)
+            condition_quality[:-1][observed & (clipped < right)] |= int(Q.STALE)
+            condition_right, condition_durations = clipped, clipped_durations
+    selected_durations = (durations if valid_until_ns is None and condition_valid_until_ns is None
+                          else np.minimum(value_durations, condition_durations))
+    keep = observed & (selected_durations > 0) & valid_values[:-1] & known[:-1] & truth[:-1]
+    areas = np.zeros(len(left), dtype=np.float64)
+    seconds = selected_durations.astype(np.float64)
+    if step_ns is None:
+        seconds /= 1_000_000_000
+    else:
+        # 分母保留完整实际记录对，不能改用条件/有效期裁剪后的长度。
+        seconds /= np.diff(times)
+        seconds *= step_ns / 1_000_000_000
+    with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+        np.multiply(values.values[:-1], seconds, out=areas, where=keep)
+    # 非有限及非零下溢只标实际执行的TRUE项，并使该位置真实样本失效。
+    nonfinite = keep & ~np.isfinite(areas)
+    underflow = keep & (areas == 0) & (values.values[:-1] != 0)
+    quality_values[:-1][nonfinite] |= int(Q.NONFINITE)
+    quality_values[:-1][underflow] |= int(Q.PRECISION_LOSS)
+    valid_values[:-1][nonfinite | underflow] = False
+    keep = observed & (selected_durations > 0) & valid_values[:-1] & known[:-1] & truth[:-1]
+    areas[~keep] = 0.0
+    # 五种覆盖分别按(N-1,)掩码归约正整数ns，总和不超过已验证int64实际跨度。
+    value_duration = int(np.sum(value_durations, where=observed & valid_values[:-1], dtype=np.int64))
+    known_duration = int(np.sum(condition_durations, where=observed & known[:-1], dtype=np.int64))
+    selected_duration = int(np.sum(selected_durations, where=keep, dtype=np.int64))
+    selected_unknown_duration = int(np.sum(condition_durations, where=observed & known[:-1] & truth[:-1], dtype=np.int64)) - selected_duration
+    false_duration = int(np.sum(condition_durations, where=observed & known[:-1] & ~truth[:-1], dtype=np.int64))
+    # 样本只计真实原值更新；条件变化与右终点不成为数值样本。
+    actual_updates = np.array(series.actual_value_updates, dtype=bool)
+    actual_samples = actual_updates & (times >= start) & (times < end)
+    sample_count = int(np.count_nonzero(actual_samples & valid_values & known & truth))
+    # 诊断来自实际正区间或真实样本，不将窗口外末点质量传播入结果。
+    diagnostic = np.array([int(flag) for flag in series.diagnostics], dtype=np.uint16) | quality_values | condition_quality
+    relevant = actual_samples.copy()
+    relevant[:-1] |= observed
+    quality = Q(int(np.bitwise_or.reduce(diagnostic, where=relevant, initial=0)))
+    # Python循环仅将有限未知掩码恢复精确Interval；数值和覆盖未调用参考核。
+    value_unknown = (tuple(Interval(int(value_right[index] if valid_values[index] else left[index]), int(right[index]))
+        for index in np.flatnonzero(observed & (~valid_values[:-1] | (value_right < right)))) if retain_unknown_ranges else ())
+    condition_unknown = (tuple(Interval(int(condition_right[index] if known[index] else left[index]), int(right[index]))
+        for index in np.flatnonzero(observed & (~known[:-1] | (condition_right < right)))) if retain_unknown_ranges else ())
+    facts = ConditionalIntegralFacts(spec, actual, value_duration, known_duration, selected_duration,
+        selected_unknown_duration, false_duration, sample_count, merge_ranges(value_unknown),
+        merge_ranges(condition_unknown), quality, series.unit, series.binding_identity, series.source_refs,
+        ranges_retained=retain_unknown_ranges)
+    # 返回只读列供独立原序float归约；输出未申请独立owner，不能脱离已预约workspace留存。
+    areas.setflags(write=False)
+    keep.setflags(write=False)
+    return NumpyConditionalIntegralTerms(areas, keep, facts)

chronaxis/core/conditional_integral_terms_reference.py

@@ -0,0 +1,111 @@
+"""独立标量生成有限条件积分面积，分别保存值覆盖与BOOL条件覆盖。
+
+输入为有限CalculationSeries和原integral请求，输出原序(N-1,)面积/掩码及冻结事实。
+每个值先通过标量浮点精度检查；只有TRUE且有效值才乘裁剪后的整数纳秒时长。
+面积溢出或非零下溢使该位置值和真实样本失效；FALSE、UNKNOWN不做面积乘法。
+不把UNKNOWN补零，不归约面积或转换最终单位，不读取来源、不修改输入。
+只依赖标准库及typed模型，不调用NumPy；有限临时列须由调用方owner预约。
+"""
+
+# 标量数值与覆盖判据独立于数组核，仅复用已校验模型和结构门槛。
+from math import isfinite
+from .conditional_integral_terms import ConditionalIntegralFacts, ReferenceConditionalIntegralTerms, require_conditional_integral_terms
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric import ScalarValue, to_float_reference
+from .types import QualityFlag as Q
+from .record_intervals import clipped_record_seconds
+
+
+def compute_conditional_integral_terms_reference(series, spec, *, step_ns=None, valid_until_ns=None,
+                                                condition_valid_until_ns=None, retain_unknown_ranges=True):
+    """逐正区间生成未转换原序面积与独立值、条件覆盖事实。
+
+    参数: series为有限数值CalculationSeries及显式BOOL条件，spec为原integral请求。
+        step_ns为可选所选周期；两个until列是实际有效截止；范围明细可显式关闭。
+    返回: ReferenceConditionalIntegralTerms；面积为输入单位乘秒，无效槽位0配False。
+    异常: 输入、单位、时间与分配错误传播；精度、面积溢出/下溢写入质量及未知。
+    """
+    # 结构先校验，裁剪保留精确整数ns；没有交集不凭空创建观察域。
+    require_conditional_integral_terms(series, spec, step_ns=step_ns, valid_until_ns=valid_until_ns,
+                                      condition_valid_until_ns=condition_valid_until_ns)
+    if type(retain_unknown_ranges) is not bool:
+        raise TypeError('未知范围保留选项需要bool')
+    start = max(series.observation.start_ns, spec.window.start_ns)
+    end = min(series.observation.end_ns, spec.window.end_ns)
+    actual = Interval(start, end) if start <= end else None
+    # 所有值都接受原完整积分的精度门槛，包括FALSE与UNKNOWN未选择的值。
+    values = [to_float_reference(value) for value in series.values]
+    conditions = series.conditions if condition_valid_until_ns is None else list(series.conditions)
+    # 到期点本身已失效；未到期的部分区间在下方独立裁剪。
+    for rows, deadlines in ((values, valid_until_ns), (conditions, condition_valid_until_ns)):
+        if deadlines is not None:
+            for index, deadline in enumerate(deadlines):
+                if deadline is not None and series.times_ns[index] >= deadline:
+                    old = rows[index]
+                    rows[index] = ScalarValue(None, old.dtype, False, old.quality | Q.STALE, old.labels)
+    areas, valid, value_unknown, condition_unknown = [], [], [], []
+    value_duration, known_duration, selected_duration = 0, 0, 0
+    selected_unknown_duration, false_duration, sample_count, quality = 0, 0, 0, Q.NONE
+    # 原N-1槽位顺序不变；数值未跨块归约，条件单独变化只改变选择覆盖。
+    for index in range(len(series.times_ns) - 1):
+        left, right = max(start, series.times_ns[index]), min(end, series.times_ns[index + 1])
+        area, keep = 0.0, False
+        if left < right:
+            value, condition = values[index], conditions[index]
+            quality |= series.diagnostics[index] | value.quality | condition.quality
+            value_end = right if valid_until_ns is None or valid_until_ns[index] is None else max(left, min(right, valid_until_ns[index]))
+            condition_end = right if condition_valid_until_ns is None or condition_valid_until_ns[index] is None else max(left, min(right, condition_valid_until_ns[index]))
+            selected_end = min(value_end, condition_end)
+            if value_end < right or condition_end < right:
+                quality |= Q.STALE
+            # 只有明确TRUE才计算面积；FALSE不因未执行的溢出丢掉值覆盖。
+            if value.valid and condition.valid and condition.value and selected_end > left:
+                seconds = ((selected_end - left) / 1_000_000_000 if step_ns is None else
+                    clipped_record_seconds(series.times_ns[index], series.times_ns[index + 1],
+                        spec.window if selected_end == right else Interval(left, selected_end), step_ns=step_ns))
+                term = value.value * seconds
+                failure = Q.NONFINITE if not isfinite(term) else Q.PRECISION_LOSS if term == 0 and value.value != 0 else Q.NONE
+                if failure == Q.NONE:
+                    area, keep = term, True
+                else:
+                    # 局部转换列同时更新样本有效性；原ScalarValue不被改写。
+                    value = ScalarValue(value.value, value.dtype, False, value.quality | failure, value.labels)
+                    values[index] = value
+                    quality |= failure
+            # 值和条件各自完整分区；TRUE值未知与条件UNKNOWN分别登记。
+            if value.valid:
+                value_duration += value_end - left
+                if retain_unknown_ranges and value_end < right:
+                    value_unknown.append(Interval(value_end, right))
+            elif retain_unknown_ranges:
+                value_unknown.append(Interval(left, right))
+            if condition.valid:
+                known_duration += condition_end - left
+                if not condition.value:
+                    false_duration += condition_end - left
+                elif value.valid:
+                    selected_duration += selected_end - left
+                    selected_unknown_duration += condition_end - selected_end
+                else:
+                    selected_unknown_duration += condition_end - left
+                if retain_unknown_ranges and condition_end < right:
+                    condition_unknown.append(Interval(condition_end, right))
+            elif retain_unknown_ranges:
+                condition_unknown.append(Interval(left, right))
+        # 未观察槽位也保留原位置，但不形成UNKNOWN或正常积分项。
+        areas.append(area)
+        valid.append(keep)
+    # 只计半开范围内原值真实更新且有效/TRUE；条件更新与末点不能计样本。
+    for index, time in enumerate(series.times_ns):
+        if start <= time < end and series.actual_value_updates[index]:
+            value, condition = values[index], conditions[index]
+            quality |= series.diagnostics[index] | value.quality | condition.quality
+            if value.valid and condition.valid and condition.value:
+                sample_count += 1
+    # 两未知元组仅合并相邻范围；完整来源子类和联合绑定身份原样保留。
+    facts = ConditionalIntegralFacts(spec, actual, value_duration, known_duration, selected_duration,
+        selected_unknown_duration, false_duration, sample_count, merge_ranges(value_unknown),
+        merge_ranges(condition_unknown), quality, series.unit, series.binding_identity, series.source_refs,
+        ranges_retained=retain_unknown_ranges)
+    return ReferenceConditionalIntegralTerms(tuple(areas), tuple(valid), facts)

chronaxis/core/conditional_time_reduction.py

@@ -0,0 +1,118 @@
+"""声明有限条件时间统计事实及结构门槛，不执行数值或时间归约。
+
+支持条件min_time/max_time/time_weighted_mean和主BOOL duration。值覆盖与外BOOL条件覆盖
+独立完整划分实际窗口；外FALSE不选择，外UNKNOWN不算FALSE。duration另保存外TRUE
+但主FALSE的有效零证据，选中时长只含主TRUE。mean的值覆盖包含转float精度门槛，
+权重数值故障不改输入覆盖。纯模型不读来源、不管理预算，不留存全窗输入；
+有限事实及返回元数据需要外层owner预先计费，最终分类也由外层负责。
+"""
+
+# 两数值核仅共享typed模型和静态配置/几何门槛，不共享数值计算。
+from dataclasses import dataclass
+from .calculations import CalculationDefinition, CalculationSeries
+from .models import Interval, SourceRef
+from .time_reduction import require_time_config
+from .types import QualityFlag as Q, SignalDType as D
+from .validation import require_text
+
+
+def _unknown_duration(ranges, actual):
+    """核对一种未知范围的顺序与几何，返回精确整数时长。
+
+    参数: ranges为冻结正Interval tuple，actual为原请求内实际交集或None。
+    返回: 原生int未知纳秒。异常: TypeError/ValueError为类型、重叠、反序或越界。
+    """
+    # 各未知分区独立检查，不靠总长度掩盖重复位置或跨越实际边界。
+    if type(ranges) is not tuple:
+        raise TypeError('条件时间未知范围需要tuple')
+    cursor, total = (actual.start_ns if actual is not None else 0), 0
+    for item in ranges:
+        if (not isinstance(item, Interval) or actual is None or item.start_ns < cursor
+                or item.start_ns >= item.end_ns or item.end_ns > actual.end_ns):
+            raise ValueError('条件时间未知范围必须有序、不重叠且在实际窗口内')
+        cursor, total = item.end_ns, total + item.end_ns - item.start_ns
+    return total
+
+
+@dataclass(frozen=True)
+class ConditionalTimeCalculationFacts:
+    """保存有限块双覆盖和选择交集，主FALSE只为duration保留有效零证据。
+
+    数值算子selected包含外TRUE有效值；duration的selected只含外TRUE主TRUE。
+    selected_false只含duration外TRUE主FALSE，其他算子为0；真实样本遵循相同选择。
+    两未知元组分别完整划分值与外条件，不用UNKNOWN填零或代替FALSE。
+    """
+
+    spec: CalculationDefinition  # 原时间统计请求与政策，不按块重写。
+    actual_window: Interval | None  # 当前块真实交集，不外推EOF。
+    value_valid_duration_ns: int  # 原值通过本算子门槛后的有效纳秒。
+    condition_known_duration_ns: int  # 外条件TRUE/FALSE已知纳秒。
+    selected_duration_ns: int  # 外TRUE有效数值，duration另须主TRUE。
+    selected_value_unknown_duration_ns: int  # 外TRUE但值未知，不混入外条件UNKNOWN。
+    false_duration_ns: int  # 外条件已知FALSE纳秒，只有完整窗才证明空选择。
+    selected_false_duration_ns: int  # duration外TRUE主FALSE有效零证据，其他算子0。
+    valid_sample_count: int  # 已选真实值更新，不是条件更新/保持区间数。
+    value_unknown_ranges: tuple[Interval, ...]  # 值未知位置，包含mean精度失败。
+    condition_unknown_ranges: tuple[Interval, ...]  # 外条件UNKNOWN位置。
+    quality: Q  # 输入、精度与依赖原因，不包含数值weight失败。
+    input_unit: str  # 原分析工程单位，尚未转换最终输出。
+    dtype: D  # 极值保留原定宽整数；duration为BOOL。
+    binding_identity: str  # 原值表达式联合输入身份。
+    source_refs: tuple[SourceRef, ...]  # 原定位和真实子类完整保留。
+    ranges_retained: bool = True  # False只留分类所需计数，不构造未知范围。
+
+    def __post_init__(self):
+        """验证正分区、选择交集和完整身份，不修补矛盾事实。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为配置、几何或交集矛盾。
+        """
+        # 配置门槛只验证typed算子、单位、dtype，不计算浮点数值。
+        require_time_config(self.spec, self.input_unit, self.dtype, None, 4096)
+        if self.actual_window is not None and not isinstance(self.actual_window, Interval):
+            raise TypeError('条件时间实际范围需要Interval或None')
+        actual, request = self.actual_window, self.spec.window
+        span = 0 if actual is None else actual.end_ns - actual.start_ns
+        if actual is not None and not request.start_ns <= actual.start_ns <= actual.end_ns <= request.end_ns:
+            raise ValueError('条件时间实际范围越过原请求')
+        durations = (self.value_valid_duration_ns, self.condition_known_duration_ns, self.selected_duration_ns,
+                     self.selected_value_unknown_duration_ns, self.false_duration_ns, self.selected_false_duration_ns)
+        # 计数与纳秒必须原生int；bool不能通过整数继承关系冒充时长。
+        if any(type(value) is not int or not 0 <= value <= span for value in durations):
+            raise ValueError('条件时间覆盖需要实际跨度内原生非负int')
+        if (type(self.valid_sample_count) is not int or not 0 <= self.valid_sample_count <= self.selected_duration_ns
+                or self.selected_duration_ns + self.selected_false_duration_ns > self.value_valid_duration_ns
+                or self.selected_value_unknown_duration_ns > span - self.value_valid_duration_ns
+                or self.false_duration_ns > self.condition_known_duration_ns
+                or self.selected_duration_ns + self.selected_false_duration_ns + self.selected_value_unknown_duration_ns
+                   != self.condition_known_duration_ns - self.false_duration_ns
+                or self.spec.operation != 'duration' and self.selected_false_duration_ns != 0):
+            raise ValueError('条件时间样本、选择、有效FALSE及已知交集矛盾')
+        # 值和外条件分别完整划分实际域；不能用另一种未知补缺口。
+        if type(self.ranges_retained) is not bool or not self.ranges_retained and (self.value_unknown_ranges or self.condition_unknown_ranges):
+            raise ValueError('精简条件时间事实不能携带未知范围')
+        value_unknown = _unknown_duration(self.value_unknown_ranges, actual)
+        condition_unknown = _unknown_duration(self.condition_unknown_ranges, actual)
+        if self.ranges_retained and value_unknown + self.value_valid_duration_ns != span:
+            raise ValueError('条件时间值有效与未知未完整划分实际窗口')
+        if self.ranges_retained and condition_unknown + self.condition_known_duration_ns != span:
+            raise ValueError('条件时间已知与外条件未知未完整划分实际窗口')
+        if not isinstance(self.quality, Q) or type(self.source_refs) is not tuple or any(not isinstance(ref, SourceRef) for ref in self.source_refs):
+            raise TypeError('条件时间需要typed质量和完整来源tuple')
+        require_text(self.binding_identity, 'conditional_time.binding_identity')
+
+
+def require_conditional_time_series(series, spec, input_unit, dtype):
+    """核对有限联合输入的条件、单位、类型与正交集几何。
+
+    参数: series为有限CalculationSeries，其余为归约的原配置。
+    返回: 当前实际交集Interval或None。异常: TypeError/ValueError/OverflowError。
+    """
+    # BOOL条件已由CalculationSeries验证；缺条件不能被默认为全TRUE或全FALSE。
+    if not isinstance(series, CalculationSeries):
+        raise TypeError('条件时间归约需要CalculationSeries')
+    if series.conditions is None or series.unit != input_unit or series.values[0].dtype is not dtype:
+        raise ValueError('条件时间归约需要同单位同dtype及显式BOOL条件')
+    left, right = max(spec.window.start_ns, series.observation.start_ns), min(spec.window.end_ns, series.observation.end_ns)
+    if right - left > 2**63 - 1:
+        raise OverflowError('条件时间正交集跨度超过int64')
+    return Interval(left, right) if left <= right else None