chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/execution/historical_sample_calculation.py

@@ -0,0 +1,338 @@
+"""从有限历史块得到完整的样本极值或算术均值，可附独立BOOL选择条件。
+
+输入是已封存的新解码历史、原保持上下文、实际绑定、编译表达式和原指标请求。
+每次step最多消费一个有限块；均值不建立第二遍块源，也不重新扫描原来源。
+样本均值累计原序真实更新的原单位总和，完整EOF后除总样本数并换单位一次。
+TTL、条件更新和裁剪保持不增加样本；完整双覆盖、未知和来源动态先预约费用。
+observation显式限制原domain内的计算观测域，样本只取该域半开范围内真实更新；
+None兼容原domain及原预算，不证明实际观测。原context、绑定和请求窗口不改变。
+自有分块者、当前块、数值状态和结果由close释放；借用历史、上下文与绑定保持。
+预算是新分析层保守估算，超限明确失败，不承诺进程RSS或旧来源缓冲受控。
+"""
+
+# 只组合新分析分块者、独立样本核和既有结果政策，历史读写与解码保持原样。
+from ..core.decoded_binding import DecodedBindings
+from ..core.expression import CompiledExpression
+from ..core.calculations import CalculationDefinition, make_calculation_result
+from ..core.models import Interval
+from ..core.sample_reduction import SampleCalculationFacts
+from ..core.types import QualityFlag as Q
+from ..results.errors import ResultClosedError
+from .history import DecodedHistoryStore, _metadata_bytes
+from .hold import HoldContext
+from .calculation_blocks import HistoricalCalculationBlocks, _calculation_observation
+from .historical_conditional_blocks import HistoricalConditionalBlocks
+
+
+def _append_ranges(existing, incoming):
+    """合并同一种未知的相邻范围，保留真实已知间隔。
+
+    参数: existing/incoming为已校验有序Interval tuple。返回: 冻结有序tuple。
+    异常: ValueError为重叠；分配错误传播，调用方须先预约全部候选元数据。
+    """
+    # 仅合并首尾相接的诊断，不填补中间已知值或可判断条件。
+    result = list(existing)
+    for item in incoming:
+        if result and item.start_ns < result[-1].end_ns:
+            raise ValueError('样本指标未知范围重叠')
+        if result and item.start_ns == result[-1].end_ns:
+            result[-1] = Interval(result[-1].start_ns, item.end_ns)
+        else:
+            result.append(item)
+    return tuple(result)
+
+
+class HistoricalSampleCalculation:
+    """拥有一次有限回读及整窗事实，完整EOF后才开放最终CalculationResult。
+
+    极值只留单候选，均值只留有界误差项和真实样本数，不累计全窗值列。
+    数值故障与覆盖事实分开；操作异常后只可close，清理取消保留重试金额和句柄。
+    """
+
+    def __init__(self, history, context, bindings, compiled, spec, condition=None, *,
+                 backend='numpy', batch_intervals=64, partial_limit=4096, observation=None):
+        """校验输入，预留固定状态，再创建自有分块者和纯样本核。
+
+        参数: history/context/bindings/compiled为真实新历史及原运行契约；spec为三samples请求；
+            condition为可选BOOL表达式，None表示全TRUE；backend为reference或numpy；
+            batch_intervals为有限正区间数，partial_limit为浮点误差项容量。
+            observation为原domain内已核实Interval；None保留原domain，不是观测证明。
+        返回: 尚未消费历史的新owner。
+        异常: 类型、能力、预算或构造错误；持续清理失败的原异常附
+            historical_sample_calculation_cleanup_owner，恢复环境后可调用其close。
+        """
+        # 来源身份与BOOL条件仍由真实分块者校验；本层先拒绝模型和能力错误。
+        if (not isinstance(history, DecodedHistoryStore) or not isinstance(context, HoldContext)
+                or not isinstance(bindings, DecodedBindings) or not isinstance(compiled, CompiledExpression)
+                or not isinstance(spec, CalculationDefinition)
+                or condition is not None and not isinstance(condition, CompiledExpression)):
+            raise TypeError('历史样本指标需真实历史、保持上下文、绑定、表达式和CalculationDefinition')
+        if spec.operation not in ('sample_minimum', 'sample_maximum', 'sample_mean'):
+            raise ValueError('当前样本归约只接三种samples算子')
+        if (backend not in ('reference', 'numpy') or type(batch_intervals) is not int
+                or batch_intervals < 1 or type(partial_limit) is not int or partial_limit < 1):
+            raise ValueError('历史样本指标需合法后端、正块大小与误差项容量')
+        # 冻结原请求的真实交集和初始自有状态，借用资源只保存引用，不接管其生命周期。
+        observed = _calculation_observation(context, observation)
+        left = max(observed.start_ns, spec.window.start_ns)
+        right = min(observed.end_ns, spec.window.end_ns)
+        self._actual = Interval(left, right) if left <= right else None
+        self._history, self._context, self._bindings = history, context, bindings
+        self._observation = observation
+        self._compiled, self._spec, self._condition, self._backend = compiled, spec, condition, backend
+        self._batch_intervals, self._partial_limit = batch_intervals, partial_limit
+        self._budget, self._held_cost = history.budget, 0
+        self._blocks = self._current = self._reducer = self._result = None
+        self._closed = self._closing = self._failed = self._finished = False
+        self._fact_cost = 0
+        self._cursor = None if self._actual is None else self._actual.start_ns
+        self._value_duration = self._selected_duration = self._sample_count = 0
+        self._known_duration = self._selected_value_unknown = self._false_duration = 0
+        self._unknown, self._condition_unknown, self._refs, self._quality = (), (), (), Q.NONE
+        try:
+            # 固定有界误差状态与原契约先计费，动态诊断与有限核工作区另行预约。
+            identity = None if condition is None else condition.identity
+            self._reserve(131072 + 1024 * partial_limit +
+                          16 * _metadata_bytes((context, bindings.sources, compiled.identity, identity, spec))
+                          + (0 if observation is None else 16 * _metadata_bytes(observation)))
+            self._reducer = self._make_reducer()
+            self._blocks = self._make_blocks()
+        except BaseException as exc:
+            # 子构造未返回时接管其原异常上的实际自有恢复句柄，不关闭借用历史。
+            attr = 'calculation_blocks_cleanup_owner' if condition is None else 'conditional_blocks_cleanup_owner'
+            child = getattr(exc, attr, None)
+            if child is not None:
+                self._blocks = child
+            try:
+                self.close()
+            except BaseException as cleanup:
+                exc.add_note(f'历史样本指标构造清理失败: {type(cleanup).__name__}')
+                if not self._closed:
+                    try:
+                        self.close()
+                    except BaseException as retry:
+                        exc.add_note(f'历史样本指标构造清理重试失败: {type(retry).__name__}')
+                        if not self._closed:
+                            exc.historical_sample_calculation_cleanup_owner = self
+            raise
+
+    def _make_reducer(self):
+        """创建所选后端的独立样本核，不需要预先知道均值分母。
+
+        参数: 无。返回: 对应SampleReduction。异常: 原配置、数值模型或分配错误。
+        """
+        if self._backend == 'reference':
+            from ..core.sample_reduction_reference import ReferenceSampleReduction
+            factory = ReferenceSampleReduction
+        else:
+            from ..core.sample_reduction_numpy import NumpySampleReduction
+            factory = NumpySampleReduction
+        # 实际每块仍校验unit/dtype，均值计数来自原值实际更新，不能按块数平均。
+        return factory(self._spec, self._compiled.root.unit, self._compiled.root.dtype,
+                       partial_limit=self._partial_limit)
+
+    def _make_blocks(self):
+        """创建一次自有历史回读者，按可选条件选择单源或联合边界。
+
+        参数: 无。返回: HistoricalCalculationBlocks或HistoricalConditionalBlocks。
+        异常: 原构造、身份、条件或预算错误；持续清理入口由构造调用方接管。
+        """
+        # 同一观测域决定半开真实样本截止；条件两路不能回退到原domain。
+        if self._condition is None:
+            return HistoricalCalculationBlocks(self._history, self._context, self._bindings,
+                self._compiled, self._spec, backend=self._backend, batch_intervals=self._batch_intervals,
+                observation=self._observation)
+        return HistoricalConditionalBlocks(self._history, self._context, self._bindings,
+            self._compiled, self._spec, self._condition, backend=self._backend,
+            batch_intervals=self._batch_intervals, observation=self._observation)
+
+    @property
+    def closed(self):
+        """读取实际关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    @property
+    def failed(self):
+        """读取操作失败状态。参数: 无。返回: bool。异常: 无。"""
+        return self._failed
+
+    @property
+    def finished(self):
+        """读取完整分类状态。参数: 无。返回: bool。异常: 无。"""
+        return self._finished
+
+    @property
+    def result(self):
+        """借出完整窗口结果，关闭或失败后不再开放。
+
+        参数: 无。返回: CalculationResult。异常: 未完成/失败/关闭时拒绝。
+        """
+        self._require_open()
+        if self._failed or not self._finished:
+            raise RuntimeError('历史样本指标尚未成功完成')
+        return self._result
+
+    def _require_open(self):
+        """拒绝半关闭或已关闭操作。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed or self._closing:
+            raise ResultClosedError('历史样本指标已关闭或正在清理')
+
+    def _reserve(self, amount):
+        """先申请本owner费用，按实际账本接管成功后取消。
+
+        参数: amount为bytes。返回: None。异常: 预算或取消错误。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.reserve_ram(amount)
+        finally:
+            if self._budget.ram_bytes == before + amount:
+                self._held_cost += amount
+
+    def _release(self, amount):
+        """扣账后即更新自有金额，释放前取消保留重试。
+
+        参数: amount为bytes。返回: None。异常: 原释放或取消错误。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.release_ram(amount)
+        finally:
+            if self._budget.ram_bytes == before - amount:
+                self._held_cost -= amount
+
+    def _append_facts(self, facts):
+        """核对连续完整划分，先计费再保存双未知和完整来源。
+
+        参数: facts为纯核当前有限SampleCalculationFacts。返回: None。
+        异常: 结构、身份、重复范围、预算或复制失败，此后只可关闭。
+        """
+        if (not isinstance(facts, SampleCalculationFacts) or facts.spec != self._spec
+                or facts.input_unit != self._compiled.root.unit or facts.dtype != self._compiled.root.dtype
+                or facts.binding_identity != self._compiled.identity):
+            raise ValueError('样本块事实与原请求或真实表达式不同')
+        actual = facts.actual_window
+        if actual is None:
+            if self._actual is not None:
+                raise ValueError('样本块缺失真实交集')
+        elif self._actual is None or actual.start_ns != self._cursor or actual.end_ns > self._actual.end_ns:
+            raise ValueError('样本块必须按真实交集连续推进')
+        # 候选复制时旧事实仍存在，动态计费含双未知及完整SourceRef子类的全部定位。
+        candidate_cost = 65536 + 16 * (_metadata_bytes((self._unknown, self._condition_unknown, self._refs))
+                                     + _metadata_bytes(facts))
+        self._reserve(candidate_cost)
+        value_unknown = _append_ranges(self._unknown, facts.value_unknown_ranges)
+        condition_unknown = _append_ranges(self._condition_unknown, facts.condition_unknown_ranges)
+        refs = list(self._refs)
+        for item in facts.source_refs:
+            if not any(type(item) is type(previous) and item == previous for previous in refs):
+                refs.append(item)
+        # 只安装已校验候选；释放旧费用取消时，全部金额仍归本owner，不能交付前缀结果。
+        old_cost = self._fact_cost
+        self._unknown, self._condition_unknown, self._refs = value_unknown, condition_unknown, tuple(refs)
+        self._value_duration += facts.value_valid_duration_ns
+        self._selected_duration += facts.selected_duration_ns
+        self._sample_count += facts.valid_sample_count
+        self._known_duration += facts.condition_known_duration_ns
+        self._selected_value_unknown += facts.selected_value_unknown_duration_ns
+        self._false_duration += facts.false_duration_ns
+        self._quality |= facts.quality
+        self._cursor = None if actual is None else actual.end_ns
+        self._fact_cost = candidate_cost
+        self._release(old_cost)
+
+    def _facts_snapshot(self):
+        """完整EOF后构造整窗事实，不以未完成前缀冒充整窗。
+
+        参数: 无。返回: SampleCalculationFacts。异常: 完整范围或双覆盖矛盾。
+        """
+        if self._actual is not None and self._cursor != self._actual.end_ns:
+            raise ValueError('样本指标尚未完整消费真实交集')
+        duration = 0 if self._actual is None else self._actual.end_ns - self._actual.start_ns
+        # 两个独立分区均需覆盖实际域，FALSE已知，不能计入条件未知。
+        if self._value_duration + sum(item.end_ns - item.start_ns for item in self._unknown) != duration:
+            raise ValueError('样本全窗值覆盖不完整')
+        if self._known_duration + sum(item.end_ns - item.start_ns for item in self._condition_unknown) != duration:
+            raise ValueError('样本全窗条件覆盖不完整')
+        return SampleCalculationFacts(self._spec, self._actual, self._value_duration,
+            self._known_duration, self._selected_duration, self._selected_value_unknown,
+            self._false_duration, self._sample_count, self._unknown, self._condition_unknown,
+            self._quality, self._compiled.root.unit, self._compiled.root.dtype,
+            self._compiled.identity, self._refs)
+
+    def _finish(self):
+        """按完整事实和最终数值分类一次，原序样本和无需第二遍。
+
+        参数: 无。返回: False表示最终完成。异常: 覆盖、数值快照、预算或取消错误。
+        """
+        # 快照与分类复制前先预约完整双未知和来源；费用持有至close，不是临时裸分配。
+        self._reserve(65536 + 16 * _metadata_bytes((self._unknown, self._condition_unknown, self._refs)))
+        facts = self._facts_snapshot()
+        number = self._reducer.finish()
+        duration = 0 if facts.actual_window is None else facts.actual_window.end_ns - facts.actual_window.start_ns
+        # 只有请求全窗充分FALSE才证明空选择；无真实样本与UNKNOWN仍按既有政策区分。
+        all_false = (facts.actual_window == self._spec.window and duration > 0
+                     and facts.false_duration_ns == duration)
+        self._result = make_calculation_result(self._spec, facts, number.value, number.unit, facts.actual_window,
+            facts.value_valid_duration_ns, facts.condition_known_duration_ns, facts.selected_duration_ns,
+            facts.selected_value_unknown_duration_ns, facts.valid_sample_count,
+            facts.value_unknown_ranges, facts.condition_unknown_ranges, facts.quality | number.quality,
+            all_false=all_false, calculation_failed=number.calculation_failed)
+        self._finished = True
+        return False
+
+    def step(self):
+        """处理至多一个有限块，完整EOF分类后才返回False。
+
+        参数: 无。返回: bool；完成后重复False。异常: 读取/数值/预算/取消错误，随后仅close。
+        """
+        self._require_open()
+        if self._failed:
+            raise RuntimeError('失败的样本指标只能关闭')
+        if self._finished:
+            return False
+        try:
+            try:
+                self._current = next(self._blocks)
+            except StopIteration:
+                return self._finish()
+            # 有限N行数组、掩码和样本临时先预约；不累积全窗值，原单位总和只留有界状态。
+            series = self._current.series
+            workspace = 65536 + 2048 * len(series.times_ns) + 16 * _metadata_bytes(series.source_refs)
+            self._reserve(workspace)
+            facts = self._reducer.push(series)
+            self._append_facts(facts)
+            del facts, series
+            self._current.close()
+            self._current = None
+            self._release(workspace)
+            return True
+        except BaseException:
+            self._failed = True
+            raise
+
+    def close(self):
+        """关闭自有当前块、分块者和金额，保留借用历史及原调用方状态。
+
+        参数: 无。返回: None，重复关闭安全。异常: 关闭或释放取消可重试。
+        """
+        if self._closed:
+            return
+        # 进入清理即禁止结果访问；每个自有句柄仅在close成功后移除，取消时留待重试。
+        self._closing = True
+        try:
+            if self._current is not None:
+                self._current.close()
+                self._current = None
+            if self._blocks is not None:
+                self._blocks.close()
+                self._blocks = None
+            self._release(self._held_cost)
+        finally:
+            # 所有句柄已释放且实际自有金额为0才清空状态；不拿借用账本总额充当关闭证明。
+            if self._current is None and self._blocks is None and self._held_cost == 0:
+                self._result = self._reducer = None
+                self._history = self._context = self._bindings = self._compiled = self._condition = None
+                self._observation = None
+                self._unknown = self._condition_unknown = self._refs = ()
+                self._closed = True

