chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/sample_reduction.py

@@ -0,0 +1,161 @@
+"""声明有限样本统计事实、数值快照与结构门槛，不执行样本归约。
+
+支持sample_minimum/sample_maximum/sample_mean，BOOL条件可省略为全TRUE。值有效与条件
+已知分别完整划分实际窗口；FALSE不选择，UNKNOWN不当FALSE。真实样本仅计半开
+窗口内原值实际更新且有效/TRUE，TTL、条件更新和裁剪保持边界不能成为样本。
+mean的值覆盖包含整数转float精度门槛，求和、除法和单位故障单独记数值失败。
+纯协议不读来源、不管理预算、不保存全轴；有限元数据及结果由外层owner计费。
+"""
+
+# 两数值后端仅共享冻结协议、单位和几何校验，数值与覆盖计算各自独立。
+from dataclasses import dataclass
+from math import isfinite
+from .integral_sum import require_partial_limit
+from .calculations import CalculationSeries, CalculationDefinition, 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 SampleCalculationFacts:
+    """保存有限块双覆盖与真实选中样本，样本数不代替区间数或时长。
+
+    selected只计条件TRUE且数值可用的正时长，selected_value_unknown只计TRUE值未知。
+    无条件known等于实际跨度、false为0；mean精度失败属于值未知，数值累计失败不改事实。
+    """
+
+    spec: CalculationDefinition  # 原samples请求、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纳秒，不包含条件UNKNOWN。
+    valid_sample_count: int  # 半开窗口中有效/TRUE的原值真实更新。
+    value_unknown_ranges: tuple[Interval, ...]  # 原值和mean精度未知位置。
+    condition_unknown_ranges: tuple[Interval, ...]  # 独立BOOL UNKNOWN位置。
+    quality: Q  # 输入、精度与依赖原因，不含归约数值故障。
+    input_unit: str  # 原分析工程单位，未最终转换。
+    dtype: D  # 原数值声明，极值保持int64/uint64精确整数。
+    binding_identity: str  # 原值联合输入实际身份。
+    source_refs: tuple[SourceRef, ...]  # 完整来源定位，保留真实子类。
+
+    def __post_init__(self):
+        """核对完整双分区、选择交集及typed字段，不修补事实。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为配置、覆盖、类型或几何矛盾。
+        """
+        # 结构配置不执行数值转换，只检查样本统计能力与单位。
+        require_sample_config(self.spec, self.input_unit, self.dtype, 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)
+        # 原生整数纳秒与计数不能接受bool/浮点；TRUE值未知不能超过全部值未知。
+        if (any(type(value) is not int or not 0 <= value <= span for value in durations)
+                or 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('样本事实计数、选择与双覆盖交集矛盾')
+        if _unknown_duration(self.value_unknown_ranges, actual) + self.value_valid_duration_ns != span:
+            raise ValueError('样本值有效与未知未完整划分实际窗口')
+        if _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.binding_identity, 'sample.binding_identity')
+
+
+@dataclass(frozen=True)
+class SampleReductionResult:
+    """保存最终单位数值与真实样本数，不复用时间统计的区间项数语义。
+
+    极值可保留精确int，均值为float；有效零、无样本None和数值失败分别表示。
+    输入覆盖与最终report/strict/空选择分类由外层负责，数值快照不补正常零。
+    """
+
+    value: int | float | None  # 最终单位有限候选，无法核实为None。
+    unit: str  # 最终输出标签，已换单位一次。
+    calculation_failed: bool  # 原序和、除法或最终转换失败。
+    quality: Q  # 仅数值故障，输入原因另存facts。
+    valid_sample_count: int  # 实际参与候选的有效真实样本数。
+
+    def __post_init__(self):
+        """拒绝样本数、正常数值和失败状态之间的矛盾。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为字段类型或不可能数值状态。
+        """
+        # 非有限/bool不能成为正常候选，原整数不被float检查造成舍入。
+        require_text(self.unit, 'sample.output_unit')
+        if self.value is not None and (type(self.value) not in (int, float)
+                or type(self.value) is float and not isfinite(self.value)):
+            raise ValueError('样本结果需要有限int/float或None')
+        if (type(self.calculation_failed) is not bool or not isinstance(self.quality, Q)
+                or type(self.valid_sample_count) is not int or self.valid_sample_count < 0):
+            raise TypeError('样本结果需要真实失败状态、质量和非负原生int计数')
+        # 空样本只能无值；有效失败须有样本及原因，成功不带数值故障位。
+        if self.calculation_failed:
+            if self.value is not None or self.quality == Q.NONE or self.valid_sample_count == 0:
+                raise ValueError('样本数值失败需要有效样本、None与明确原因')
+        elif self.quality != Q.NONE or (self.valid_sample_count == 0) != (self.value is None):
+            raise ValueError('样本成功结果数值、计数或质量矛盾')
+
+
+def require_sample_config(spec, input_unit, dtype, partial_limit):
+    """校验三samples能力、数值dtype与明确单位，不计算样本。
+
+    参数: 原spec/input_unit/dtype及正原生int误差容量partial_limit。
+    返回: (output_unit, factor)。异常: TypeError/ValueError为类型、能力、单位或容量。
+    """
+    # BOOL/ENUM与时间算子各有独立口径，不在本核中暗自提升或扩展。
+    if not isinstance(spec, CalculationDefinition) or spec.operation not in ('sample_minimum', 'sample_maximum', 'sample_mean'):
+        raise TypeError('样本归约仅支持sample_minimum/sample_maximum/sample_mean')
+    if not isinstance(dtype, D) or dtype not in (D.INT64, D.UINT64, D.FLOAT64):
+        raise ValueError('样本统计只接受数值dtype')
+    require_text(input_unit, 'sample.input_unit')
+    require_partial_limit(partial_limit)
+    return calculation_unit(spec, input_unit)
+
+
+def require_sample_series(series, spec, input_unit, dtype):
+    """核对有限输入unit/dtype及精确交集，保留可选BOOL条件。
+
+    参数: series为有限CalculationSeries，其余为归约原配置。
+    返回: 实际交集Interval或None。异常: TypeError/ValueError/OverflowError。
+    """
+    # CalculationSeries已校验可选条件列为BOOL；不自动换单位、转dtype或补原值更新。
+    if not isinstance(series, CalculationSeries):
+        raise TypeError('样本归约需要CalculationSeries')
+    if series.unit != input_unit or series.values[0].dtype is not dtype:
+        raise ValueError('样本归约只接受同unit及同dtype输入')
+    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

