chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/execution/record_time_calculation.py

@@ -0,0 +1,322 @@
+"""用有限记录计算时间统计和真实样本统计；仅时间均值暂存必要值/权重。
+
+输入与RecordIntegral共享点缓冲、递增时间和失效处理。复用原时间/样本数值核；
+样本统计保真实更新标志，不把条件/TTL更新当新样本，样本均值使用原序求和。
+均值首遍仅写值与权重，实际权重为int64纳秒，周期权重为float秒；
+次遍按已知总权重规范化，避免先求面积溢出。
+临时文件由本owner关闭时删除，不默认留现场；结果不附历史、贡献或时间对照。
+调用者必须先确认来源EOF及关闭成功再finish，本对象不替代公共AnalysisRunner发布。
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from struct import Struct
+from tempfile import TemporaryFile
+
+import numpy as np
+
+from ..core.calculations import CalculationDefinition, CalculationSeries, classify_calculation_value
+from ..core.calculations import classify_coverage
+from ..core.models import Interval
+from ..core.types import SignalDType as D, QualityFlag as Q
+from ..core.time_reduction import require_time_config, TimeReductionResult
+from ..core.time_reduction_reference import ReferenceTimeReduction
+from ..core.time_reduction_numpy import NumpyTimeReduction
+from ..core.conditional_time_reduction_reference import ReferenceConditionalTimeReduction
+from ..core.conditional_time_reduction_numpy import NumpyConditionalTimeReduction
+from ..core.integral_sum_reference import ReferenceIntegralSum
+from ..core.integral_sum_numpy import NumpyIntegralSum
+from ..core.mean_weights_reference import normalized_mean_terms as reference_mean
+from ..core.mean_weights_numpy import normalized_mean_terms as numpy_mean
+from ..results.budget import ResourceBudget, _reserve_owned_ram, _release_owned_ram, _cleanup_owner
+from ..results.errors import BudgetExceededError
+from .history import _metadata_bytes
+from .record_point_buffer import RecordPointBuffer
+from ..core.sample_reduction import require_sample_config
+from ..core.sample_reduction_reference import ReferenceSampleReduction
+from ..core.sample_reduction_numpy import NumpySampleReduction
+from .record_sample_series import sample_series
+
+
+@dataclass(frozen=True)
+class RecordTimeResult:
+    """保存时间统计的必要输出，整数极值不转成浮点数。"""
+
+    value: int | float | None
+    unit: str
+    status: str
+    reason: str
+    quality: Q
+    coverage_status: str | None = None
+
+
+class RecordTimeCalculation(RecordPointBuffer):
+    """拥有一份点缓冲、数值状态及可选均值临时文件，失败后只能清理。"""
+
+    def __init__(self, budget, spec, input_unit, dtype, step_ns, *, backend='numpy',
+                 batch_intervals=64, partial_limit=4096, conditioned=False, work_dir=None):
+        """预付有限状态，均值的文件延迟到首批有效项才创建。
+
+        参数: 共享budget、时间统计spec、已求值类型/单位；step_ns为None实际差或正周期；
+            后端和批上限明确；
+            conditioned表示外BOOL条件，time_weighted_mean需要既存work_dir。
+        返回: 新owner。异常: 配置/预算失败；持续清理故障附record_time_cleanup_owner。
+        """
+        if not isinstance(budget, ResourceBudget) or not isinstance(spec, CalculationDefinition):
+            raise TypeError('记录时间统计需要共享预算和CalculationDefinition')
+        if backend not in ('reference', 'numpy') or type(conditioned) is not bool:
+            raise ValueError('时间统计需要明确后端及bool条件开关')
+        if type(batch_intervals) is not int or not 1 <= batch_intervals <= 4096:
+            raise ValueError('记录批上限需要1到4096')
+        self._samples=spec.operation in ('sample_minimum','sample_maximum','sample_mean')
+        if self._samples:
+            if step_ns is not None:raise ValueError('样本统计不使用固定或DBC周期')
+            self._unit,self._factor=require_sample_config(spec,input_unit,dtype,partial_limit)
+        else:
+            self._unit, self._factor = require_time_config(spec, input_unit, dtype, None, partial_limit, step_ns=step_ns)
+        self._work_dir = None
+        if spec.operation == 'time_weighted_mean':
+            if work_dir is None or not Path(work_dir).is_dir():
+                raise ValueError('均值需要已存在的专用工作目录')
+            self._work_dir = Path(work_dir)
+        self._budget, self._spec, self._input_unit, self._dtype = budget, spec, input_unit, dtype
+        self._step_ns, self._limit, self._conditioned = step_ns, batch_intervals, conditioned
+        self._backend, self._partial_limit = backend, partial_limit
+        self._held_cost = self._fixed_cost = self._workspace_cost = 0
+        self._closed = self._closing = self._failed = self._finished = False
+        self._rows = self._reduction = self._result = self._file = self._mean_sum = None
+        self._last_time = None
+        self._covered_ns = self._known_ns = self._selected_ns = self._selected_unknown_ns = self._false_ns = 0
+        self._quality = Q.NONE
+        self._coverage_value_ns=0 if spec.minimum_coverage>0 else None
+        self._record_count = 0
+        self._codec = Struct('>dq' if step_ns is None else '>dd')  # 仅值/权重，实际纳秒不降为浮点。
+        try:
+            _reserve_owned_ram(self, 65536 + partial_limit * 512 + (batch_intervals+1)*1024
+                + 16*_metadata_bytes((spec, input_unit)), '_fixed_cost')
+            self._rows = []
+            kernel = ((ReferenceConditionalTimeReduction if backend == 'reference' else NumpyConditionalTimeReduction)
+                      if conditioned else (ReferenceTimeReduction if backend == 'reference' else NumpyTimeReduction))
+            self._reduction = ((ReferenceSampleReduction if backend=='reference' else NumpySampleReduction)
+                (spec,input_unit,dtype,partial_limit=partial_limit) if self._samples else
+                kernel(spec, input_unit, dtype, step_ns=step_ns, partial_limit=partial_limit))
+        except BaseException as exc:
+            _cleanup_owner(self, exc, 'record_time_cleanup_owner', '记录时间统计')
+            raise
+
+    def _append_mean(self, values, weights):
+        """只写本批选中的必要均值项；费用先预约，不缓存完整输入。
+
+        参数: 已由核校验的有限数值/权重。返回: None。异常: 配额、短写、IO或取消传播。
+        """
+        if len(values) == 0:
+            return
+        if self._file is None:
+            self._file = TemporaryFile(mode='w+b', buffering=0, dir=self._work_dir, prefix='mean-')
+        payload = bytearray(len(values)*self._codec.size)
+        view = None
+        try:
+            for index, (value, weight) in enumerate(zip(values, weights)):
+                self._codec.pack_into(payload, index*self._codec.size, float(value),
+                    int(weight) if self._step_ns is None else float(weight))
+            self._budget.reserve_spool(len(payload))
+            view = memoryview(payload)
+            position = 0
+            while position < len(view):
+                written = self._file.write(view[position:])
+                if type(written) is not int or not 0 < written <= len(view)-position:
+                    raise OSError('均值暂存短写或无写入进展')
+                position += written
+            self._record_count += len(values)
+        finally:
+            if view is not None:
+                view.release()
+            values = weights = payload = view = None
+
+    def _flush(self):
+        """在共享预算内分块处理样本统计，保留每块的共同右端。
+
+        参数: 无，使用已预付的点缓冲。返回: None。
+        异常: 最小两点工作区也放不下时报告计算项与用途；数值、取消原错传播。
+        不降低每行估算、不放宽限额，也不丢弃、重排或重复累计真实样本。
+        """
+        if not self._samples:
+            return self._flush_block()
+        remaining = None
+        try:
+            while len(self._rows) >= 2:
+                # 读取队列和其他指标仍存活，不能假定本指标可独占整个预算。
+                # 系数沿用原样本核对最多两个TTL插入点的保守预付。
+                available = self._budget.memory_budget_bytes - self._budget.ram_bytes
+                count = min(len(self._rows), (available - 65536) // 36864)
+                if count < 2:
+                    raise BudgetExceededError(
+                        f'计算项 {self._spec.calculation_id}（{self._spec.operation}）'
+                        f'样本统计工作区不足：最小两点需要139264字节，当前可用{available}字节；'
+                        '已尝试按可用预算分块，请减少同时运行的计算项或读取批量，'
+                        '核实必要状态后再调整memory_budget_bytes')
+                if count == len(self._rows):
+                    self._flush_block()
+                    break
+                # 两份短列表的引用槽由既有点缓冲1024字节/行覆盖；不复制值对象。
+                # 右端在前块半开范围内不计样本，下一块再作为左端处理一次。
+                remaining = self._rows[count - 1:]
+                self._rows = self._rows[:count]
+                self._flush_block()
+                self._rows, remaining = remaining, None
+        finally:
+            # 中途失败不能持有已退款缓冲以外的尾部引用；外层负责标失败并关闭。
+            remaining = None
+
+    def _flush_block(self):
+        """计算完整记录对，只留共享右端；均值写选中项，其他指标不写盘。
+
+        参数: 无。返回: None。异常: 预算/数值结构/IO/取消，失败后不得交付前缀。
+        """
+        if len(self._rows) < 2:
+            return
+        series = block = facts = None
+        primary = None
+        try:
+            _reserve_owned_ram(self, 65536 + len(self._rows)*(36864 if self._samples else 12288), '_workspace_cost')
+            times = tuple(row[0] for row in self._rows)
+            values = tuple(row[1] for row in self._rows)
+            deadlines = tuple(row[2] for row in self._rows) if any(row[2] is not None for row in self._rows) else None
+            conditions = tuple(row[3] for row in self._rows) if self._conditioned else None
+            options = {'condition_valid_until_ns': tuple(row[4] for row in self._rows)} if self._conditioned else {}
+            series = (sample_series(self._rows,self._input_unit,self._conditioned) if self._samples else
+                CalculationSeries(Interval(times[0], times[-1]), times, values, (True,)*len(times), self._input_unit, conditions=conditions))
+            mean = self._spec.operation == 'time_weighted_mean'
+            block = (self._reduction.push(series) if self._samples else
+                self._reduction.push(series, valid_until_ns=deadlines,
+                    retain_unknown_ranges=False, retain_mean_terms=mean, **options))
+            facts = block.facts if mean else block
+            if self._coverage_value_ns is not None:
+                self._coverage_value_ns+=facts.value_valid_duration_ns
+            if mean:
+                self._append_mean(block.values, block.weights)
+            span = 0 if facts.actual_window is None else facts.actual_window.end_ns-facts.actual_window.start_ns
+            self._covered_ns += span
+            self._known_ns += facts.condition_known_duration_ns if self._conditioned else span
+            self._selected_ns += facts.selected_duration_ns
+            self._selected_unknown_ns += facts.selected_value_unknown_duration_ns if self._conditioned else span-facts.value_valid_duration_ns
+            if self._conditioned:
+                self._false_ns += facts.false_duration_ns
+            self._quality |= facts.quality
+            self._rows[:] = self._rows[-1:]
+        except BaseException as exc:
+            primary, self._failed = exc, True
+            raise
+        finally:
+            series = block = facts = times = values = deadlines = conditions = options = None
+            try:
+                _release_owned_ram(self, self._workspace_cost, '_workspace_cost')
+            except BaseException as cleanup:
+                self._failed = True
+                if primary is None:
+                    raise
+                primary.add_note('时间统计临时费用释放失败：'+type(cleanup).__name__)
+
+    def _finish_mean(self):
+        """分批回读必要数值/权重，复用原归一化及原序求和，最终只换单位一次。
+
+        参数: 无。返回: TimeReductionResult。异常: 临时数据短缺/多出、IO、预算或取消。
+        """
+        if self._record_count == 0:
+            return TimeReductionResult(None, self._unit, False, Q.NONE, 0)
+        denominator = (self._reduction.selected_duration_ns if self._step_ns is None
+                       else self._reduction.selected_weight_seconds)
+        self._file.seek(0)
+        self._mean_sum = (ReferenceIntegralSum if self._backend == 'reference' else NumpyIntegralSum)(self._partial_limit)
+        remaining, quality = self._record_count, Q.NONE
+        payload = pairs = values = weights = terms = keep = None
+        try:
+            while remaining:
+                count = min(remaining, self._limit)
+                payload = self._file.read(count*self._codec.size)
+                if len(payload) != count*self._codec.size:
+                    raise ValueError('均值必要暂存数据不完整')
+                if self._backend == 'reference':
+                    pairs = tuple(self._codec.iter_unpack(payload))
+                    values, weights = tuple(item[0] for item in pairs), tuple(item[1] for item in pairs)
+                    terms, failure = reference_mean(values, weights, denominator)
+                    keep = (True,)*len(terms)
+                else:
+                    pairs = np.frombuffer(payload, dtype=[('value', '>f8'),
+                        ('weight', '>i8' if self._step_ns is None else '>f8')])
+                    values, weights = pairs['value'], pairs['weight']
+                    terms, failure = numpy_mean(values, weights, denominator)
+                    keep = np.ones(len(terms), dtype=bool)
+                    keep.setflags(write=False)
+                quality |= failure
+                if quality == Q.NONE:
+                    self._mean_sum.push_values(terms, keep)
+                remaining -= count
+            if self._file.read(1):
+                raise ValueError('均值必要暂存含未登记数据')
+            if quality != Q.NONE:
+                return TimeReductionResult(None, self._unit, True, quality, self._record_count)
+            number = self._mean_sum.finish(self._unit, self._factor)
+            return TimeReductionResult(number.value, number.unit, number.calculation_failed, number.quality, self._record_count)
+        finally:
+            payload = pairs = values = weights = terms = keep = None
+
+    def finish(self):
+        """上游确认EOF后结算，并关闭删除均值临时文件，再交付精简结果。
+
+        参数: 无。返回: RecordTimeResult，重复调用同一结果。异常: 失败拒绝前缀，close可重试。
+        """
+        self._require_open()
+        if self._finished:
+            return self._result
+        primary = None
+        try:
+            self._flush()
+            workspace = 65536 + (self._limit+1)*12288 if self._spec.operation == 'time_weighted_mean' else 4096
+            _reserve_owned_ram(self, workspace, '_workspace_cost')
+            number = self._finish_mean() if self._spec.operation == 'time_weighted_mean' else self._reduction.finish()
+            value, status, reason = classify_calculation_value(self._spec, number.value, self._covered_ns,
+                self._known_ns, self._selected_ns, self._selected_unknown_ns,
+                all_false=self._conditioned and self._covered_ns>0 and self._false_ns==self._covered_ns,
+                calculation_failed=number.calculation_failed)
+            if self._file is not None:
+                self._file.close()
+                self._file = None
+            coverage=None if self._coverage_value_ns is None else classify_coverage(
+                self._spec,self._covered_ns,self._coverage_value_ns,self._known_ns)
+            self._result = RecordTimeResult(value, self._unit, status, reason, self._quality | number.quality,coverage)
+            self._finished = True
+            return self._result
+        except BaseException as exc:
+            primary, self._failed = exc, True
+            raise
+        finally:
+            number = None
+            try:
+                _release_owned_ram(self, self._workspace_cost, '_workspace_cost')
+            except BaseException as cleanup:
+                self._failed = True
+                if primary is None:
+                    raise
+                primary.add_note('时间统计结算费用释放失败：'+type(cleanup).__name__)
+
+    @property
+    def closed(self):
+        """读取自有文件/费用是否全部释放。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    def close(self):
+        """清理自有数值状态和临时文件，释放失败保留重试入口，不碰输入文件。
+
+        参数: 无。返回: None。异常: 文件关闭/费用释放失败可重试；重复关闭安全。
+        """
+        if self._closed:
+            return
+        self._closing = True
+        self._rows = self._reduction = self._mean_sum = self._result = None
+        if self._file is not None:
+            self._file.close()
+            self._file = None
+        _release_owned_ram(self, self._workspace_cost, '_workspace_cost')
+        _release_owned_ram(self, self._fixed_cost, '_fixed_cost')
+        self._closed = True