chronaxis/execution/historical_selection_rows.py

@@ -0,0 +1,300 @@
+"""从有限历史输入逐行借出真实更新的SelectionRow，保留TRUE与UNKNOWN。
+
+输入为已封存的新解码历史、保持上下文、实际绑定、值表达式、select请求和可选
+BOOL条件。只回读新历史，由原单值/联合分块者保留TTL、同刻和半开更新标志；
+每块复用独立select_reference或select_numpy，不重扫来源adapter，不物化全窗行表。
+FALSE过滤，UNKNOWN诊断行保留；原数值、BOOL、ENUM的dtype/标签/单位/质量不转换。
+observation显式限制原domain内的计算域；该域右端点及之后的真实更新和UNKNOWN行
+不再输出。None兼容原domain及预算，不证明实际观测，不改变原context、绑定或请求。
+
+资源分为七类：借用history、context、bindings及共享budget不由本owner关闭；自有
+分块者及其回读/登记归_blocks，单当前CalculationBlock归_current，选择核生成器及有限
+数组/索引归_rows；固定描述费用由_held_cost持有，核workspace归_workspace_cost，
+单当前借出行及完整定位归_row/_row_cost。核和行分配前预约费用，取消按真实账本
+更新归属，生成器close成功才丢句柄。返回行只借出至下一次next或close；外部独立
+保存行须另计预算，ResultSpool编码/写入费用也另付。不承诺旧来源缓冲或进程RSS。
+"""
+
+# 仅组合有限新历史分块与现有独立选择核，不修改完整核或结果schema。
+from dataclasses import replace
+from ..core.decoded_binding import DecodedBindings
+from ..core.expression import CompiledExpression
+from ..core.calculations import CalculationDefinition
+from ..core.calculations_memory_reference import require_calculation_plan
+from ..results.errors import ResultClosedError
+from .history import DecodedHistoryStore, _metadata_bytes
+from .hold import HoldContext
+from .calculation_blocks import HistoricalCalculationBlocks, _calculation_observation
+from .historical_conditional_blocks import HistoricalConditionalBlocks
+
+
+class HistoricalSelectionRows:
+    """拥有单当前块、有限核生成器和当前行费用，失败后只可重试关闭。
+
+    数值与筛选由所选独立核完成，strict/minimum_coverage沿原行流语义，不造伪标量。
+    exhausted为正常EOF，与显式closed不同；EOF释放回读、当前块、核与行，固定描述费用保留至close。
+    再次next仍StopIteration，不将耗尽当作显式关闭。
+    任何清理失败保留实际句柄及金额，半关闭后不再交付行，不关闭借用历史或原状态。
+    """
+
+    def __init__(self, history, context, bindings, compiled, spec, condition=None, *,
+                 backend='numpy', batch_intervals=64, observation=None):
+        """检查真实select契约，先计费固定描述，再构造自有分块者。
+
+        参数: history/context/bindings/compiled为真实新历史及原执行契约，spec为select；
+            condition为可选同绑定BOOL条件；backend为reference/numpy，batch_intervals为正区间上限。
+            observation为原domain内已核实Interval；None兼容原domain及原预算。
+        返回: 尚未消费历史的行owner。异常: 类型、能力、同步、预算、构造或取消错误；
+            持续清理失败时原异常附historical_selection_rows_cleanup_owner用于恢复close。
+        """
+        # 真实身份与联合同步在构造资源前检查，选择行不允许隐式输出单位转换。
+        if (not isinstance(history, DecodedHistoryStore) or not isinstance(context, HoldContext)
+                or not isinstance(bindings, DecodedBindings) or not isinstance(compiled, CompiledExpression)
+                or not isinstance(spec, CalculationDefinition)
+                or condition is not None and not isinstance(condition, CompiledExpression)):
+            raise TypeError('历史选择行需真实历史、上下文、绑定、表达式和CalculationDefinition')
+        if spec.operation != 'select' or spec.output_unit not in (None, compiled.root.unit):
+            raise ValueError('历史选择行需select且保留原表达式单位')
+        if (backend not in ('reference', 'numpy') or type(batch_intervals) is not int or batch_intervals < 1):
+            raise ValueError('历史选择行需合法后端与正原生int块大小')
+        if compiled.bindings.identity != bindings.identity:
+            raise ValueError('选择行表达式与实际绑定不同')
+        require_calculation_plan(compiled, spec, condition)
+        # 只验证显式范围，不创建派生context；块层按半开实际域裁剪原值更新和UNKNOWN行。
+        _calculation_observation(context, observation)
+        # 构造失败前准备可清理字段；借用引用与自有句柄明确区分，金额从0开始。
+        self._history, self._context, self._bindings = history, context, bindings
+        self._observation = observation
+        self._compiled, self._spec, self._condition, self._backend = compiled, spec, condition, backend
+        self._batch_intervals, self._budget = batch_intervals, history.budget
+        self._blocks = self._current = self._rows = self._row = None
+        self._held_cost = self._workspace_cost = self._row_cost = self._row_estimate = 0
+        self._closed = self._closing = self._failed = self._exhausted = False
+        try:
+            # 固定描述费用在自有子对象创建前预约，动态完整refs和核/行费用按当前块另计。
+            identity = None if condition is None else condition.identity
+            self._reserve(65536 + 16 * _metadata_bytes((context, bindings.sources, compiled.identity, identity, spec))
+                          + (0 if observation is None else 16 * _metadata_bytes(observation)))
+            self._blocks = self._make_blocks()
+        except BaseException as exc:
+            # 子构造未返回也可能拥有历史读取句柄，接管原异常上的真实恢复入口。
+            attr = 'calculation_blocks_cleanup_owner' if condition is None else 'conditional_blocks_cleanup_owner'
+            child = getattr(exc, attr, None)
+            if child is not None:
+                self._blocks = child
+            for attempt in range(2):
+                try:
+                    self.close()
+                    break
+                except BaseException as cleanup:
+                    exc.add_note(f'历史选择行构造清理第{attempt+1}次失败: {type(cleanup).__name__}')
+            if not self._closed:
+                exc.historical_selection_rows_cleanup_owner = self
+                exc.add_note('释放恢复后调用historical_selection_rows_cleanup_owner.close()')
+            raise
+
+    def _make_blocks(self):
+        """创建一次自有单值或联合回读者，借用资源不接管关闭。
+
+        参数: 无。返回: HistoricalCalculationBlocks或HistoricalConditionalBlocks。
+        异常: 原构造/身份/同步/预算错误，恢复句柄由父构造接管。
+        """
+        # 两输入能力已明确支持select，条件BOOL内部保持与原分块/TTL行为相同。
+        if self._condition is None:
+            return HistoricalCalculationBlocks(self._history, self._context, self._bindings,
+                self._compiled, self._spec, backend=self._backend, batch_intervals=self._batch_intervals,
+                observation=self._observation)
+        return HistoricalConditionalBlocks(self._history, self._context, self._bindings,
+            self._compiled, self._spec, self._condition, backend=self._backend, batch_intervals=self._batch_intervals,
+            observation=self._observation)
+
+    @property
+    def closed(self):
+        """读取全部自有资源关闭事实。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    @property
+    def failed(self):
+        """读取操作失败状态。参数: 无。返回: bool。异常: 无。"""
+        return self._failed
+
+    @property
+    def exhausted(self):
+        """读取正常EOF事实。参数: 无。返回: bool。异常: 无。"""
+        return self._exhausted
+
+    def __iter__(self):
+        """返回本行owner。参数: 无。返回: self。异常: 无。"""
+        return self
+
+    def _reserve(self, amount, *, slot=None):
+        """申请固定/工作区/当前行费用，并接管预约成功后取消的真实金额。
+
+        参数: amount为bytes，slot可为_workspace_cost或_row_cost；None为固定描述。
+        返回: None。异常: 预算或取消传播，未真正增加账本时不记所有权。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.reserve_ram(amount)
+        finally:
+            # 本次预约不含子操作，只按真实新增amount同时登记总额与费用所属槽位。
+            if self._budget.ram_bytes == before + amount:
+                self._held_cost += amount
+                if slot is not None:
+                    setattr(self, slot, getattr(self, slot) + amount)
+
+    def _release(self, amount, *, slot=None):
+        """抵销实际自有费用，释放前取消保留金额，释放后取消立即更新归属。
+
+        参数: amount为bytes，slot为对应工作区/行槽位或None。返回: None。
+        异常: 原释放/取消传播，恢复后close不能再次抵销已释放费用。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.release_ram(amount)
+        finally:
+            if self._budget.ram_bytes == before - amount:
+                self._held_cost -= amount
+                if slot is not None:
+                    setattr(self, slot, getattr(self, slot) - amount)
+
+    def _drop_row(self):
+        """结束当前借出行生命周期，释放取消时保留真实未抵销金额。
+
+        参数: 无。返回: None。异常: 行费用释放或取消传播，之后只允许close。
+        """
+        # 先丢自有行引用，再按实际账本释放；外部独立保留引用须由外部另行计费。
+        self._row = None
+        if self._row_cost:
+            self._release(self._row_cost, slot='_row_cost')
+
+    def _drop_current(self):
+        """先关闭核生成器再关当前块，全部成功后释放当前核workspace。
+
+        参数: 无。返回: None。异常: generator/block关闭、释放或取消传播，可重试。
+        """
+        # 生成器可能仍持有当前series和数组，close成功前不能丢句柄或归还工作区费用。
+        if self._rows is not None:
+            self._rows.close()
+            self._rows = None
+        if self._current is not None:
+            self._current.close()
+            self._current = None
+        if self._workspace_cost:
+            self._release(self._workspace_cost, slot='_workspace_cost')
+        self._row_estimate = 0
+
+    def _load_current(self):
+        """取得一个有限块，在第一次消费选择核前预约全部核及行上界元数据。
+
+        参数: 无。返回: None。异常: EOF为StopIteration；读取、预算、核构造或取消传播。
+        """
+        # 自有分块者被外部关闭/失败时明确拒绝，不能把损坏生命周期当正常EOF。
+        if self._blocks.closed or self._blocks.failed or self._blocks._closing:
+            raise ResultClosedError('选择行自有分块者已关闭、失败或正在清理')
+        self._current = next(self._blocks)
+        series = self._current.series
+        # N行数组/布尔掩码/索引和完整refs动态费用先预约；不会累计全窗行列表。
+        workspace = 65536 + 2048 * len(series.times_ns) + 16 * _metadata_bytes(series.source_refs)
+        self._reserve(workspace, slot='_workspace_cost')
+        if self._condition is not None:
+            # 联合身份沿既有内存select入口；replace只在workspace已取得后复制冻结模型。
+            identity = self._compiled.identity + ':' + self._condition.identity
+            series = replace(series, binding_identity=identity)
+        # 当前行上界含最长原值/枚举标签、单位、联合身份和完整来源，分配前按此费用预约。
+        value_metadata = max(_metadata_bytes(value) for value in series.values)
+        self._row_estimate = 4096 + 16 * (_metadata_bytes((series.source_refs, series.binding_identity, series.unit)) + value_metadata)
+        if self._backend == 'reference':
+            from ..core.calculations_reference import select_reference
+            self._rows = select_reference(series, self._spec)
+        else:
+            from ..core.calculations_numpy import select_numpy
+            self._rows = select_numpy(series, self._spec)
+
+    def _finish_exhaustion(self):
+        """正常EOF释放当前核/行/块费用，保留固定描述至explicit close。
+
+        参数: 无。返回: None。异常: 关闭/释放取消传播，失败后仅可close恢复。
+        """
+        # EOF不等于显式close，但自有当前行、生成器、当前块和分块者都不再需要。
+        self._drop_row()
+        self._drop_current()
+        if self._blocks is not None:
+            self._blocks.close()
+            self._blocks = None
+        # 原配置、identity和exhausted状态仍由owner持有，固定描述费用只在explicit close归还。
+        self._exhausted = True
+
+    def __next__(self):
+        """借出至下一次推进/close的单SelectionRow，TRUE/UNKNOWN原样交付。
+
+        参数: 无。返回: 一个SelectionRow；FALSE、非实际更新和半开右端由原核过滤。
+        异常: 正常EOF可重复StopIteration；关闭/半关闭ResultClosedError；其他操作失败后仅close。
+        """
+        if self._closed or self._closing:
+            raise ResultClosedError('历史选择行已关闭或正在清理')
+        if self._failed:
+            raise RuntimeError('失败的历史选择行只能关闭')
+        if self._exhausted:
+            raise StopIteration
+        try:
+            # 当前核可能仍持有已关闭输入的series；子owner/块失效后不得继续借出悬挂前缀行。
+            if (self._blocks is not None and (self._blocks.closed or self._blocks.failed or self._blocks._closing)
+                    or self._current is not None and (self._current.closed or self._current._closing)):
+                raise ResultClosedError('选择行自有输入已关闭、失败或正在清理')
+            # 下一次推进结束上一行借出费用；块内只留一行，不积累输出历史。
+            self._drop_row()
+            while True:
+                if self._rows is None:
+                    try:
+                        self._load_current()
+                    except StopIteration:
+                        self._finish_exhaustion()
+                        raise StopIteration
+                # 生成器第一次next会执行NumPy数组与索引；workspace和当前行费用已先取得。
+                self._reserve(self._row_estimate, slot='_row_cost')
+                try:
+                    row = next(self._rows)
+                except StopIteration:
+                    self._drop_row()
+                    self._drop_current()
+                    continue
+                self._row = row
+                return row
+        except StopIteration:
+            raise
+        except BaseException:
+            self._failed = True
+            raise
+
+    def close(self):
+        """关闭核、当前块、分块者和自有费用，借用资源保持，重复关闭安全。
+
+        参数: 无。返回: None。异常: generator/block/分块者关闭或金额释放取消可重试。
+        """
+        if self._closed:
+            return
+        # 进入清理后禁推进；句柄只在对应close成功后丢弃，不让持续取消丢失恢复入口。
+        self._closing = True
+        try:
+            # 先结束自有行引用并关闭generator；其frame/数组仍在时不释放任何核费用。
+            self._row = None
+            if self._rows is not None:
+                self._rows.close()
+                self._rows = None
+            if self._current is not None:
+                self._current.close()
+                self._current = None
+            if self._blocks is not None:
+                self._blocks.close()
+                self._blocks = None
+            # 自有句柄全关后统一抵销固定/核/当前行金额；前后取消由实际held账本恢复。
+            if self._held_cost:
+                self._release(self._held_cost)
+        finally:
+            # 自有各句柄和实际持有金额全部清零才closed，不以借用账本全局余额代替证明。
+            if self._rows is None and self._current is None and self._blocks is None and self._held_cost == 0:
+                self._workspace_cost = self._row_cost = self._row_estimate = 0
+                self._history = self._context = self._bindings = self._compiled = self._condition = None
+                self._observation = None
+                self._closed = True