chronaxis/core/sample_reduction_numpy.py

@@ -0,0 +1,160 @@
+"""用真实NumPy样本与覆盖掩码归约有限min/max/sample_mean。
+
+输入值及可选BOOL为(N,)typed列，覆盖为(N-1,)精确int64差与bool掩码；真实样本
+按半开窗口原值actual更新、有效和条件TRUE选择。极值保持原dtype，mean只转换
+可核实值，并将原序样本推进本后端有界误差核。finish先完成原单位总和、除真实
+样本数，再转换输出一次；原量纲中间溢出不改为时间规范权重。输入覆盖与数值
+故障分开，不调用参考核、不重读来源、不保留全轴，有限临时内存由外层计费。
+"""
+
+# 数值与覆盖均用独立真实数组运算，仅共享typed模型与本数组原序误差状态。
+import numpy as np
+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 .sample_reduction import SampleCalculationFacts, SampleReductionResult, require_sample_config, require_sample_series
+from .types import QualityFlag as Q
+
+
+class NumpySampleReduction:
+    """保存单原dtype候选、真实样本数和有界误差列，不留存历史样本数组。"""
+
+    def __init__(self, spec, input_unit, dtype, *, partial_limit=4096):
+        """检查原配置并建立本数组后端有限状态。
+
+        参数: spec/input_unit/dtype为原声明，partial_limit为正原生int误差容量。
+        返回: None。异常: 配置、分配错误传播。
+        """
+        # 共享静态门槛不执行样本、浮点或覆盖计算。
+        self._unit, self._factor = require_sample_config(spec, input_unit, dtype, partial_limit)
+        self._spec, self._input_unit, self._dtype = spec, input_unit, dtype
+        self._identity = self._candidate = None
+        self._value_duration = self._selected_duration = self._samples = 0
+        self._sum = NumpyIntegralSum(partial_limit) if spec.operation == 'sample_mean' else None
+
+    @property
+    def selected_duration_ns(self):
+        """读取累计TRUE有效保持时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._selected_duration  # 不是样本mean分母。
+
+    @property
+    def value_valid_duration_ns(self):
+        """读取累计值有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._value_duration  # 与选择条件独立。
+
+    @property
+    def valid_sample_count(self):
+        """读取有效真实样本数。参数: 无。返回: 原生int。异常: 无。"""
+        return self._samples  # 条件/TTL/边界更新不计入。
+
+    def push(self, series):
+        """独立数组计算双覆盖、真实样本掩码并推进对应候选。
+
+        参数: series为同unit/dtype有限CalculationSeries，可选条件None表示全TRUE。
+        返回: SampleCalculationFacts；mean精度入值覆盖，数值归约故障不改覆盖。
+        异常: 结构、身份、容量、分配或取消传播；异常后外层只能清理owner。
+        内存: 新列形状N/N-1或当前所选样本数，当前push存活，不修改输入列。
+        """
+        # 有限输入结构和整数交集先验证，禁止跨块更换原值绑定。
+        actual = require_sample_series(series, self._spec, self._input_unit, self._dtype)
+        if self._identity is not None and self._identity != series.binding_identity:
+            raise ValueError('样本归约不能跨绑定身份累计')
+        self._identity = series.binding_identity
+        # N个typed原值、有效性与uint16质量独立装箱；无效0只是掩码约束的存储占位。
+        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))
+        # mean独立数组精度门槛，极值原int64/uint64保持；无条件显式全TRUE而非UNKNOWN。
+        values = to_float_numpy(column) if self._spec.operation == 'sample_mean' else column
+        size = len(series.times_ns)
+        known = np.ones(size, dtype=bool) if series.conditions is None else np.array([condition.valid for condition in series.conditions], dtype=bool)
+        truth = np.ones(size, dtype=bool) if series.conditions is None else np.array([condition.value if condition.valid else False for condition in series.conditions], dtype=bool)
+        condition_quality = np.zeros(size, dtype=np.uint16) if series.conditions is None else 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差，绝对时间不转float，域外反序差不wrap。
+        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)
+        value_valid = observed & values.valid[:-1]
+        selected = value_valid & known[:-1] & truth[:-1]
+        value_duration = int(np.sum(durations, where=value_valid, dtype=np.int64))
+        known_duration = int(np.sum(durations, where=observed & known[:-1], dtype=np.int64))
+        selected_duration = int(np.sum(durations, where=selected, dtype=np.int64))
+        selected_unknown = int(np.sum(durations, where=observed & known[:-1] & truth[:-1] & ~values.valid[:-1], dtype=np.int64))
+        false_duration = int(np.sum(durations, where=observed & known[:-1] & ~truth[:-1], dtype=np.int64))
+        # 样本(N,)掩码单独使用actual更新，不能由区间selected或条件变化推算。
+        actual_samples = (times >= start) & (times < end) & np.array(series.actual_value_updates, dtype=bool)
+        samples = actual_samples & values.valid & known & truth
+        sample_count = int(np.count_nonzero(samples))
+        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)))
+        # Python仅恢复有限未知定位；时长和样本计数均已由真实数组掩码归约。
+        value_unknown = tuple(Interval(int(left[index]), int(right[index])) for index in np.flatnonzero(observed & ~values.valid[:-1]))
+        condition_unknown = tuple(Interval(int(left[index]), int(right[index])) for index in np.flatnonzero(observed & ~known[:-1]))
+        if self._sum is not None:
+            # 按原(N,)位置顺序选择原单位样本，不先块求和或块均值；只读列交给本后端误差核。
+            chosen = values.values[samples]
+            keep = np.ones(len(chosen), dtype=bool)
+            chosen.setflags(write=False)
+            keep.setflags(write=False)
+            self._sum.push_values(chosen, keep)
+        elif sample_count:
+            # 极值当前样本列用原dtype数组归约，跨块仅保留一个同dtype候选。
+            candidate = (np.min if self._spec.operation == 'sample_minimum' else np.max)(values.values[samples])
+            if self._candidate is not None:
+                previous = DTYPES[self._dtype].type(self._candidate)
+                candidate = (np.minimum if self._spec.operation == 'sample_minimum' else np.maximum)(previous, candidate)
+            self._candidate = candidate.item()
+        # 跨块仅累计三个原生计数；冻结事实保留原请求、双未知与完整真实来源。
+        self._value_duration += value_duration
+        self._selected_duration += selected_duration
+        self._samples += sample_count
+        return SampleCalculationFacts(self._spec, actual, value_duration, known_duration, selected_duration,
+            selected_unknown, false_duration, sample_count, merge_ranges(value_unknown), merge_ranges(condition_unknown),
+            quality, self._input_unit, self._dtype, series.binding_identity, series.source_refs)
+
+    def finish(self):
+        """完成原单位样本总和后除计数，并仅一次转换最终单位。
+
+        参数: 无。返回: SampleReductionResult快照，覆盖政策由外层分类。
+        异常: 配置、分配或取消传播；原序和、除法、精度、换算故障写None与质量。
+        """
+        # 没有真实有效样本只能无候选，保持时长不能替代此计数证明0。
+        if self._samples == 0:
+            return SampleReductionResult(None, self._unit, False, Q.NONE, 0)
+        quality = Q.NONE
+        if self._sum is not None:
+            # 原单位factor=1先完成raw总和，原量纲中途溢出保持失败，不预规范化样本。
+            number = self._sum.finish(self._input_unit)
+            if number.calculation_failed:
+                return SampleReductionResult(None, self._unit, True, number.quality, self._samples)
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                value = np.divide(np.float64(number.value), np.float64(self._samples)).item()
+            if not np.isfinite(value) or value == 0 and number.value != 0:
+                quality |= Q.NONFINITE if not np.isfinite(value) else Q.PRECISION_LOSS
+        else:
+            value = self._candidate
+        # 极值factor=1保留原生整数；明确换单位先用本数组精度核核对可表示性。
+        if quality == Q.NONE and 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
+        # 只规范成功浮点零，不清除数值故障或改写真实样本/输入覆盖事实。
+        if quality == Q.NONE and type(value) is float and value == 0:
+            value = 0.0
+        return SampleReductionResult(None if quality != Q.NONE else value, self._unit, quality != Q.NONE, quality, self._samples)