chronaxis/execution/record_time_indexes.py

@@ -0,0 +1,143 @@
+"""只为周期选窗/事件时长保存一份所需驱动时刻，按索引定位。
+
+每条只写一个实际整数时间；偏移只在单次查询中按记录索引计算，不保存改写时间轴。
+"""
+from fractions import Fraction
+from struct import Struct
+from tempfile import TemporaryFile
+from ..results.errors import ResultClosedError
+from ..results.spool import _reserve_owned_ram,_release_owned_ram,_cleanup_owner
+
+
+class RecordTimeIndexes:
+    """拥有各必要驱动的一份定长时间文件，所有消费者借用。"""
+
+    def __init__(self,budget,path,drivers):
+        """预付有限索引状态。参数: 预算/私有路径/唯一驱动名称。返回: owner。异常: 原构造错。"""
+        self._budget,self._path=budget,path
+        self._files={}
+        self._counts={}
+        self._last={}
+        self._held_cost=self._fixed_cost=0
+        self._closed=False
+        self._codec=Struct('>q')
+        try:
+            _reserve_owned_ram(self,65536+len(drivers)*32768,'_fixed_cost')
+            self._counts=dict.fromkeys(drivers,0)
+            self._last=dict.fromkeys(drivers)
+        except BaseException as error:
+            _cleanup_owner(self,error,'record_time_indexes_cleanup_owner','必要驱动索引构造')
+            raise
+
+    def observe_group(self,group):
+        """每驱动每实际同刻组只写一次。参数: 完整组。返回: None。异常: 顺序/IO/预算错误。"""
+        if self._closed:
+            raise ResultClosedError('驱动索引已关闭')
+        names={sample.name for sample in group.samples}
+        for driver in self._counts:
+            if driver not in names:
+                continue
+            if self._last[driver] is not None and group.time_ns<=self._last[driver]:
+                raise ValueError('驱动索引时间回退或重复')
+            if driver not in self._files:
+                self._files[driver]=TemporaryFile(mode='w+b',dir=self._path,prefix='driver-times-')
+            self._budget.reserve_spool(8)
+            handle=self._files[driver]
+            handle.seek(0,2)
+            if handle.write(self._codec.pack(group.time_ns))!=8:
+                raise OSError('驱动索引短写')
+            self._counts[driver]+=1
+            self._last[driver]=group.time_ns
+
+    def count(self,driver):
+        """读取已写条数。参数: 驱动。返回: int。异常: 未声明驱动。"""
+        return self._counts[driver]
+
+    def last(self,driver):
+        """读取已写末时刻。参数: 驱动。返回: int或None。异常: 未声明驱动。"""
+        return self._last[driver]
+
+    def at(self,driver,index):
+        """只读取一个时间整数。参数: 驱动/索引。返回: int。异常: 越界/短读。"""
+        if self._closed:
+            raise ResultClosedError('驱动索引已关闭')
+        if not 0<=index<self._counts[driver]:
+            raise IndexError('驱动索引越界')
+        handle=self._files[driver]
+        handle.seek(index*8)
+        data=handle.read(8)
+        if len(data)!=8:
+            raise ValueError('驱动索引短读')
+        return self._codec.unpack(data)[0]
+
+    def lower(self,driver,time_ns):
+        """二分首个不早于time_ns的时刻。参数: 驱动/实际时间。返回: 索引。异常: 原读取错。"""
+        lo,hi=0,self._counts[driver]
+        while lo<hi:
+            mid=(lo+hi)//2
+            if self.at(driver,mid)<time_ns:
+                lo=mid+1
+            else:
+                hi=mid
+        return lo
+
+    def position(self,driver,time_ns):
+        """单次查询实际时刻位于哪对记录及其比例，不保存转换时间轴。
+
+        参数: 驱动/实际时间。返回: (Fraction记录位置,是否超出观测)。异常: 空索引或读取错。
+        """
+        if not self.count(driver):
+            raise ValueError('记录位置需要真实驱动')
+        count=self.count(driver)
+        right=self.lower(driver,time_ns)
+        if right==count:
+            position=Fraction(count-1)
+            outside=time_ns>self.at(driver,count-1)
+        elif self.at(driver,right)==time_ns:
+            position=Fraction(right)
+            outside=False
+        elif right==0:
+            position=Fraction(0)
+            outside=True
+        else:
+            left_time,right_time=self.at(driver,right-1),self.at(driver,right)
+            position=Fraction(right-1)+Fraction(time_ns-left_time,right_time-left_time)
+            outside=False
+        return position,outside
+
+    def shift(self,driver,time_ns,offset_ns,step_ns):
+        """按所选周期偏移记录位置，返回实际时刻及首尾裁剪标识。
+
+        参数: 驱动、实际锚点、带符号偏移ns、正周期ns。返回: (实际ns,是否裁剪)。
+        非整周期按原实际间隔比例定位，最终纳秒沿既有最近偶数舍入；不补观测之外的记录。
+        异常: 空索引/非法周期/实际读取错。
+        """
+        if step_ns<=0 or not self.count(driver):
+            raise ValueError('周期选窗需要正周期及真实驱动记录')
+        count=self.count(driver)
+        position,outside=self.position(driver,time_ns)
+        target=position+Fraction(offset_ns,step_ns)
+        if target<0:
+            return self.at(driver,0),True
+        if target>count-1:
+            return self.at(driver,count-1),True
+        left=target.numerator//target.denominator
+        if target==left:
+            return self.at(driver,left),outside
+        a,b=self.at(driver,left),self.at(driver,left+1)
+        return round(Fraction(a)+(target-left)*(b-a)),outside
+
+    @property
+    def closed(self):
+        """返回关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    def close(self):
+        """只关闭本次必要文件，失败可重试。参数: 无。返回: None。异常: 原关闭错。"""
+        if self._closed:
+            return
+        for driver in tuple(self._files):
+            self._files[driver].close()
+            del self._files[driver]
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost')
+        self._closed=True

chronaxis/execution/record_value_history.py

@@ -0,0 +1,160 @@
+"""只为需要回看范围的消费者保存计算值，一份实际时间和必要有效截止。
+
+同一表达式/条件/驱动可共享此文件。最后一点留在内存，便于非驱动失效更新
+它的截止；其余记录定长保存，可二分定位而无需全量核验或JSON重建。
+"""
+from struct import Struct
+from tempfile import TemporaryFile
+from ..core.numeric import ScalarValue
+from ..core.types import SignalDType as D,QualityFlag as Q
+from ..results.errors import ResultClosedError
+from ..results.spool import _reserve_owned_ram,_release_owned_ram,_cleanup_owner
+
+
+class RecordValueHistory:
+    """拥有单个必要临时文件和最后一个计算点；没有原帧、原文或第二时间轴。"""
+
+    def __init__(self,budget,path,dtype,conditioned=False,*,sample_updates=False,labels=()):
+        """预付有限读写状态，不立即建文件。
+
+        参数: 预算/专用路径/值类型/条件开关；sample_updates按需存真实更新标志，labels共享枚举域。
+        返回: owner。异常: 原构造错。
+        """
+        self._budget,self._path,self._dtype,self._conditioned=budget,path,dtype,conditioned
+        self._sample_updates,self._labels=sample_updates,labels
+        self._held_cost=self._fixed_cost=0
+        self._file=self._last=None
+        self._count=0
+        self._closed=self._failed=False
+        try:
+            _reserve_owned_ram(self,65536,'_fixed_cost')
+            if type(sample_updates) is not bool:raise TypeError('样本标志开关需要bool')
+            if dtype is D.ENUM:
+                if type(labels) is not tuple or not labels:raise ValueError('枚举历史需要共享标签域')
+                _reserve_owned_ram(self,4096+sum(1024+64*len(label) for label in labels),'_fixed_cost')
+            code={D.FLOAT64:'d',D.INT64:'q',D.UINT64:'Q',D.BOOL:'?',D.ENUM:'I'}[dtype]
+            self._codec=Struct('>q'+code+'?Iq?'+('??Iq?' if conditioned else '')+('?' if sample_updates else ''))
+        except BaseException as error:
+            _cleanup_owner(self,error,'record_value_history_cleanup_owner','必要计算历史构造')
+            raise
+
+    @property
+    def count(self):
+        """含内存末点的记录数。参数: 无。返回: int。异常: 无。"""
+        return self._count+(self._last is not None)
+
+    @property
+    def last_time(self):
+        """最后真实驱动时刻。参数: 无。返回: int或None。异常: 无。"""
+        return None if self._last is None else self._last[0]
+
+    def _open(self):
+        """拒绝失败/关闭后使用。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed or self._failed:
+            raise ResultClosedError('必要计算历史已关闭或失败')
+
+    def append(self,row,condition=None,*,actual_update=False):
+        """写前一点并留下新点；输入是本执行器已验证的求值结果。
+
+        参数: row(time,ScalarValue,deadline)，condition为同样三元组或None；actual_update标识真实值更新。
+        返回: None。异常: 顺序/短写/预算错误，失败后只能清理。
+        """
+        self._open()
+        try:
+            if type(actual_update) is not bool:raise TypeError('真实更新标志需要bool')
+            time,value,deadline=row
+            if self._last is not None and time<=self._last[0]:
+                raise ValueError('必要计算历史时间须递增')
+            if self._last is not None:
+                if self._file is None:
+                    self._file=TemporaryFile(mode='w+b',dir=self._path,prefix='calculation-values-')
+                t,v,d,c,cd=self._last[:5]
+                number=self._labels.index(v.value) if self._dtype is D.ENUM and v.valid else v.value if v.valid else 0
+                fields=(t,number,v.valid,int(v.quality),d or 0,d is not None)
+                if self._conditioned:
+                    fields+=(bool(c.value) if c.valid else False,c.valid,int(c.quality),cd or 0,cd is not None)
+                if self._sample_updates:fields+=(self._last[5],)
+                payload=self._codec.pack(*fields)
+                self._budget.reserve_spool(len(payload))
+                self._file.seek(0,2)
+                if self._file.write(payload)!=len(payload):
+                    raise OSError('必要计算历史短写')
+                self._count+=1
+            self._last=(time,value,deadline,None if condition is None else condition[1],
+                        None if condition is None else condition[2])+((actual_update,) if self._sample_updates else ())
+        except BaseException:
+            self._failed=True
+            raise
+
+    def expire_at(self,time_ns,*,condition=False):
+        """非驱动失效只裁最后点，不添加假记录。参数: 实际截止/条件标识。返回: None。异常: 时间回退。"""
+        self._open()
+        if self._last is None:
+            return
+        if time_ns<self._last[0]:
+            raise ValueError('必要计算历史截止回退')
+        index=4 if condition else 2
+        old=self._last[index]
+        self._last=self._last[:index]+(time_ns if old is None else min(old,time_ns),)+self._last[index+1:]
+
+    def at(self,index):
+        """读取一个实际记录，不全量扫描。参数: 已登记索引。返回: 点及条件五元组。异常: 越界/短读。"""
+        self._open()
+        if not 0<=index<self.count:
+            raise IndexError('必要计算历史索引越界')
+        if index==self._count:
+            return self._last
+        self._file.seek(index*self._codec.size)
+        payload=self._file.read(self._codec.size)
+        if len(payload)!=self._codec.size:
+            raise ValueError('必要计算历史短读')
+        fields=self._codec.unpack(payload)
+        t,v,valid,quality,deadline,has_deadline=fields[:6]
+        value=ScalarValue((self._labels[v] if self._dtype is D.ENUM else v) if valid else None,
+                         self._dtype,valid,Q(quality),self._labels)
+        selected=selected_deadline=None
+        if self._conditioned:
+            c,valid,quality,selected_deadline,has_end=fields[6:11]
+            selected=ScalarValue(c if valid else None,D.BOOL,valid,Q(quality))
+            if not has_end:
+                selected_deadline=None
+        return (t,value,deadline if has_deadline else None,selected,selected_deadline)+((fields[-1],) if self._sample_updates else ())
+
+    def lower(self,time_ns):
+        """二分首个不早于time_ns的索引。参数: 实际时间。返回: int。异常: 原读取错。"""
+        lo,hi=0,self.count
+        while lo<hi:
+            mid=(lo+hi)//2
+            if self.at(mid)[0]<time_ns:
+                lo=mid+1
+            else:
+                hi=mid
+        return lo
+
+    def rows(self,start_ns,end_ns):
+        """只借出范围两侧及其中的记录，保留裁剪分母。参数: 实际起止。返回: 迭代器。异常: 原读取错。"""
+        self._open()
+        if not self.count:
+            return
+        first=self.lower(start_ns)
+        if first==self.count or first>0 and self.at(first)[0]>start_ns:
+            first-=1
+        last=min(self.count-1,self.lower(end_ns))
+        for index in range(first,last+1):
+            yield self.at(index)
+
+    @property
+    def closed(self):
+        """返回自有资源关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    def close(self):
+        """关闭必要文件并退款，不碰原输入。参数: 无。返回: None。异常: 原关闭错，可重试。"""
+        if self._closed:
+            return
+        if self._file is not None:
+            self._file.close()
+            self._file=None
+        self._last=None
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost')
+        self._closed=True