chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/conditional_time_reduction_numpy.py

@@ -0,0 +1,223 @@
+"""用真实NumPy掩码归约有限条件时间极值、规范化均值和主BOOL时长。
+
+typed值及外BOOL为(N,)列，正区间为(N-1,)精确int64差与独立bool掩码。极值在原
+dtype上归约；duration同时保留外TRUE主FALSE零证据；mean首遍仅确认值精度和
+TRUE有效选择，次遍计算x*(dt/D)，由本数组原序误差核推进。数值weight故障不改
+双覆盖，最终单位只finish转换一次。装箱、恢复未知和固定标量状态驱动不冒充
+数组数值核；不调用参考算法、不读来源、不存全轴，有限内存由外层owner预约。
+"""
+
+# 原序推进复用独立数组误差状态，只共享结构/typed协议，不调用标量后端。
+import numpy as np
+from .conditional_time_reduction import ConditionalTimeCalculationFacts, require_conditional_time_series
+from .integral_sum_numpy import NumpyIntegralSum
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric_numpy import DTYPES, NumericArray, to_float_numpy
+from .time_reduction import TimeReductionResult, require_time_config, require_time_options
+from .integral_terms import require_valid_until
+from .types import QualityFlag as Q
+
+from .time_reduction import MeanTimeBlock
+from .mean_weights_numpy import normalized_mean_terms
+
+
+class NumpyConditionalTimeReduction:
+    """保存单原dtype候选、整数时长与有界误差列，不存跨块输入数组。"""
+
+    def __init__(self, spec, input_unit, dtype, *, selected_duration_ns=None, partial_limit=4096,
+                 step_ns=None, selected_weight_seconds=None):
+        """校验原配置并建立本数组后端固定状态。
+
+        参数: spec/input_unit/dtype为原配置；selected_duration_ns为mean次遍全TRUE有效分母；
+            partial_limit为误差容量；step_ns选周期，周期均值次遍传selected_weight_seconds。返回: None。异常: 配置、数组分配错误传播。
+        """
+        # 静态门槛只检查明确配置，两个后端不共享后续数值或覆盖计算。
+        self._unit, self._factor = require_time_config(spec, input_unit, dtype, selected_duration_ns, partial_limit,
+            step_ns=step_ns, selected_weight_seconds=selected_weight_seconds)
+        self._spec, self._input_unit, self._dtype = spec, input_unit, dtype
+        self._step_ns = step_ns
+        self._denominator = selected_duration_ns if step_ns is None else selected_weight_seconds
+        # mean首遍不建立误差列，固定候选/计数不随块数增长。
+        self._identity = self._candidate = None
+        self._value_duration = self._selected_duration = self._terms = 0
+        self._numeric_quality = Q.NONE
+        self._sum = NumpyIntegralSum(partial_limit) if spec.operation == 'time_weighted_mean' and self._denominator is not None else None
+        self._weight_sum = NumpyIntegralSum(partial_limit) if step_ns is not None and spec.operation in ('duration', 'time_weighted_mean') else None
+
+    @property
+    def selected_weight_seconds(self):
+        """读取必要周期权重。参数: 无。返回: float或不适用None。异常: 权重求和故障。"""
+        if self._weight_sum is None:
+            return None
+        result = self._weight_sum.finish('s')
+        if result.calculation_failed:
+            raise OverflowError('条件周期权重累计失败')
+        return 0.0 if result.value is None else result.value
+
+    @property
+    def selected_duration_ns(self):
+        """读取累计已选时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._selected_duration  # duration仅主TRUE；mean为规范化分母事实。
+
+    @property
+    def value_valid_duration_ns(self):
+        """读取累计值有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._value_duration  # 独立于外条件FALSE/UNKNOWN。
+
+    def push(self, series, *, valid_until_ns=None, condition_valid_until_ns=None, retain_unknown_ranges=True, retain_mean_terms=False):
+        """计算有限块双覆盖并按原序推进本后端数值候选。
+
+        参数: series为同dtype/原单位且显式BOOL条件的有限CalculationSeries。
+        valid_until_ns/condition_valid_until_ns分别截断实际有效期；
+            retain_unknown_ranges=False省去两类未知范围。
+        retain_mean_terms仅均值首遍返回MeanTimeBlock，其他调用返回事实。
+        返回: ConditionalTimeCalculationFacts；权重故障仅改变数值失败状态，不改输入覆盖。
+        异常: 结构、身份、容量、分配或取消错误传播，外层异常后只能清理owner。
+        内存: 所有新输入/掩码列形状N或N-1，仅当前push存活，不修改调用者输入。
+        """
+        # 当前输入先核对显式条件/单位/dtype和交集，跨块原值绑定不能变化。
+        actual = require_conditional_time_series(series, self._spec, self._input_unit, self._dtype)
+        require_time_options(series, self._step_ns, valid_until_ns, retain_unknown_ranges)
+        require_valid_until(series.times_ns, condition_valid_until_ns)
+        if type(retain_mean_terms) is not bool or retain_mean_terms and (self._spec.operation != 'time_weighted_mean' or self._denominator is not None):
+            raise ValueError('仅均值首遍可请求必要回读项')
+        if self._identity is not None and self._identity != series.binding_identity:
+            raise ValueError('条件时间归约不能跨绑定身份累计')
+        self._identity = series.binding_identity
+        # typed装箱仅恢复协议，值精度转换只对mean执行，极值保持int64/uint64原数组。
+        column = NumericArray(self._dtype,
+            np.array([value.value if value.valid else 0 for value in series.values], dtype=DTYPES[self._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) if self._spec.operation == 'time_weighted_mean' else column
+        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)
+        start, end = (actual.start_ns, actual.end_ns) if actual is not None else (0, 0)
+        # 整数端点先裁剪，只对正区间做差，域外反序不发生int64减法wrap。
+        left, right = np.maximum(times[:-1], np.int64(start)), np.minimum(times[1:], np.int64(end))
+        observed = right > left
+        deadlines = np.array([2**63-1 if item is None else item for item in valid_until_ns], dtype=np.int64) if valid_until_ns is not None else None
+        condition_deadlines = np.array([2**63-1 if item is None else item for item in condition_valid_until_ns], dtype=np.int64) if condition_valid_until_ns is not None else None
+        value_end = right.copy() if deadlines is None else np.minimum(right, deadlines[:-1])
+        condition_end = right.copy() if condition_deadlines is None else np.minimum(right, condition_deadlines[:-1])
+        value_end = np.maximum(left, np.where(values.valid[:-1], value_end, left))
+        condition_end = np.maximum(left, np.where(known[:-1], condition_end, left))
+        # 三种交集独立做安全整数差，原始记录对仍留作周期权重分母。
+        value_dt = np.zeros(len(left), dtype=np.int64)
+        condition_dt = np.zeros(len(left), dtype=np.int64)
+        durations = np.zeros(len(left), dtype=np.int64)
+        np.subtract(value_end, left, out=value_dt, where=observed)
+        np.subtract(condition_end, left, out=condition_dt, where=observed)
+        np.subtract(np.minimum(value_end, condition_end), left, out=durations, where=observed)
+        usable = observed & (durations > 0) & truth[:-1]
+        selected = usable & values.values[:-1] if self._spec.operation == 'duration' else usable
+        selected_false_mask = usable & ~values.values[:-1] if self._spec.operation == 'duration' else np.zeros(len(left), dtype=bool)
+        # 所有非负dt归约不超过已检查int64实际跨度，跨块由Python整数累加。
+        value_duration = int(np.sum(value_dt, dtype=np.int64))
+        known_duration = int(np.sum(condition_dt, dtype=np.int64))
+        selected_duration = int(np.sum(durations, where=selected, dtype=np.int64))
+        selected_unknown = int(np.sum(condition_dt - durations, where=truth[:-1], dtype=np.int64))
+        false_duration = int(np.sum(condition_dt, where=~truth[:-1], dtype=np.int64))
+        selected_false = int(np.sum(durations, where=selected_false_mask, dtype=np.int64))
+        terms = int(np.count_nonzero(usable))
+        seconds = None
+        if self._weight_sum is not None:
+            seconds = durations[selected].astype(np.float64)
+            seconds /= np.diff(times)[selected]
+            seconds *= self._step_ns / 1_000_000_000
+            keep_weights = np.ones(len(seconds), dtype=bool)
+            seconds.setflags(write=False)
+            keep_weights.setflags(write=False)
+            self._weight_sum.push_values(seconds, keep_weights)
+        # 半开原值真实更新且外TRUE才成为样本；duration另要求主TRUE，条件更新不计。
+        actual_samples = (times >= start) & (times < end) & np.array(series.actual_value_updates, dtype=bool)
+        samples = actual_samples & values.valid & known & truth
+        if deadlines is not None:
+            samples &= times < deadlines
+        if condition_deadlines is not None:
+            samples &= times < condition_deadlines
+        if self._spec.operation == 'duration':
+            samples &= values.values
+        relevant = actual_samples.copy()
+        relevant[:-1] |= observed
+        diagnostics = np.array([int(flag) for flag in series.diagnostics], dtype=np.uint16) | values.quality | condition_quality
+        quality = Q(int(np.bitwise_or.reduce(diagnostics, where=relevant, initial=0)))
+        # 元数据循环只恢复两种未知Interval，覆盖和数值运算均已由真实数组完成。
+        if np.any(observed & ((values.valid[:-1] & (value_end < right)) | (known[:-1] & (condition_end < right)))):
+            quality |= Q.STALE
+        value_unknown = (tuple(Interval(int(value_end[index]), int(right[index])) for index in np.flatnonzero(observed & (value_end < right)))
+                         if retain_unknown_ranges else ())
+        condition_unknown = (tuple(Interval(int(condition_end[index]), int(right[index])) for index in np.flatnonzero(observed & (condition_end < right)))
+                             if retain_unknown_ranges else ())
+        if self._spec.operation in ('min_time', 'max_time') and terms:
+            # 当前块原dtype极值，跨块仅比较一个同dtype候选，避免uint64精度舍入。
+            candidate = (np.min if self._spec.operation == 'min_time' else np.max)(values.values[:-1][usable])
+            if self._candidate is not None:
+                previous = DTYPES[self._dtype].type(self._candidate)
+                candidate = (np.minimum if self._spec.operation == 'min_time' else np.maximum)(previous, candidate)
+            self._candidate = candidate.item()
+        elif self._spec.operation == 'time_weighted_mean' and self._denominator is not None:
+            chosen = values.values[:-1][usable]
+            measures = durations[usable].astype(np.float64) if self._step_ns is None else seconds
+            weighted, weight_quality = normalized_mean_terms(chosen, measures, self._denominator)
+            self._numeric_quality |= weight_quality
+            if self._numeric_quality == Q.NONE:
+                keep = np.ones(len(weighted), dtype=bool)
+                keep.setflags(write=False)
+                self._sum.push_values(weighted, keep)
+        self._value_duration += value_duration
+        self._selected_duration += selected_duration
+        self._terms += terms
+        facts = ConditionalTimeCalculationFacts(self._spec, actual, value_duration, known_duration, selected_duration,
+            selected_unknown, false_duration, selected_false, int(np.count_nonzero(samples)), merge_ranges(value_unknown),
+            merge_ranges(condition_unknown), quality, self._input_unit, self._dtype, series.binding_identity, series.source_refs, retain_unknown_ranges)
+        if retain_mean_terms:
+            selected_values = values.values[:-1][usable]
+            selected_weights = durations[usable].copy() if self._step_ns is None else seconds
+            selected_values.setflags(write=False)
+            selected_weights.setflags(write=False)
+            return MeanTimeBlock(facts, selected_values, selected_weights)
+        return facts
+
+    def finish(self):
+        """生成原序统计快照并做一次最终换单位，双覆盖由外层分类。
+
+        参数: 无。返回: 既有TimeReductionResult。异常: mean首遍RuntimeError、次遍分母不符ValueError；
+            配置/分配/取消传播，数值溢出和非零下溢返回计算失败。
+        """
+        # mean首遍禁交付数值；次遍需要实际TRUE有效累计时长与全窗D相等。
+        if self._spec.operation == 'time_weighted_mean':
+            if self._denominator is None:
+                raise RuntimeError('条件时间均值首遍只收事实，不能生成数值')
+            measured = self._selected_duration if self._step_ns is None else self.selected_weight_seconds
+            if measured != self._denominator:
+                raise ValueError('条件均值次遍选择时长与全窗分母不同')
+            if self._numeric_quality != Q.NONE:
+                return TimeReductionResult(None, self._unit, True, self._numeric_quality, self._terms)
+            number = self._sum.finish(self._unit, self._factor)
+            return TimeReductionResult(number.value, number.unit, number.calculation_failed, number.quality, self._terms)
+        # 没有正区间数值证据不补0；全外FALSE空0由外层完整请求分类证明。
+        if self._terms == 0:
+            return TimeReductionResult(None, self._unit, False, Q.NONE, 0)
+        # 主FALSE为有效duration项而时长0；极值未换单位时保持原生精确整数。
+        value = ((float(np.divide(np.float64(self._selected_duration), np.float64(1_000_000_000)))
+                  if self._step_ns is None else self.selected_weight_seconds)
+                 if self._spec.operation == 'duration' else self._candidate)
+        quality = Q.NONE
+        if self._factor != 1 and type(value) is int:
+            converted = to_float_numpy(NumericArray(self._dtype,
+                np.array([value], dtype=DTYPES[self._dtype]), np.array([True]), np.array([0], dtype=np.uint16)))
+            if not converted.valid[0]:
+                quality |= Q(int(converted.quality[0]))
+            else:
+                value = converted.values[0].item()
+        if quality == Q.NONE and self._factor != 1:
+            original = value
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                value = np.multiply(np.float64(value), np.float64(self._factor)).item()
+            if not np.isfinite(value) or value == 0 and original != 0:
+                quality |= Q.NONFINITE if not np.isfinite(value) else Q.PRECISION_LOSS
+        return TimeReductionResult(None if quality != Q.NONE else value, self._unit, quality != Q.NONE, quality, self._terms)

chronaxis/core/conditional_time_reduction_reference.py

@@ -0,0 +1,213 @@
+"""独立标量归约有限条件极值、规范化时间均值和主BOOL持续时间。
+
+push保留值与外条件各自的覆盖、真实更新、未知及完整来源；跨块仅保存候选与时长。
+min/max保留原整数，duration累计外TRUE主TRUE的精确ns并保留主FALSE零证据。
+mean首遍只查有效/选择事实，次遍以全窗TRUE有效时长D计算x*(dt/D)，不先算面积。
+权重及原序求和故障与输入覆盖分开；单位仅finish转换一次。纯核不读来源、不预约
+预算或保存全轴，有限临时列及误差项须由外层owner计费，推进异常后须放弃状态。
+"""
+
+# 仅使用标量及同后端原序误差核，不调用数组面积、对齐或归约。
+from math import isfinite
+from .conditional_time_reduction import ConditionalTimeCalculationFacts, require_conditional_time_series
+from .integral_sum_reference import ReferenceIntegralSum
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric import ScalarValue, to_float_reference
+from .time_reduction import TimeReductionResult, require_time_config, require_time_options
+from .integral_terms import require_valid_until
+from .record_intervals import clipped_record_seconds
+from .types import QualityFlag as Q
+
+from .time_reduction import MeanTimeBlock
+from .mean_weights_reference import normalized_mean_terms
+
+
+class ReferenceConditionalTimeReduction:
+    """保存一个原dtype候选、精确时长与有界误差项，mean两遍实例不能混用。"""
+
+    def __init__(self, spec, input_unit, dtype, *, selected_duration_ns=None, partial_limit=4096,
+                 step_ns=None, selected_weight_seconds=None):
+        """验证原配置并建立本后端有限状态。
+
+        参数: spec/input_unit/dtype为原配置；selected_duration_ns为mean次遍全TRUE有效分母；
+            partial_limit为误差项容量；step_ns选周期，周期均值次遍传selected_weight_seconds。返回: None。异常: 配置或分配错误传播。
+        """
+        # 共享的静态门槛先核对算子、类型、单位及mean分母，不执行数值计算。
+        self._unit, self._factor = require_time_config(spec, input_unit, dtype, selected_duration_ns, partial_limit,
+            step_ns=step_ns, selected_weight_seconds=selected_weight_seconds)
+        self._spec, self._input_unit, self._dtype = spec, input_unit, dtype
+        self._step_ns = step_ns
+        self._denominator = selected_duration_ns if step_ns is None else selected_weight_seconds
+        # 固定状态不随块数增加；mean首遍不建立数值误差状态。
+        self._identity = self._candidate = None
+        self._value_duration = self._selected_duration = self._terms = 0
+        self._numeric_quality = Q.NONE
+        self._sum = ReferenceIntegralSum(partial_limit) if spec.operation == 'time_weighted_mean' and self._denominator is not None else None
+        self._weight_sum = ReferenceIntegralSum(partial_limit) if step_ns is not None and spec.operation in ('duration', 'time_weighted_mean') else None
+
+    @property
+    def selected_weight_seconds(self):
+        """读取必要周期权重。参数: 无。返回: float或不适用None。异常: 权重求和故障。"""
+        if self._weight_sum is None:
+            return None
+        result = self._weight_sum.finish('s')
+        if result.calculation_failed:
+            raise OverflowError('条件周期权重累计失败')
+        return 0.0 if result.value is None else result.value
+
+    @property
+    def selected_duration_ns(self):
+        """读取累计选择时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._selected_duration  # duration仅主TRUE；mean为全TRUE有效分母事实。
+
+    @property
+    def value_valid_duration_ns(self):
+        """读取累计值有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._value_duration  # 外FALSE/UNKNOWN不改变原值可用性。
+
+    def push(self, series, *, valid_until_ns=None, condition_valid_until_ns=None, retain_unknown_ranges=True, retain_mean_terms=False):
+        """独立消费有限联合块，返回完整双覆盖并推进原单位候选。
+
+        参数: series为同单位/dtype且有显式BOOL条件的有限CalculationSeries。
+        valid_until_ns/condition_valid_until_ns分别截断实际有效期；
+            retain_unknown_ranges=False省去两类未知范围。
+        retain_mean_terms仅均值首遍返回MeanTimeBlock，其他调用返回事实。
+        返回: ConditionalTimeCalculationFacts；mean权重故障只记数值质量，不改覆盖。
+        异常: 结构、身份、容量或分配错误传播；外层不得继续使用异常前缀状态。
+        """
+        # 输入先过明确条件/单位/dtype与交集门槛，跨块不能更换原值绑定身份。
+        actual = require_conditional_time_series(series, self._spec, self._input_unit, self._dtype)
+        require_time_options(series, self._step_ns, valid_until_ns, retain_unknown_ranges)
+        require_valid_until(series.times_ns, condition_valid_until_ns)
+        if type(retain_mean_terms) is not bool or retain_mean_terms and (self._spec.operation != 'time_weighted_mean' or self._denominator is not None):
+            raise ValueError('仅均值首遍可请求必要回读项')
+        if self._identity is not None and self._identity != series.binding_identity:
+            raise ValueError('条件时间归约不能跨绑定身份累计')
+        self._identity = series.binding_identity
+        # 只有mean检查to_float精度；极值和主BOOL不被提升成浮点类型。
+        values = tuple(to_float_reference(value) for value in series.values) if self._spec.operation == 'time_weighted_mean' else series.values
+        start, end = (actual.start_ns, actual.end_ns) if actual is not None else (0, 0)
+        value_duration = known_duration = selected_duration = selected_unknown = false_duration = selected_false = samples = terms = 0
+        value_unknown, condition_unknown, weighted = [], [], []
+        period_weights = [] if self._weight_sum is not None else None
+        mean_values = [] if self._spec.operation == 'time_weighted_mean' and (self._denominator is not None or retain_mean_terms) else None
+        mean_weights = [] if mean_values is not None else None
+        quality, weight_quality = Q.NONE, Q.NONE
+        # 每个正区间先核对双覆盖，再决定TRUE有效数值是否推进，末点没有区间。
+        for index in range(len(series.times_ns) - 1):
+            left, right = max(series.times_ns[index], start), min(series.times_ns[index+1], end)
+            if left >= right:
+                continue
+            value, condition = values[index], series.conditions[index]
+            quality |= series.diagnostics[index] | value.quality | condition.quality
+            deadline = None if valid_until_ns is None else valid_until_ns[index]
+            condition_deadline = None if condition_valid_until_ns is None else condition_valid_until_ns[index]
+            value_end = max(left, min(right, deadline)) if deadline is not None else right
+            condition_end = max(left, min(right, condition_deadline)) if condition_deadline is not None else right
+            value_end = value_end if value.valid else left
+            condition_end = condition_end if condition.valid else left
+            value_duration += value_end - left
+            known_duration += condition_end - left
+            if value_end < right:
+                if retain_unknown_ranges:
+                    value_unknown.append(Interval(value_end, right))
+                if value.valid:
+                    quality |= Q.STALE
+            if condition_end < right:
+                if retain_unknown_ranges:
+                    condition_unknown.append(Interval(condition_end, right))
+                if condition.valid:
+                    quality |= Q.STALE
+            if condition_end <= left:
+                continue
+            if not condition.value:
+                false_duration += condition_end - left
+                continue
+            chosen_end = min(value_end, condition_end)
+            selected_unknown += condition_end - chosen_end
+            if chosen_end <= left:
+                continue
+            dt = chosen_end - left
+            # 外TRUE主FALSE仍是duration正常0证据，但不增加已选时长与真实样本。
+            terms += 1
+            if self._spec.operation == 'duration' and not value.value:
+                selected_false += dt
+            else:
+                selected_duration += dt
+            measure = dt
+            if period_weights is not None and (self._spec.operation != 'duration' or value.value):
+                measure = clipped_record_seconds(series.times_ns[index], series.times_ns[index+1],
+                    Interval(left, chosen_end), step_ns=self._step_ns)
+                period_weights.append(measure)
+            if self._spec.operation in ('min_time', 'max_time'):
+                # 每次只比较一个原dtype候选，跨块不转float，保留大整数的精确极值。
+                self._candidate = value.value if self._candidate is None else (min if self._spec.operation == 'min_time' else max)(self._candidate, value.value)
+            elif mean_values is not None:
+                mean_values.append(value.value)
+                mean_weights.append(measure)
+        # 原值真实更新才计样本，外条件TRUE且duration另须主TRUE；右端与条件更新不计。
+        for index, time in enumerate(series.times_ns):
+            if not start <= time < end or not series.actual_value_updates[index]:
+                continue
+            value, condition = values[index], series.conditions[index]
+            quality |= series.diagnostics[index] | value.quality | condition.quality
+            deadline = None if valid_until_ns is None else valid_until_ns[index]
+            condition_deadline = None if condition_valid_until_ns is None else condition_valid_until_ns[index]
+            if (value.valid and condition.valid and condition.value
+                    and (deadline is None or time < deadline) and (condition_deadline is None or time < condition_deadline)
+                    and (self._spec.operation != 'duration' or value.value)):
+                samples += 1
+        # 任意权重故障使整次数值失败，不清除前述可核实覆盖；正常权重按原序推进。
+        if self._denominator is not None:
+            weighted, weight_quality = normalized_mean_terms(mean_values, mean_weights, self._denominator)
+        self._numeric_quality |= weight_quality
+        if period_weights is not None:
+            self._weight_sum.push_values(tuple(period_weights), (True,)*len(period_weights))
+        if self._sum is not None and self._numeric_quality == Q.NONE:
+            self._sum.push_values(tuple(weighted), (True,)*len(weighted))
+        self._value_duration += value_duration
+        self._selected_duration += selected_duration
+        self._terms += terms
+        facts = ConditionalTimeCalculationFacts(self._spec, actual, value_duration, known_duration, selected_duration,
+            selected_unknown, false_duration, selected_false, samples, merge_ranges(value_unknown),
+            merge_ranges(condition_unknown), quality, self._input_unit, self._dtype, series.binding_identity, series.source_refs, retain_unknown_ranges)
+        return MeanTimeBlock(facts, tuple(mean_values), tuple(mean_weights)) if retain_mean_terms else facts
+
+    def finish(self):
+        """生成数值快照并只转换一次，覆盖与全外FALSE分类由外层处理。
+
+        参数: 无。返回: 既有TimeReductionResult。异常: mean首遍RuntimeError、次遍分母不符ValueError；
+            配置/分配错误传播，数值故障保留None和质量。
+        """
+        # mean首遍没有候选；次遍只有累计选择时长与原确认分母一致才能交付。
+        if self._spec.operation == 'time_weighted_mean':
+            if self._denominator is None:
+                raise RuntimeError('条件时间均值首遍只收事实，不能生成数值')
+            measured = self._selected_duration if self._step_ns is None else self.selected_weight_seconds
+            if measured != self._denominator:
+                raise ValueError('条件均值次遍选择时长与全窗分母不同')
+            if self._numeric_quality != Q.NONE:
+                return TimeReductionResult(None, self._unit, True, self._numeric_quality, self._terms)
+            # 同后端原序核负责一次最终单位转换，不在映射结果时再次乘因子。
+            number = self._sum.finish(self._unit, self._factor)
+            return TimeReductionResult(number.value, number.unit, number.calculation_failed, number.quality, self._terms)
+        # 外FALSE/UNKNOWN或值全未知没有有效项，空证据分类由外层负责。
+        if self._terms == 0:
+            return TimeReductionResult(None, self._unit, False, Q.NONE, 0)
+        value = ((self._selected_duration / 1_000_000_000 if self._step_ns is None else self.selected_weight_seconds)
+                 if self._spec.operation == 'duration' else self._candidate)
+        quality = Q.NONE
+        # 极值factor=1保留精确整数；显式换单位先检查整数浮点可表示性。
+        if self._factor != 1 and type(value) is int:
+            converted = to_float_reference(ScalarValue(value, self._dtype))
+            if not converted.valid:
+                quality |= converted.quality
+            else:
+                value = converted.value
+        if quality == Q.NONE:
+            original = value
+            value = value * self._factor if self._factor != 1 else value
+            if type(value) is float and (not isfinite(value) or value == 0 and original != 0):
+                quality |= Q.NONFINITE if not isfinite(value) else Q.PRECISION_LOSS
+        return TimeReductionResult(None if quality != Q.NONE else value, self._unit, quality != Q.NONE, quality, self._terms)

chronaxis/core/declarations.py

@@ -0,0 +1,192 @@
+"""在读取数据之前检查来源、信号和派生名称声明，生成不可变的声明绑定。
+
+输入为来源定位、时基、请求范围、信号定义和同步证据；输出DeclarationBindings
+及其SHA-256身份。函数只检查配置关系，不证明文件、DBC字段或实际观测存在，
+也不创建虚拟样本。静态表达式检查可使用这些声明；实际解释器仍需包含内存数据
+的SignalBindings。本模块只依赖标准库和核心模型，没有文件操作、样本计算、
+全局注册或执行计划缓存。
+"""
+
+# 冻结声明并为规范身份计算稳定摘要。
+from dataclasses import dataclass, field
+from hashlib import sha256
+# 复用已验契约与同步证据，不放宽实际绑定校验。
+from .binding import SignalDefinition, SynchronizationEvidence, _identity
+# 时基和范围已经独立验证，不借空SessionSpec制造实际来源。
+from .models import Interval, TimebaseSpec
+from .types import TimeType
+from .validation import require_identifier, require_text
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class DeclaredSource:
+    """保存一个尚未读取的来源定位，以及其声明的固定时间映射。
+
+    input_identity包含规范配置中的路径顺序、格式和处理配置标识，不是文件内容
+    哈希。offset_ns是整数纳秒偏移；模型不会估计漂移。字段实际存在性由来源执行
+    接口另行检查，不能凭声明认定数据已读取。全部字段不可变。
+    """
+
+    name: str  # 当前计划来源名。
+    timebase: TimebaseSpec  # 原始来源坐标。
+    input_identity: str  # 规范声明身份，与实际数据身份分别保存。
+    offset_ns: int = 0  # 显式固定偏移，不自动估计漂移。
+
+    def __post_init__(self) -> None:
+        """校验声明结构，保持声明身份与实际内容证据保持分开。
+
+        参数: 无；读取name/timebase/input_identity/offset_ns。
+        返回: None，冻结声明。
+        异常: TypeError/ValueError/TimeOverflowError为配置错误。
+        """
+        # 所有名称遵守统一安全规则。
+        require_identifier(self.name, 'source.name')
+        # 规范身份必须明确提供，不凭文件名猜测。
+        require_text(self.input_identity, 'source.input_identity')
+        # offset必须保持定宽整数。
+        require_int64_ns(self.offset_ns)
+        # 时基不得使用未校验字典。
+        if not isinstance(self.timebase, TimebaseSpec):
+            # 静态接口也不接无类型占位。
+            raise TypeError('声明来源需要TimebaseSpec')
+
+
+@dataclass(frozen=True)
+class DeclarationBindings:
+    """冻结一个计划的来源、信号名称和同步关系，供执行前检查使用。
+
+    signals与derived_names共用名称空间。identity只证明配置声明；来源路径、
+    处理配置、转换或有效期变化会改变它。模型不验证文件内容、实际列或DBC
+    元数据，不能代替执行数据绑定。同步检查只针对当前节点实际使用的来源。
+    """
+
+    session_id: str  # 当前会话声明。
+    timebase: TimebaseSpec  # 计划分析坐标。
+    domain: Interval | None  # 用户请求范围；None声明整文件无时间筛选，不表示无观测。
+    sources: tuple[DeclaredSource, ...]  # 保留声明原顺序。
+    signals: tuple[SignalDefinition, ...]  # 已校验单信号契约。
+    derived_names: tuple[str, ...] = ()  # signals统一名称空间。
+    synchronization: tuple[SynchronizationEvidence, ...] = ()  # 显式核实依据。
+    identity: str = field(init=False)  # 配置身份，不是执行绑定SHA。
+
+    def __post_init__(self) -> None:
+        """检查名称、来源和显式同步关系，并生成声明身份。
+
+        参数: 无；输入均为已经校验的不可变声明模型。
+        返回: None；不读取任何样本、文件或DBC。
+        异常: TypeError/ValueError为结构错误、名称冲突、来源错误或同步关系冲突。
+        """
+        # 会话名采用同一标识符规则。
+        require_identifier(self.session_id, 'dataset.session')
+        # 容器不得在构造后被调用者改写。
+        if (not isinstance(self.timebase, TimebaseSpec)
+                or self.domain is not None and not isinstance(self.domain, Interval)
+                or any(type(items) is not tuple for items in (self.sources, self.signals, self.derived_names, self.synchronization))):
+            # 不冻结任意迭代器或未知对象。
+            raise TypeError('声明绑定需要typed时基/范围与tuple容器')
+        # 单项必须由对应模型校验，不使用duck typing。
+        if any(not isinstance(item, DeclaredSource) for item in self.sources) or any(not isinstance(item, SignalDefinition) for item in self.signals):
+            # 静态编译也不接受伪造类名。
+            raise TypeError('声明绑定需要DeclaredSource/SignalDefinition')
+        # 来源表只属于当前计划。
+        sources = {item.name: item for item in self.sources}
+        # 重复来源不能字典覆盖。
+        if len(sources) != len(self.sources):
+            # 没有自动选取第一个来源的回退。
+            raise ValueError('source.name重复')
+        # 所有原信号和派生名称必须唯一。
+        names = set()
+        # 原字段只检查已声明来源，不声称实际存在。
+        for definition in self.signals:
+            # 完整单信号契约已经校验。
+            if definition.source not in sources or definition.name in names:
+                # 定位声明中实际冲突的信号。
+                raise ValueError(f'{definition.name}来源不存在或别名重复')
+            # 防止派生与当前信号重名。
+            names.add(definition.name)
+        # 派生名称不以点号或函数名绕过白名单。
+        for name in self.derived_names:
+            # 与实际执行绑定使用同一规则。
+            require_identifier(name, 'derived.name')
+            # 声明整个名称空间，未引用也不能隐藏冲突。
+            if name in names:
+                # 保留用户名称，不加后缀。
+                raise ValueError(f'signals/derived名称冲突：{name}')
+            # 登记下一个冲突校验点。
+            names.add(name)
+        # 同步声明必须唯一且指向当前计划。
+        evidenced = set()
+        # 不从机器时钟或两文件首点为0推断同步。
+        for evidence in self.synchronization:
+            # 正确类型和目标是声明有效性的必要条件。
+            if not isinstance(evidence, SynchronizationEvidence):
+                # 不以文字字符串冒充typed同步说明。
+                raise TypeError('同步需要SynchronizationEvidence')
+            # 重复/未知来源及不同分析时基都拒绝。
+            if evidence.source not in sources or evidence.source in evidenced or evidence.analysis_timebase != self.timebase:
+                # 不静默选一个映射。
+                raise ValueError('同步来源重复/未知或目标时基不一致')
+            # 保留已核实来源声明集合。
+            evidenced.add(evidence.source)
+        # 静态身份显式使用独立版本前缀，不与真实绑定共用证明。
+        # 已有显式Interval仍使用原v1字节；无筛选声明以独立v2前缀和None端点表示。
+        version = 'declaration-v1' if self.domain is not None else 'declaration-v2-no-time-request'
+        payload = (version, self.session_id, self.timebase.timebase_id, self.timebase.time_type.value, self.timebase.origin,
+                   None if self.domain is None else self.domain.start_ns,
+                   None if self.domain is None else self.domain.end_ns,
+                   tuple((item.name, item.timebase.timebase_id, item.timebase.time_type.value, item.timebase.origin, item.offset_ns, item.input_identity) for item in self.sources),
+                   tuple(item.identity() for item in self.signals), self.derived_names,
+                   tuple((item.source, item.evidence) for item in self.synchronization))
+        # 所有身份材料是已校验结构，不调用外部对象repr。
+        object.__setattr__(self, 'identity', sha256(_identity(payload).encode('utf-8')).hexdigest())
+
+    def resolve(self, name: str) -> SignalDefinition:
+        """定位当前声明中的唯一信号别名。
+
+        参数: name简单别名。
+        返回: 当前计划SignalDefinition。
+        异常: ValueError为名称非法或未知。
+        """
+        # 不把semantic点号转换成别名。
+        require_identifier(name, 'signal alias')
+        # 只查当前声明集合。
+        for definition in self.signals:
+            # 保留大小写敏感身份。
+            if definition.name == name:
+                # 不继承上个任务的输入。
+                return definition
+        # 未知信号不能通过空数据隐式创建。
+        raise ValueError(f'未知信号别名：{name}')
+
+    def require_synchronized(self, names: tuple[str, ...]) -> None:
+        """按实际联合依赖检查声明的公共时间基准。
+
+        参数: names为原信号简单别名tuple。
+        返回: None，单来源或公共起点/显式同步依据齐备时通过。
+        异常: TypeError/ValueError为容器、别名或同步缺项。
+        """
+        # 与实际绑定保持相同的依赖接口。
+        if type(names) is not tuple:
+            # 不接受可变或无限依赖列表。
+            raise TypeError('联合依赖names必须为tuple')
+        # 单来源多个信号只产生一个同步成员。
+        used = {self.resolve(name).source for name in names}
+        # 独立来源可在自己坐标中校验。
+        if len(used) <= 1:
+            # 未使用来源不参与当前声明的证据检查。
+            return
+        # 构造已校验所有证据的来源/目标关系。
+        evidenced = {item.source for item in self.synchronization}
+        # 联合计算只检查实际参与来源。
+        for source in self.sources:
+            # 未参与或已有显式固定映射的来源无需重复声明公共起点。
+            if source.name not in used or source.name in evidenced:
+                # 不自动估计其他来源的漂移。
+                continue
+            # absolute坐标已统一为UTC；relative坐标须有相同的完整起点声明。
+            same = source.timebase.time_type is self.timebase.time_type and (source.timebase.time_type is TimeType.ABSOLUTE or source.timebase == self.timebase)
+            # 数值offset本身不能证明同步。
+            if not same:
+                # 提供具体缺项位置供配置修正。
+                raise ValueError(f'联合依赖缺少同步依据：{source.name}；需要公共起点或固定offset核实证据')