chronaxis/core/sample_reduction_reference.py

@@ -0,0 +1,154 @@
+"""独立标量归约有限真实样本，保留原dtype极值与原序样本算术均值。
+
+push分别计算值/条件覆盖，只将半开窗中有效/TRUE原值真实更新计入候选。极值
+保留原整数；mean先检查float精度，原单位样本按原序推进有界误差核，finish完成
+原量纲总和后除真实样本数，再换输出单位一次。原序中间溢出沿既有故障政策保持
+失败，不改为time_weighted_mean的规范化权重；除法/换算故障不改输入覆盖。不调用NumPy、
+不读来源、不保留全轴；有限临时样本和误差项须由外层owner计费，异常后须清理。
+"""
+
+# 标量覆盖及候选独立于数组后端；仅复用本参考原序误差状态。
+from math import isfinite
+from .integral_sum_reference import ReferenceIntegralSum
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric import ScalarValue, to_float_reference
+from .sample_reduction import SampleCalculationFacts, SampleReductionResult, require_sample_config, require_sample_series
+from .types import QualityFlag as Q, SignalDType as D
+
+
+class ReferenceSampleReduction:
+    """保存单原生候选、真实样本计数与有界误差项，不存历史输入列。"""
+
+    def __init__(self, spec, input_unit, dtype, *, partial_limit=4096):
+        """核对原配置并建立本参考后端有限状态。
+
+        参数: spec/input_unit/dtype为原声明，partial_limit为正原生int误差容量。
+        返回: None。异常: 配置或分配错误传播。
+        """
+        # 共享静态门槛先检查明确样本能力、数值类型和输出单位。
+        self._unit, self._factor = require_sample_config(spec, input_unit, dtype, partial_limit)
+        self._spec, self._input_unit, self._dtype = spec, input_unit, dtype
+        self._identity = self._candidate = None
+        self._value_duration = self._selected_duration = self._samples = 0
+        self._sum = ReferenceIntegralSum(partial_limit) if spec.operation == 'sample_mean' else None
+
+    @property
+    def selected_duration_ns(self):
+        """读取累计TRUE值有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._selected_duration  # 不作为样本均值分母。
+
+    @property
+    def value_valid_duration_ns(self):
+        """读取累计值有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._value_duration  # 与条件TRUE/FALSE/UNKNOWN独立。
+
+    @property
+    def valid_sample_count(self):
+        """读取有效真实样本数。参数: 无。返回: 原生int。异常: 无。"""
+        return self._samples  # TTL/条件更新或裁剪保持不增加此数。
+
+    def push(self, series):
+        """消费有限块双覆盖与真实样本，不以保持区间代替样本。
+
+        参数: series为同unit/dtype有限CalculationSeries，条件可省略为全TRUE。
+        返回: SampleCalculationFacts；mean精度失败进入输入覆盖，求和故障不改覆盖。
+        异常: 结构、身份、容量、分配或取消传播；外层异常后不能接着使用前缀状态。
+        """
+        # 输入结构和交集先核对，跨块原表达式绑定身份必须保持。
+        actual = require_sample_series(series, self._spec, self._input_unit, self._dtype)
+        if self._identity is not None and self._identity != series.binding_identity:
+            raise ValueError('样本归约不能跨绑定身份累计')
+        self._identity = series.binding_identity
+        # 只有mean走浮点精度门槛，min/max不把大整数舍入为float。
+        values = tuple(to_float_reference(value) for value in series.values) if self._spec.operation == 'sample_mean' else series.values
+        unconditional = ScalarValue(True, D.BOOL)
+        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 = samples = 0
+        value_unknown, condition_unknown, chosen = [], [], []
+        quality = Q.NONE
+        # 独立逐正区间计算双覆盖；这只说明保持事实，不向数值样本归约添加值。
+        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 = values[index]
+            condition = series.conditions[index] if series.conditions is not None else unconditional
+            dt = right-left
+            quality |= series.diagnostics[index] | value.quality | condition.quality
+            if value.valid:
+                value_duration += dt
+            else:
+                value_unknown.append(Interval(left, right))
+            if condition.valid:
+                known_duration += dt
+                if not condition.value:
+                    false_duration += dt
+                elif value.valid:
+                    selected_duration += dt
+                else:
+                    selected_unknown += dt
+            else:
+                condition_unknown.append(Interval(left, right))
+        # 半开窗口真实原值更新才进入候选；外条件变化和共享右端不产生样本。
+        for index, time in enumerate(series.times_ns):
+            if not start <= time < end or not series.actual_value_updates[index]:
+                continue
+            value = values[index]
+            condition = series.conditions[index] if series.conditions is not None else unconditional
+            quality |= series.diagnostics[index] | value.quality | condition.quality
+            if not value.valid or not condition.valid or not condition.value:
+                continue
+            samples += 1
+            if self._spec.operation == 'sample_mean':
+                chosen.append(value.value)
+            else:
+                # 极值只存一个原dtype候选，不按时长加权或保留跨块样本集合。
+                self._candidate = value.value if self._candidate is None else (min if self._spec.operation == 'sample_minimum' else max)(self._candidate, value.value)
+        # raw原单位样本按原序推进；中间溢出不会因后续抵消恢复正常。
+        if self._sum is not None:
+            self._sum.push_values(tuple(chosen), (True,)*len(chosen))
+        # 跨块只留精确计数，返回的有限双未知和来源仍需外层owner计费及管理生命周期。
+        self._value_duration += value_duration
+        self._selected_duration += selected_duration
+        self._samples += samples
+        return SampleCalculationFacts(self._spec, actual, value_duration, known_duration, selected_duration,
+            selected_unknown, false_duration, samples, merge_ranges(value_unknown), merge_ranges(condition_unknown),
+            quality, self._input_unit, self._dtype, series.binding_identity, series.source_refs)
+
+    def finish(self):
+        """完成原单位总和、除真实样本数，再仅一次转换输出单位。
+
+        参数: 无。返回: SampleReductionResult快照，不清空状态或分类覆盖政策。
+        异常: 配置/分配错误传播；原序和、除法、精度或换算故障返回None及质量。
+        """
+        # 空真实样本没有数值证据，即使保持值长期有效也不能补正常零。
+        if self._samples == 0:
+            return SampleReductionResult(None, self._unit, False, Q.NONE, 0)
+        quality = Q.NONE
+        if self._sum is not None:
+            # 此处原单位factor=1先完成总和，不能先输出换单位或先归约块均值。
+            number = self._sum.finish(self._input_unit)
+            if number.calculation_failed:
+                return SampleReductionResult(None, self._unit, True, number.quality, self._samples)
+            value = number.value / self._samples
+            if not isfinite(value) or value == 0 and number.value != 0:
+                quality |= Q.NONFINITE if not isfinite(value) else Q.PRECISION_LOSS
+        else:
+            value = self._candidate
+        # 非1倍率极值先检查整数可精确float表示；倍率1保留原生整数。
+        if quality == Q.NONE and 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 and self._factor != 1:
+            original = value
+            value *= self._factor
+            if not isfinite(value) or value == 0 and original != 0:
+                quality |= Q.NONFINITE if not isfinite(value) else Q.PRECISION_LOSS
+        # 成功浮点零统一+0.0；所有数值故障保留真实样本数而不改输入覆盖。
+        if quality == Q.NONE and type(value) is float and value == 0:
+            value = 0.0
+        return SampleReductionResult(None if quality != Q.NONE else value, self._unit, quality != Q.NONE, quality, self._samples)

