chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/execution/integral_facts.py

@@ -0,0 +1,311 @@
+"""逐块累计整窗积分覆盖、质量和来源，并为保留的诊断申请预算。
+
+输入为真实观测范围、原 CalculationDefinition 和有限块 IntegralFacts；输出为冻结整窗事实。
+先检查连续性与未知覆盖，再申请候选工作空间，最后整体替换当前前缀。
+不保存面积或时间轴，不执行浮点求和、单位转换或 CalculationResult 分类。
+未知区间与完整来源可能随窗口增长；超过 ResourceBudget 明确失败，不截断诊断。
+预算采用既有保守元数据估算，不代表全进程 RSS；不读写文件或历史快照。
+budget 属于调用方。本对象关闭后不再持有 facts；调用方独立保留返回引用须另计预算。
+"""
+
+# 复用冻结事实、整数时间及预算协议，数值核仍由两个原积分项后端独立执行。
+from ..core.integral_terms import IntegralFacts
+from ..core.calculations import CalculationDefinition, calculation_unit
+from ..core.models import Interval, SourceRef
+from ..core.types import QualityFlag as Q
+from ..core.validation import require_text
+from ..results.budget import ResourceBudget
+from ..results.errors import ResultClosedError
+from .history import _metadata_bytes
+from .retained_metadata import retained_metadata_bytes, reference_workspace
+
+
+def _refs_cost(refs: tuple[SourceRef, ...]) -> int:
+    """估算完整来源实体及冻结容器，不承担JSON工作副本。
+
+    参数: refs 为调用方已经提供的冻结定位。返回: 保守 bytes。
+    异常: ResultFormatError 为既有估算协议无法处理的字段。
+    """
+    # 逐字段实体估算含实例字典/长文本；2048另覆盖每项持有和局部状态余量。
+    try:
+        return retained_metadata_bytes(refs) + 2048 * len(refs)
+    finally:
+        # 费用估算中取消也不让本层参数在TB持有完整定位tuple。
+        refs = None
+
+
+def _unique_refs(existing, incoming):
+    """按完整类型和值保留第一次出现的定位，保持原出现顺序。
+
+    参数: existing/incoming 为已校验来源 tuple。返回: 去重后的 tuple。
+    异常: MemoryError 为预算已申请后的实际分配失败。
+    """
+    # 无未计费的全量哈希表；此函数只在调用方已申请候选预算后执行。
+    result = None
+    try:
+        result = list(existing)
+        for ref in incoming:
+            # 显式短路和原any相同；不留下会在异步取消时保全list的生成器帧。
+            duplicate = False
+            for old in result:
+                if type(ref) is type(old) and ref == old:
+                    duplicate = True
+                    break
+            if not duplicate:
+                result.append(ref)
+        return tuple(result)
+    finally:
+        # 原异常TB可能由调用者保留；不把本层新list钉在已抵费的栈帧里。
+        result = existing = incoming = ref = old = None
+
+
+def _join_unknown(existing, incoming):
+    """合并连续块边界处及块内相邻的未知范围，不填补有效区间。
+
+    参数: 两个 tuple 均为有序、不重叠的正区间。返回: 紧凑区间 tuple。
+    异常: MemoryError 为已申请工作空间内的实际分配失败。
+    """
+    # 旧范围保持顺序；仅当前末段可能和新段相邻，不能跨有效间隔合并。
+    result = None
+    try:
+        result = list(existing)
+        for interval in incoming:
+            if result and result[-1].end_ns == interval.start_ns:
+                result[-1] = Interval(result[-1].start_ns, interval.end_ns)
+            else:
+                result.append(interval)
+        return tuple(result)
+    finally:
+        # 未知范围的新list/边界Interval同样不得在失败TB中逃逸费用寿命。
+        result = existing = incoming = interval = None
+
+
+class IntegralFactsAccumulator:
+    """持有一个已接收的连续前缀，完整结束后才开放整窗事实。
+
+    构造时固定目标交集；不会从前缀猜测 EOF。失败只允许关闭，完成后拒绝追加。
+    所有保留状态及候选容器均先 reserve；预算单线程协议下取消前后精确记账。
+    close 释放成功后即结束，即使该次调用随后被取消；释放前取消则可重试。
+    """
+
+    def __init__(self, budget: ResourceBudget, spec: CalculationDefinition,
+                 observation: Interval, input_unit: str, binding_identity: str,
+                 source_refs: tuple[SourceRef, ...] = ()):
+        """固定真实观测交集并申请初始状态预算。
+
+        参数: budget 为借用账本；spec 为原积分请求；observation 为真实观测范围；
+        input_unit/identity 为原表达式事实；source_refs 为已知完整定位。
+        返回: 新 owner。异常: TypeError/ValueError 为协议错误；预算/分配/取消原样传播。
+        清理仍失败时，原异常.integral_facts_cleanup_owner 提供可重试 close 的 owner。
+        """
+        # 在申请前拒绝非法输入，不把任意对象或缺失观测伪装成空窗口。
+        if not isinstance(budget, ResourceBudget) or not isinstance(spec, CalculationDefinition) or spec.operation != 'integral':
+            raise TypeError('需要ResourceBudget和integral CalculationDefinition')
+        if not isinstance(observation, Interval):
+            raise TypeError('观测范围需要真实Interval')
+        require_text(input_unit, 'integral.input_unit')
+        require_text(binding_identity, 'integral.binding_identity')
+        if type(source_refs) is not tuple or any(not isinstance(ref, SourceRef) for ref in source_refs):
+            raise TypeError('完整来源需要SourceRef tuple')
+        calculation_unit(spec, input_unit)  # 仅校验输出单位兼容性，此处没有数值转换。
+        # 沿用积分项的闭合观测交集表示；相接端点保留点事实，不等同于无交集。
+        left, right = max(spec.window.start_ns, observation.start_ns), min(spec.window.end_ns, observation.end_ns)
+        actual = Interval(left, right) if left <= right else None
+        # owner 账本在第一次 reserve 前建立，取消后仍能在构造清理中准确释放。
+        self._budget, self._spec, self._actual = budget, spec, actual
+        self._unit, self._identity = input_unit, binding_identity
+        self._held_cost, self._state = 0, None
+        self._closed = self._closing = self._failed = self._finished = False
+        self._base_cost = 65536 + 16 * _metadata_bytes((spec, observation, input_unit, binding_identity))
+        try:
+            # 来源去重容器、冻结状态及旧输入引用均由这次保守申请覆盖。
+            self._reserve(self._base_cost + _refs_cost(source_refs)
+                          + reference_workspace(0, len(source_refs)))
+            refs = _unique_refs((), source_refs)
+            self._state = IntegralFacts(spec, None, 0, 0, (), Q.NONE, input_unit, binding_identity, refs)
+            self._release(self._held_cost - self._base_cost - _refs_cost(refs))
+        except BaseException as exc:
+            # 构造不会正常交付 owner；清理异常不能覆盖原失败或丢掉重试入口。
+            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.integral_facts_cleanup_owner = self
+                            exc.add_note('释放恢复后调用integral_facts_cleanup_owner.close()')
+            raise
+        finally:
+            # 构造已交给_state或真实恢复owner；本层临时tuple不由异常栈继续持有。
+            refs = None
+
+    @property
+    def closed(self):
+        """提供关闭状态。参数: 无。返回: bool。异常: 无。"""
+        # 是否结束以实际释放结果为准，不能仅凭进入 close 判定。
+        return self._closed
+
+    @property
+    def failed(self):
+        """提供失败状态。参数: 无。返回: bool。异常: 无。"""
+        # 推进失败后保留资源供清理，此标志不表示已经关闭。
+        return self._failed
+
+    @property
+    def facts(self) -> IntegralFacts:
+        """在完整 finish 后借用冻结整窗事实，不额外复制诊断。
+
+        参数: 无。返回: 原 spec 与完整覆盖/来源事实。异常: 关闭、失败或未完成时拒绝。
+        副作用: 返回引用只由本 owner 计费至 close；独立留存由调用方承担。
+        """
+        # 未完成前缀不能冒充整窗事实，关闭过程中也禁止借出状态。
+        self._require_open()
+        if self._failed or not self._finished:
+            raise RuntimeError('整窗事实尚未成功完成')
+        return self._state
+
+    def _require_open(self):
+        """拒绝关闭及正在清理时读取或推进。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed or self._closing:
+            raise ResultClosedError('积分事实owner已关闭或正在清理')
+
+    def _reserve(self, amount):
+        """申请前后按真实账本增量登记，覆盖成功后取消。
+
+        参数: amount 为非负 bytes。返回: None。异常: 原预算或取消异常。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.reserve_ram(amount)
+        finally:
+            # ResourceBudget 单线程契约下，只有成功申请才改变账本。
+            if self._budget.ram_bytes == before + amount:
+                self._held_cost += amount
+
+    def _release(self, amount):
+        """释放前后按真实账本减少持有量，取消后不会再次扣同一笔。
+
+        参数: amount 为 owner 当前持有部分。返回: None。异常: 原释放或取消异常。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.release_ram(amount)
+        finally:
+            # 释放后取消也已归还；释放前取消仍保留全部持有量，等待 close 重试。
+            if self._budget.ram_bytes == before - amount:
+                self._held_cost -= amount
+
+    def _validate_block(self, facts):
+        """检查当前块接在已接收前缀之后，覆盖事实完整且身份一致。
+
+        参数: facts 为有限块事实。返回: None。异常: TypeError/ValueError 为协议错误。
+        """
+        # 原请求、单位和绑定身份一致才能连接；不做隐式换单位或重绑定。
+        if not isinstance(facts, IntegralFacts):
+            raise TypeError('需要IntegralFacts')
+        if facts.spec != self._spec or facts.input_unit != self._unit or facts.binding_identity != self._identity:
+            raise ValueError('积分块请求、单位或绑定身份不一致')
+        # 固定最终目标；None 不接受人为块，点窗口只允许一次真实点事实。
+        block, target = facts.actual_window, self._actual
+        if block is None or target is None:
+            raise ValueError('没有实际目标或块观测')
+        previous = self._state.actual_window
+        cursor = target.start_ns if previous is None else previous.end_ns
+        if block.start_ns != cursor or block.end_ns > target.end_ns:
+            raise ValueError('积分块有缺口、重叠或超出目标')
+        if target.start_ns == target.end_ns:
+            if previous is not None or block != target:
+                raise ValueError('零窗口仅接收一个真实点块')
+        elif block.start_ns >= block.end_ns:
+            raise ValueError('正窗口不接受不推进的块')
+        # 有序且不重叠是必要条件，不能仅靠总时长相等掩盖重复未知诊断。
+        last_end, unknown_duration = block.start_ns, 0
+        for interval in facts.value_unknown_ranges:
+            if interval.start_ns < last_end:
+                raise ValueError('未知范围必须有序且不重叠')
+            last_end = interval.end_ns
+            unknown_duration += interval.end_ns - interval.start_ns
+        duration = block.end_ns - block.start_ns
+        if unknown_duration + facts.value_valid_duration_ns != duration:
+            raise ValueError('有效与未知时长未完整划分当前块')
+        if facts.valid_sample_count > duration:
+            raise ValueError('半开整数纳秒窗口的样本数超过可用时间点')
+
+    def push(self, facts: IntegralFacts) -> None:
+        """顺序累计一块覆盖事实，面积仍留在调用方的有限块内消费。
+
+        参数: facts 为连续块的真实 IntegralFacts。返回: None。
+        异常: 协议、预算、分配或取消错误；此后只允许 close。
+        """
+        # 检查生命周期后才推进，拒绝在失败前缀或已交付整窗结果上追加。
+        self._require_open()
+        if self._failed or self._finished:
+            raise RuntimeError('失败或完成的积分事实owner不能追加')
+        old = unknown = refs = candidate = window = None
+        try:
+            self._validate_block(facts)
+            old = self._state
+            # 旧refs实体已由前缀持有；候选只复制指针，不能再按旧完整payload深计。
+            old_dynamic = 4096 * len(old.value_unknown_ranges)
+            incoming = 4096 * len(facts.value_unknown_ranges) + _refs_cost(facts.source_refs)
+            self._reserve(65536 + old_dynamic + incoming
+                          + reference_workspace(len(old.source_refs), len(facts.source_refs)))
+            unknown = _join_unknown(old.value_unknown_ranges, facts.value_unknown_ranges)
+            refs = _unique_refs(old.source_refs, facts.source_refs)
+            window = Interval(self._actual.start_ns, facts.actual_window.end_ns)
+            candidate = IntegralFacts(self._spec, window,
+                old.value_valid_duration_ns + facts.value_valid_duration_ns,
+                old.valid_sample_count + facts.valid_sample_count, unknown,
+                old.quality | facts.quality, self._unit, self._identity, refs)
+            # 单个冻结状态原子安装；异常前的前缀不会被零散字段部分更新。
+            self._state = candidate
+            retained = self._base_cost + 4096 * len(unknown) + _refs_cost(refs)
+            # 旧状态与临时容器停止持有后，归还保守候选余额。
+            old = candidate = None
+            self._release(self._held_cost - retained)
+        except BaseException as exc:
+            # 保留当前可追踪状态及已申请金额，不在异常路径悄悄丢失资源句柄。
+            self._failed = True
+            exc.integral_facts_cleanup_owner = self
+            raise
+        finally:
+            # 费用释放/候选构造失败时，原TB也不得留下本层旧快照或新候选容器。
+            old = unknown = refs = candidate = window = facts = None
+
+    def finish(self) -> None:
+        """确认真实目标全部覆盖；无交集可直接完成，点窗口必须收到点事实。
+
+        参数: 无。返回: None；成功后 facts 可读，重复 finish 无副作用。
+        异常: RuntimeError 为失败状态；ValueError 为观测前缀不足。
+        """
+        self._require_open()
+        if self._failed:
+            raise RuntimeError('失败owner只能关闭')
+        # 不把当前最后一块当 EOF；原始真实交集在构造时已经固定。
+        if self._actual is not None and self._state.actual_window != self._actual:
+            self._failed = True
+            raise ValueError('尚未覆盖完整实际窗口')
+        self._finished = True
+
+    def close(self) -> None:
+        """归还本 owner 的 RAM；释放前取消可重试，不关闭借用账本。
+
+        参数: 无。返回: None；重复关闭不再扣账。
+        异常: 原释放/取消错误，是否已关闭以实际账本释放结果为准。
+        """
+        if self._closed:
+            return
+        self._closing = True
+        try:
+            self._release(self._held_cost)
+        finally:
+            # 成功释放或成功后取消均清除引用；失败前取消仍保留状态供重试。
+            if self._held_cost == 0:
+                self._state = self._spec = self._actual = None
+                self._unit = self._identity = None
+                self._closed = True

chronaxis/execution/integral_reduction.py

@@ -0,0 +1,216 @@
+"""为逐块积分数值归约和整窗事实提供预算、生命周期及故障清理。
+
+输入为真实观测、原请求及同一后端的有限面积块，结束后借出数值与覆盖事实。
+数值核保留有界误差项，事实 owner 保留诊断和完整来源；不保存全部面积或时间轴。
+所有状态和候选数组先申请保守 RAM 预算，超限或取消后只允许关闭。
+budget 为借用的单线程账本，本 owner 不关闭它；估算不代表全进程 RSS。
+不执行文件 I/O、历史读写/解码或最终 CalculationResult 的覆盖状态分类。
+"""
+
+# 两核独立，仅在运行 owner 中选择；冻结协议和事实预算允许共享。
+from ..core.integral_sum import IntegralSumResult, require_partial_limit
+from ..core.integral_sum_reference import ReferenceIntegralSum
+from ..core.integral_sum_numpy import NumpyIntegralSum
+from ..core.integral_terms import ReferenceIntegralTerms, IntegralFacts
+from ..core.integral_terms_numpy import NumpyIntegralTerms
+from ..core.calculations import CalculationDefinition, calculation_unit
+from ..core.models import Interval, SourceRef
+from ..results.budget import ResourceBudget
+from ..results.errors import ResultClosedError
+from .integral_facts import IntegralFactsAccumulator
+
+
+class IntegralReduction:
+    """持有一个积分归约 owner，完成前不开放整窗结果。
+
+    纯核的非有限累计是数值结果故障，仍消费后续事实；协议/容量/预算异常使 owner 失败。
+    关闭途中禁止借出引用，释放前取消可重试，释放后取消不会重复扣账。
+    借出的结果和事实由本 owner 计费到 close，调用方另行留存须承担预算。
+    """
+
+    def __init__(self, budget: ResourceBudget, spec: CalculationDefinition, observation: Interval,
+                 input_unit: str, binding_identity: str, source_refs: tuple[SourceRef, ...] = (),
+                 backend: str = 'numpy', partial_limit: int = 4096):
+        """先申请数值工作空间，再创建独立核和事实 owner。
+
+        参数: budget 为借用账本；spec/observation 为原请求及真实范围；
+        input_unit/identity/refs 保留表达式身份；backend 为 reference/numpy；partial_limit 为误差容量。
+        返回: None，初始化新 owner。异常: 配置、预算、分配、取消原样传播。
+        持续清理失败时原异常.integral_reduction_cleanup_owner 可用于重试 close。
+        """
+        # 配置验证不分配面积数组；事实详细门槛由子 owner 原样实施。
+        if not isinstance(budget, ResourceBudget) or not isinstance(spec, CalculationDefinition) or spec.operation != 'integral':
+            raise TypeError('积分归约需要ResourceBudget和integral CalculationDefinition')
+        if type(backend) is not str or backend not in ('reference', 'numpy'):
+            raise ValueError('积分归约后端需要reference或numpy')
+        limit = require_partial_limit(partial_limit)
+        unit, factor = calculation_unit(spec, input_unit)
+        # 句柄与计费状态先建立，构造中取消也有可恢复清理入口。
+        self._budget, self._backend = budget, backend
+        self._unit, self._factor = unit, factor
+        self._held_cost = 0
+        self._kernel = self._facts_owner = self._result = None
+        self._failed = self._finished = self._closing = self._closed = False
+        self._numeric_cost = 65536 + 512 * limit
+        try:
+            # 512 bytes/项覆盖旧/候选误差列、参考 float 对象和数组拆分临时列。
+            self._reserve(self._numeric_cost)
+            kernel = ReferenceIntegralSum if backend == 'reference' else NumpyIntegralSum
+            self._kernel = kernel(limit)
+            self._facts_owner = IntegralFactsAccumulator(budget, spec, observation, input_unit,
+                                                       binding_identity, source_refs)
+        except BaseException as exc:
+            # 子构造清理持续失败时接管其句柄，不让嵌套 owner 的资源变成不可达。
+            child = getattr(exc, 'integral_facts_cleanup_owner', None)
+            if child is not None:
+                self._facts_owner = 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.integral_reduction_cleanup_owner = self
+                            exc.add_note('释放恢复后调用integral_reduction_cleanup_owner.close()')
+            raise
+
+    @property
+    def closed(self) -> bool:
+        """读取实际关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed  # 以两个 owner 实际归还预算为准。
+
+    @property
+    def failed(self) -> bool:
+        """读取推进异常状态。参数: 无。返回: bool。异常: 无。"""
+        return self._failed  # 与正常交付的数值失败结果不同。
+
+    @property
+    def result(self) -> IntegralSumResult:
+        """借出完成后的数值结果，不能将前缀当成整窗面积。
+
+        参数: 无。返回: 冻结结果。异常: 关闭、失败或未完成时拒绝。
+        """
+        self._require_finished()  # 借出引用由本 owner 计费到 close。
+        return self._result
+
+    @property
+    def facts(self) -> IntegralFacts:
+        """借出完成后的整窗覆盖、质量及完整来源。
+
+        参数: 无。返回: 冻结事实。异常: 关闭、失败或未完成时拒绝。
+        """
+        self._require_finished()  # 子 owner 同时验证完整真实交集。
+        return self._facts_owner.facts
+
+    def _require_open(self) -> None:
+        """拒绝关闭及清理中操作。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed or self._closing:
+            raise ResultClosedError('积分归约owner已关闭或正在清理')
+
+    def _require_finished(self) -> None:
+        """验证借出整窗结果的门槛。参数: 无。返回: None。异常: 生命周期错误。"""
+        self._require_open()
+        if self._failed or not self._finished:
+            raise RuntimeError('整窗积分归约尚未成功完成')
+
+    def _reserve(self, amount: int) -> None:
+        """按真实预算增量登记申请，覆盖成功后取消。
+
+        参数: amount 为 bytes。返回: None。异常: 原申请或取消错误。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.reserve_ram(amount)
+        finally:
+            # 单线程借用账本下，成功申请后的取消也须由本 owner 持有并归还。
+            if self._budget.ram_bytes == before + amount:
+                self._held_cost += amount
+
+    def _release(self, amount: int) -> None:
+        """按真实预算减少持有量，覆盖成功后取消。
+
+        参数: amount 为 bytes。返回: None。异常: 原释放或取消错误。
+        """
+        before = self._budget.ram_bytes
+        try:
+            self._budget.release_ram(amount)
+        finally:
+            # 成功后取消不再重复扣账，释放前取消则保留金额供 close 重试。
+            if self._budget.ram_bytes == before - amount:
+                self._held_cost -= amount
+
+    def push(self, terms: ReferenceIntegralTerms | NumpyIntegralTerms) -> None:
+        """即时消费有限面积块及事实，不保留调用方输入数组。
+
+        参数: terms 必须与构造后端一致。返回: None。
+        异常: 协议、容量、预算、分配或取消错误；此后只允许 close。
+        """
+        try:
+            self._require_open()
+            if self._failed or self._finished:
+                raise RuntimeError('失败或完成的积分归约不能追加')
+            try:
+                # 输入归调用方块 workspace；先计费有效索引/候选列，再执行任何数值核。
+                expected = ReferenceIntegralTerms if self._backend == 'reference' else NumpyIntegralTerms
+                if not isinstance(terms, expected):
+                    raise TypeError('积分面积模型与归约后端不一致')
+                workspace = 4096 + 64 * len(terms.areas)
+                self._reserve(workspace)
+                self._facts_owner.push(terms.facts)
+                self._kernel.push(terms)
+                # 输入没有被持有，有限块临时列可归还；固定误差空间留到关闭。
+                self._release(workspace)
+            except BaseException:
+                self._failed = True  # 已推进的前缀不再借出，不假装撤销成功。
+                raise
+        finally:
+            # 原异常及TB仍交调用方；只断本层借入参数、视图和临时，不清外部帧。
+            self = terms = None
+
+    def finish(self) -> None:
+        """核对整窗事实后归约并应用一次输出单位因子。
+
+        参数: 无。返回: None，重复成功完成无副作用。
+        异常: 未覆盖真实目标、预算/分配/取消错误；失败后只允许 close。
+        """
+        self._require_open()
+        if self._failed:
+            raise RuntimeError('失败的积分归约只能关闭')
+        if self._finished:
+            return
+        try:
+            # 不能从最后一个已见块猜 EOF，数值结果也不能先于覆盖门槛交付。
+            self._facts_owner.finish()
+            result = self._kernel.finish(self._unit, self._factor)
+            self._result = result
+            self._finished = True
+        except BaseException:
+            self._failed = True
+            raise
+
+    def close(self) -> None:
+        """关闭自有事实与数值状态，保留调用方已有预算。
+
+        参数: 无。返回: None，重复成功关闭无副作用。
+        异常: 原释放/取消错误；释放前取消保留句柄和金额供再次 close。
+        """
+        if self._closed:
+            return
+        self._closing = True
+        try:
+            # 子 owner 自行处理释放前后取消；父 owner 不能把子金额当成自己的释放。
+            if self._facts_owner is not None:
+                self._facts_owner.close()
+            self._release(self._held_cost)
+        finally:
+            # 父释放后取消也可结束；子释放后取消时父金额仍在，需再次 close 收尾。
+            child_closed = self._facts_owner is None or self._facts_owner.closed
+            if child_closed and self._held_cost == 0:
+                self._kernel = self._facts_owner = self._result = None
+                self._unit = self._factor = None
+                self._closed = True