chronaxis/core/selection.py

@@ -0,0 +1,74 @@
+"""声明已解码信号层的选择行，保留时间、原值、三值状态和来源身份。
+
+输入为CalculationSeries和select请求，输出由各独立后端逐行迭代SelectionRow。
+TRUE行是已知选中；UNKNOWN行用于保留无法决定的诊断，消费方必须检查selection。
+FALSE行被过滤。只输出目标表达式依赖的真实时间组更新，不伪造裁剪或TTL样本。
+本模块仅验证不可变协议，不计算筛选掩码、不读写文件、不改变旧读取或解码。
+来源定位是绑定字段与时间组，不宣称保存旧日志的物理行号或逐消息求值序号。
+输入仍为完整内存历史；逐行输出不意味着AnalysisRunner的内存预算已经实现。
+"""
+
+# 冻结行协议避免消费者修改结果身份。
+from dataclasses import dataclass
+# 只共享静态模型，不包含筛选数值内核。
+from .calculations import CalculationSeries, CalculationDefinition
+from .models import SourceRef
+from .numeric import ScalarValue
+from .types import Truth, QualityFlag as Q
+from .validation import require_text
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class SelectionRow:
+    """保存一个真实表达式更新时间组的选择结果。
+
+    value保持原dtype、枚举标签、有效性和质量；selection只允许TRUE或UNKNOWN。
+    quality汇总原依赖、值及条件原因；binding_identity与source_refs定位当前输入。
+    unit保留当前分析值单位；行流不执行隐式单位换算。
+    所有字段不可变，没有跨任务状态；UNKNOWN不是已知选中，不能隐式转bool。
+    """
+
+    time_ns: int  # 原子更新时间组的精确纳秒时间。
+    value: ScalarValue  # 原typed值，未知不填正常零，枚举不输出内部整数编码。
+    selection: Truth  # TRUE选中或UNKNOWN诊断，不包含明确FALSE行。
+    quality: Q  # 原值、条件与依赖的完整质量原因。
+    binding_identity: str  # 当前表达式/选择条件的实际执行身份。
+    source_refs: tuple[SourceRef, ...]  # 当前所有依赖的原字段定位。
+    unit: str  # 当前分析值单位，和原typed值一起保留。
+
+    def __post_init__(self):
+        """验证行类型、时间和当前来源身份，不执行筛选。
+
+        参数: 无；读取冻结字段。
+        返回: None。
+        异常: TypeError/ValueError/OverflowError为不合法协议。
+        """
+        # 保持精确int64时间，不接受float或bool冒充坐标。
+        require_int64_ns(self.time_ns, 'selection.time_ns')
+        # FALSE不属于输出，value即使无效也必须有完整typed质量。
+        if not isinstance(self.value, ScalarValue) or self.selection not in (Truth.TRUE, Truth.UNKNOWN) or not isinstance(self.quality, Q):
+            raise TypeError('选择行需typed值、TRUE/UNKNOWN及QualityFlag')
+        # 身份不可为空；来源引用必须冻结且是完整字段模型。
+        require_text(self.binding_identity, 'selection.binding_identity')
+        require_text(self.unit, 'selection.unit')
+        if not isinstance(self.source_refs, tuple) or any(not isinstance(ref, SourceRef) for ref in self.source_refs):
+            raise TypeError('选择行来源需tuple SourceRef')
+        # 输出不能隐藏原值原因，UNKNOWN必须保留至少一个质量诊断。
+        if self.quality & self.value.quality != self.value.quality or self.selection is Truth.UNKNOWN and self.quality == Q.NONE:
+            raise ValueError('选择行质量不能隐藏无效值或UNKNOWN原因')
+
+
+def require_selection(series, spec):
+    """验证选择行流的输入，不把行流当成标量或隐式换单位。
+
+    参数: series为CalculationSeries，spec为operation=select的CalculationDefinition。
+    返回: None。
+    异常: TypeError为模型错误；ValueError为算子或单位转换请求。
+    """
+    # 两个后端共享已校验协议，筛选算法仍独立。
+    if not isinstance(series, CalculationSeries) or not isinstance(spec, CalculationDefinition):
+        raise TypeError('选择行流需CalculationSeries和CalculationDefinition')
+    # 此入口保留原值，转换需要先在分析表达式/绑定中明确完成。
+    if spec.operation != 'select' or spec.output_unit not in (None, series.unit):
+        raise ValueError('选择行流需select且保留输入单位')