chronaxis/execution/legacy_frame_samples.py

@@ -0,0 +1,94 @@
+"""把同次BLF原帧仓与稀疏解码仓按原序连接，供新增报文重建使用。
+
+不重新扫描BLF、不重新解码；新DBC上下文只提供编码布局和复用选择器。
+原帧与解码记录的序号、时间和公开帧字段逐项相符，结束时两仓均完整核验。
+"""
+
+from ..results.frame_exports import as_export_frame
+from ..results.frame_rebuild import FrameSample
+from ..results.budget import _reserve_owned_ram,_release_owned_ram,_cleanup_owner
+from ..results.errors import ResultClosedError,ResultFormatError
+
+
+class LegacyFrameSamples:
+    """最多保留一条原帧与一条解码记录，拥有两游标而借用原仓和DBC。"""
+
+    def __init__(self,raw_store,message_store,context,budget,*,read_identity,session_id,channel,trace=True):
+        """核同次仓身份后开有限游标。参数: 原帧/解码仓/DBC上下文/预算、原scan的read身份/会话/声明通道。返回: owner。异常: 合同/IO错。
+        """
+        self._budget=budget; self.context=context; self._held_cost=self._fixed_cost=0
+        self.channel=channel;self.trace=trace
+        self.raw=self.messages=self.pending=None; self._closed=False; self._ended=False
+        try:
+            context.require_open()
+            if raw_store._budget is not budget or raw_store.state!='sealed':
+                raise ValueError('重建需要同预算已封口原帧仓')
+            if message_store is not None and (message_store._budget is not budget or message_store.state!='sealed'
+                    or message_store.source_name!=raw_store.source_name or message_store.session_id!=session_id
+                    or message_store.read_identity!=read_identity):
+                raise ValueError('原帧与解码仓不是同次读取')
+            _reserve_owned_ram(self,262144,'_fixed_cost')
+            self.raw=raw_store.iter_frames()
+            if message_store is not None:
+                self.messages=message_store.iter_records(); self.pending=next(self.messages,None)
+        except BaseException as error:
+            _cleanup_owner(self,error,'legacy_frame_samples_cleanup_owner','原帧解码连接构造'); raise
+
+    @property
+    def closed(self):
+        """返回真实关闭状态。参数: 无。返回: bool。异常: 无。
+        """
+        return self._closed
+
+    def __iter__(self):
+        """返回独立游标。参数: 无。返回: self。异常: 无。
+        """
+        return self
+
+    def __next__(self):
+        """连接同原序记录，不跳过完整仓核验。参数: 无。返回: FrameSample。异常: EOF/来源不符/IO错。
+        """
+        if self._closed or self._ended:
+            raise StopIteration
+        self.context.require_open()
+        try:
+            raw=next(self.raw)
+        except StopIteration:
+            if self.pending is not None or not self.raw.verified_eof or self.messages is not None and not self.messages.verified_eof:
+                raise ResultFormatError('原帧和解码仓没有共同完整结束')
+            self._ended=True; raise
+        decoded=None
+        if self.pending is not None:
+            item=self.pending
+            if item.decoded.sequence<raw.sequence:
+                raise ResultFormatError('解码仓出现无对应原帧记录')
+            if item.decoded.sequence==raw.sequence:
+                if item.time_ns!=raw.time_ns or item.decoded.frame!=raw.frame:
+                    raise ResultFormatError('重建原帧与解码记录内容不符')
+                decoded=item.decoded; self.pending=next(self.messages,None)
+        # 与同次读取使用相同候选选择，不把标准与扩展帧的同数值ID混为一条。
+        message=self.context.observe(raw.frame)
+        known=raw.frame.channel==self.channel and self.context.is_known_frame(raw.frame)
+        values=(); layout=(); valid=True
+        rule=next((rule for rule in self.context.rules if rule.matches(raw.frame)),None)
+        if rule is not None and not raw.frame.is_error_frame and not raw.frame.is_remote_frame:
+            if decoded is None or message is None:
+                raise ResultFormatError('已请求重建报文缺同次解码记录')
+            values=tuple((name,decoded.values.get(name)) for name in rule.continuous)
+            selectors=tuple(signal for signal in message.signals if signal.is_multiplexer)
+            # 未激活分支的复用选择器可以缺席；实际布局只包含本次解码已有的选择器。
+            layout=tuple((signal.name,int(signal.conversion.numeric_scaled_to_raw(decoded.values[signal.name])))
+                for signal in selectors if signal.name in decoded.values)
+        return FrameSample(as_export_frame(raw,compact=not self.trace),values,layout,known,valid)
+
+    def close(self):
+        """关闭真实两个游标后释放自己的费用。参数: 无。返回: None。异常: 原close错可重试。
+        """
+        if self._closed:
+            return
+        for slot in ('raw','messages'):
+            owner=getattr(self,slot)
+            if owner is not None:
+                owner.close(); setattr(self,slot,None)
+        self.pending=self.context=None
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost'); self._closed=True