chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/windows_numpy.py

@@ -0,0 +1,78 @@
+"""独立用NumPy扩展、分组和裁剪事件窗口，再恢复片段模型。
+
+输入已排序Event tuple、WindowSpec和实际观测Interval，输出Segment tuple。
+时间端点为(N,) int64纳秒列，先检查扩展溢出，再执行UFUNC；按真实活动间隔
+或请求窗口重叠建立组边界，reduceat归约每组范围，数组裁剪并计算覆盖。
+输出循环只打包模型/元数据，不逐事件执行参考数值；不调用参考窗口算法。
+输入和数组完整物化，不读旧链、不写文件、不承诺整个AnalysisRunner的预算。
+"""
+
+# 真正数组端点、掩码与分组归约，禁止object/vectorize替代。
+import numpy as np
+from ..timebase.conversion import INT64_MIN, INT64_MAX, TimeOverflowError
+from .models import Interval
+# 只共享已校验协议与ID/诊断包装。
+from .windows import require_windows, make_segment, require_resolved_windows
+
+
+def build_segments_numpy(events, spec, observation, *, bounds=None, compact=False):
+    """以数组计算请求与实际范围，输出保留原事件关联的片段。
+
+    参数: events已排序真实事件；spec为WindowSpec；observation为真实Interval。
+    返回: Segment或compact的CompactSegment tuple；bounds为已解析的实际边界。旧覆盖保持独立float64比值。
+    异常: 配置/模型错误传播；端点或跨度溢出明确拒绝；分配失败不吞。
+    流程: 扩展前校验int64上下界，批量建立连接掩码/组索引、归约、裁剪及覆盖。
+        恢复Interval时校验请求跨度，再做安全整数差；不改变原事件。
+    """
+    # 共享的门槛没有窗口数值或归约。
+    require_windows(events, spec, observation)
+    require_resolved_windows(events,bounds,compact)
+    if not events:
+        return ()
+    # 每个时间列为(N,)纳秒，point的结束锚点等于真实触发时刻。
+    onsets = np.array([event.start_ns for event in events], dtype=np.int64)
+    endings = np.array([event.start_ns if event.end_ns is None else event.end_ns for event in events], dtype=np.int64)
+    extension = spec.exit_delay_ns if spec.merge == 'exit_delay' else spec.post_ns
+    if bounds is None:
+        if np.any(onsets < np.int64(INT64_MIN + spec.pre_ns)) or np.any(endings > np.int64(INT64_MAX - extension)):
+            raise TimeOverflowError('窗口请求扩展超出int64纳秒')
+        starts = np.subtract(onsets, np.int64(spec.pre_ns))
+        ends = np.add(endings, np.int64(extension))
+        left_clip=right_clip=np.zeros(len(events),dtype=bool)
+    else:
+        starts=np.array([item[0] for item in bounds],dtype=np.int64)
+        ends=np.array([item[1] for item in bounds],dtype=np.int64)
+        left_clip=np.array([item[2] for item in bounds],dtype=bool)
+        right_clip=np.array([item[3] for item in bounds],dtype=bool)
+    # 连接掩码(N-1,)；single比较真实onset与前活动退出deadline，不使用pre。
+    if spec.merge == 'exit_delay':
+        connected = (onsets[1:] <= ends[:-1]) | right_clip[:-1]
+    elif spec.merge == 'overlap':
+        prior=np.maximum.accumulate(ends)[:-1]
+        connected = (starts[1:] < prior) | ((starts[1:] == prior) & (np.maximum.accumulate(right_clip)[:-1] | left_clip[1:]))
+    elif spec.merge == 'overlap_and_adjacent':
+        connected = starts[1:] <= np.maximum.accumulate(ends)[:-1]
+    else:
+        connected = np.zeros(len(events)-1, dtype=bool)
+    # 组首索引和结束索引只依赖本次真实事件，未重新排序旧输入。
+    first = np.concatenate((np.array([0], dtype=np.int64), np.flatnonzero(~connected)+1))
+    stop = np.concatenate((first[1:], np.array([len(events)], dtype=np.int64)))
+    group_starts = np.minimum.reduceat(starts, first)
+    group_ends = np.maximum.reduceat(ends, first)
+    # 模型恢复先验证合并请求跨度，之后整数求差才保证不wrap。
+    requests = tuple(Interval(int(start), int(end)) for start, end in zip(group_starts, group_ends))
+    left = np.maximum(group_starts, np.int64(observation.start_ns))
+    right = np.minimum(group_ends, np.int64(observation.end_ns))
+    observed = right >= left
+    actuals = tuple(Interval(int(start), int(end)) if flag else None for start, end, flag in zip(left, right, observed))
+    if compact:
+        coverages=[None]*len(first)
+    else:
+        requested_duration = np.subtract(group_ends, group_starts)
+        actual_duration = np.zeros(len(first), dtype=np.int64)
+        np.subtract(right, left, out=actual_duration, where=observed)
+        coverages = np.divide(actual_duration.astype(np.float64), requested_duration.astype(np.float64))
+    clipped=np.logical_or.reduceat(left_clip|right_clip,first)
+    # 输出循环只关联父事件和包装typed模型，全部边界/分组/覆盖已在数组完成。
+    return tuple(make_segment(spec, requests[index], actuals[index], None if compact else float(coverages[index]), events[int(start):int(end)],compact=compact,clipped=bool(clipped[index]))
+                 for index, (start, end) in enumerate(zip(first, stop)))

chronaxis/core/windows_reference.py

@@ -0,0 +1,61 @@
+"""独立用Python精确整数扩展、合并并裁剪事件窗口，输出完整片段事实。
+
+输入已排序真实Event、WindowSpec和观测Interval，输出Segment tuple。
+先按onset/点锚点扩展请求，再按明确政策分组，最后裁剪并计算覆盖。
+single按真实活动间隔判断，pre重叠不扩大分组；相等deadline重入合并。
+本实现不调用NumPy数值，只共享协议与元数据包装，不读写旧日志或重写事件。
+输入和输出均完整保存在内存中，调用方负责资源预算。
+"""
+
+# 精确时间算术在Python整数域检查，不wrap或先转float。
+from ..timebase.conversion import checked_add_ns
+from .models import Interval
+# 共享协议与ID/质量包装，不共享扩展、合并或覆盖算法。
+from .windows import require_windows, make_segment, require_resolved_windows
+
+
+def build_segments_reference(events, spec, observation, *, bounds=None, compact=False):
+    """根据真实事件构造请求窗口及其实际观测交集。
+
+    参数: events为已排序Event tuple；spec为WindowSpec；observation为真实半开范围。
+    返回: Segment或compact的CompactSegment tuple；bounds为按所选周期解析的真实边界。空事件返回空tuple。
+    异常: 模型、排序、归属错误传播；请求端点或跨度溢出明确拒绝。
+    流程: 逐事件精确扩展，按none/重叠/相邻/真实退出间隔分组，逐组裁剪。
+        不改变原Event，不增加旧writer调用，不凭EOF外的请求补观测。
+    """
+    # 类型和原事件事实在数值执行前验证。
+    require_windows(events, spec, observation)
+    require_resolved_windows(events,bounds,compact)
+    groups = []
+    # 当前组的请求范围与末个真实活动分开保存，pre不参与退出间隔。
+    for index,event in enumerate(events):
+        start = checked_add_ns(event.start_ns, -spec.pre_ns) if bounds is None else bounds[index][0]
+        end_anchor = event.start_ns if event.end_ns is None else event.end_ns
+        extension = spec.exit_delay_ns if spec.merge == 'exit_delay' else spec.post_ns
+        end = checked_add_ns(end_anchor, extension) if bounds is None else bounds[index][1]
+        left_clip,right_clip=(False,False) if bounds is None else bounds[index][2:]
+        requested = Interval(start, end)
+        # 每组先有独立请求，再决定是否与已有组连接。
+        merge = False
+        if groups:
+            previous = groups[-1]
+            if spec.merge == 'exit_delay':
+                merge = event.start_ns <= (checked_add_ns(previous[2][-1].end_ns, spec.exit_delay_ns) if bounds is None else previous[1]) or previous[4]
+            elif spec.merge == 'overlap':
+                merge = start < previous[1] or start==previous[1] and (previous[4] or left_clip)
+            elif spec.merge == 'overlap_and_adjacent':
+                merge = start <= previous[1]
+        # 合并仅扩展片段，不写回原活动边界或真实状态。
+        if merge:
+            groups[-1] = (min(groups[-1][0], start), max(groups[-1][1], end), groups[-1][2] + (event,),groups[-1][3] or left_clip,groups[-1][4] or right_clip)
+        else:
+            groups.append((requested.start_ns, requested.end_ns, (event,),left_clip,right_clip))
+    results = []
+    # 逐组裁剪和覆盖为独立参考算术，不调用数组内核。
+    for start, end, parents,left_clip,right_clip in groups:
+        requested = Interval(start, end)
+        left, right = max(start, observation.start_ns), min(end, observation.end_ns)
+        actual = Interval(left, right) if left <= right else None
+        coverage = None if compact else (0 if actual is None else actual.duration_ns()) / requested.duration_ns()
+        results.append(make_segment(spec, requested, actual, coverage, parents,compact=compact,clipped=left_clip or right_clip))
+    return tuple(results)

chronaxis/execution/__init__.py

@@ -0,0 +1,6 @@
+"""保存新执行层内部组件，公共入口由根包AnalysisRunner按需加载。
+
+输入为已解码批次，历史组件输出有限单行重放；模块本身不读取旧来源。
+run_session协调来源创建、同组归并和已实现算子，资源账本复用结果层。
+本模块自身仅说明包职责，导入不读取来源、创建目录或保存运行状态。
+"""

chronaxis/execution/batch_signal_groups.py

@@ -0,0 +1,122 @@
+"""将已校验的解析信号批按watermark归为同刻组，不创建磁盘历史。
+
+来源适配器负责原输入及跨批合同。本层只保尚未完整的组，最大时间组等到
+后续时间或真实EOF才交付；超出预算直接失败，不拆散同刻更新。
+"""
+
+import heapq
+from ..core.models import SourceRef
+from ..results.errors import ResultClosedError
+from ..results.spool import _reserve_owned_ram, _release_owned_ram, _cleanup_owner
+from .groups import DecodedTimeGroup
+from .record_sample import RecordSample
+from ..core.types import SignalDType as D
+from .calculation_values import scalar_from_column
+from .history import _metadata_bytes
+
+
+class BatchSignalGroups:
+    """借用已验证批，拥有未完成样本与有限排序状态。"""
+
+    def __init__(self, budget, definitions, session_id, consumer):
+        """预付状态。参数: 预算、有限定义、会话、consumer。返回: owner。异常: 预算/取消原错。"""
+        self._budget, self._consumer = budget, consumer
+        self._held_cost = self._fixed_cost = self._sample_cost = self._work_cost = 0
+        self._heap = None
+        self._refs = None
+        self._serial = 0
+        self._maximum = self._last = None
+        self._closed = self._failed = self._finished = False
+        try:
+            _reserve_owned_ram(self, 65536 + 32*_metadata_bytes(definitions), '_fixed_cost')
+            self._refs = {item.name: SourceRef(session_id, item.source, item.field) for item in definitions}
+            self._heap = []
+        except BaseException as error:
+            _cleanup_owner(self, error, 'batch_groups_cleanup_owner', '解析信号归组')
+            raise
+
+    def consume(self, batch):
+        """保必要规范值，按完成进度交付组；丢弃原值/详细来源副本。
+
+        参数: 可信适配器已校验SignalBatch。返回: None。异常: 预算/模型/回退，失败后只清理。
+        """
+        if self._closed or self._failed or self._finished:
+            raise ResultClosedError('解析信号组已关闭、失败或结束')
+        sample = value = column = None
+        try:
+            for column in batch.series.values():
+                for index in range(len(column.time_ns)):
+                    time = int(column.time_ns[index])
+                    if self._last is not None and time <= self._last:
+                        raise ValueError('来源在已交付同刻组之后又返回旧样本')
+                    _reserve_owned_ram(self, 8192, '_sample_cost')
+                    value = scalar_from_column(column, index)
+                    sample = RecordSample(column.name, time, int(column.sequence[index]),
+                        value, column.unit,self._refs[column.name],
+                        column.values[index].item() if value.dtype is D.ENUM else None)
+                    heapq.heappush(self._heap, (time, self._serial, sample))
+                    self._serial += 1
+                    self._maximum = time if self._maximum is None else max(time, self._maximum)
+            if batch.watermark_ns is not None:
+                self._flush(batch.watermark_ns, keep_last=True)
+        except BaseException:
+            self._failed = True
+            raise
+        finally:
+            batch = sample = value = column = None
+
+    def _flush(self, watermark, *, keep_last):
+        """只交付完整组，费用在consumer返回后释放。参数: 进度/是否保末组。返回: None。异常: 原错。"""
+        while self._heap and (watermark is None or self._heap[0][0] <= watermark):
+            time = self._heap[0][0]
+            if keep_last and time == self._maximum:
+                return
+            samples = group = None
+            count = 0
+            primary = None
+            try:
+                # 当前组至多为已付费样本数量，先覆盖列表/tuple引用再构造。
+                _reserve_owned_ram(self, 4096 + len(self._heap)*32, '_work_cost')
+                samples = []
+                while self._heap and self._heap[0][0] == time:
+                    samples.append(heapq.heappop(self._heap)[2])
+                    count += 1
+                group = DecodedTimeGroup(time, tuple(samples))
+                self._consumer(group)
+                self._last = time
+            except BaseException as error:
+                primary = error
+                raise
+            finally:
+                samples = group = None
+                try:
+                    _release_owned_ram(self, count*8192, '_sample_cost')
+                    _release_owned_ram(self, self._work_cost, '_work_cost')
+                except BaseException as cleanup:
+                    self._failed = True
+                    if primary is None:
+                        raise
+                    primary.add_note('解析同刻组清理失败：'+type(cleanup).__name__)
+
+    def finish(self):
+        """调用方确认真实EOF及关闭后交最后组。参数: 无。返回: None。异常: 失败拒绝完成。"""
+        if self._closed or self._failed:
+            raise ResultClosedError('解析信号组不能完成')
+        if self._finished:
+            return
+        try:
+            self._flush(None, keep_last=False)
+            self._finished = True
+        except BaseException:
+            self._failed = True
+            raise
+
+    def close(self):
+        """丢待处理组并退款，不把提前close当EOF。参数: 无。返回: None。异常: 退款失败可重试。"""
+        if self._closed:
+            return
+        self._failed = True
+        self._heap = self._consumer = self._refs = None
+        for slot in ('_work_cost', '_sample_cost', '_fixed_cost'):
+            _release_owned_ram(self, getattr(self, slot), slot)
+        self._closed = True

chronaxis/execution/bindings.py

@@ -0,0 +1,296 @@
+"""核对实际封存解码历史，建立可执行表达式所需的独立运行绑定。
+
+输入为当前DeclarationBindings和sealed DecodedHistoryStore，输出须close的元数据持有对象。
+先核对请求/字段/完整归一化与时基指纹，再逐源有限重放到实际文件EOF，校验原SHA和计数。
+运行身份同时包含声明、实际描述/投影/历史与原EOF范围；不以静态表达式或猜测SHA替代核对。
+只重放新解码历史，不重读旧原日志/DBC，不保留全样本，不重新转换或计算表达式。
+固定元数据和构造临时量先计账，单行读预算由历史游标拥有，失败/取消关闭自有游标。
+外部保存已取得bindings/CompiledExpression超过lease寿命时须另负责该元数据持有量。
+同一个真实DecodedBindingLease从首次预约前持有固定费、当前reader及有限临时状态；
+未返回且持续清理失败时由原异常decoded_binding_lease_cleanup_owner交接。
+单笔预约/释放返回后取消也按实际交易更新槽，不重复归还借用history或其他reader费用。
+纯契约校验入口供不保存普通历史的内部扫描复用；它不生成读取证据，公共工厂仍检查实际磁盘EOF。
+"""
+
+# 受控类型树生成规范摘要，不执行任意对象repr或反射表达式。
+from collections.abc import Mapping
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from hashlib import sha256
+from ..core.binding import SignalDefinition, _identity
+from ..core.decoded_binding import DecodedBindings, DecodedSourceEvidence
+from ..core.declarations import DeclarationBindings, DeclaredSource
+from ..core.types import SignalDType
+from ..results.errors import ResultClosedError, ResultFormatError
+from ..results.spool import _cleanup_owner, _reserve_owned_ram, _release_owned_ram
+from ..sources.descriptions import describe_fields, source_timebase_identity
+from ..sources.models import ReadRequest, SourceDescription
+from .history import DecodedHistoryStore, _metadata_bytes
+from .history_records import HistoryProgress, HistorySample
+
+
+def _fingerprint_value(value):
+    """把已校验冻结元数据转换为纯标量/tuple，不丢字段或来源定位。
+
+    参数: value为当前typed描述/请求元数据树。返回: _identity支持的不可变树。
+    异常: TypeError为未声明结构；调用方已申请元数据构造预算。
+    """
+    if is_dataclass(value) and not isinstance(value, type):
+        return (type(value).__name__, tuple((item.name, _fingerprint_value(getattr(value, item.name))) for item in fields(value)))
+    if isinstance(value, Mapping):
+        # JSON键已检查为str；排序只用于身份，不改变读取/字段/文件次序。
+        return tuple((key, _fingerprint_value(value[key])) for key in sorted(value))
+    if type(value) is tuple:
+        return tuple(_fingerprint_value(item) for item in value)
+    if isinstance(value, Enum):
+        return (type(value).__name__, value.value)
+    if value is None or type(value) in (str, int, float, bool):
+        return value
+    raise TypeError('运行绑定元数据含未支持类型')
+
+
+def _fingerprint(value):
+    """计算完整typed树摘要。参数: value冻结元数据。返回: SHA256文本。异常: 树/分配错误。"""
+    return sha256(_identity(_fingerprint_value(value)).encode('utf-8')).hexdigest()
+
+
+class DecodedBindingLease:
+    """从首次预约到返回绑定持有唯一真实费用及当前回放reader。
+
+    _cost/_held_cost只含工厂原固定金额；_reader拥有独立FD及它自己的费用。
+    _bindings仅在完整EOF和当前reader清完后开放。_closing/_failed期间禁止借出，
+    直到实际reader和固定费都清完才closed，不关闭借用history/scan或删除文件。
+    """
+
+    def __init__(self, budget):
+        """在首次外部操作前初始化真实责任槽，不申请预算或打开文件。
+
+        参数: budget为调用方历史的共享预算。返回: 尚未取得固定费或完成绑定的lease。
+        异常: 无主动异常；构造不接已经付费的裸金额，也不复制样本。
+        """
+        # 费用与子reader必须先可清理；工厂后续每笔真实交易才登记已取得金额。
+        self._budget, self._cost, self._held_cost = budget, 0, 0
+        self._bindings = self._reader = self._current = None
+        self._history = self._declarations = None
+        self._evidence = self._definitions = self._described = None
+        self._closed = self._closing = self._failed = False
+
+    @property
+    def bindings(self) -> DecodedBindings:
+        """读取不可变运行绑定。参数: 无。返回: DecodedBindings。异常: ResultClosedError为关闭。"""
+        if self._closed or self._closing or self._failed or self._bindings is None:
+            raise ResultClosedError('解码运行绑定未完成、已关闭或正在清理')
+        return self._bindings
+
+    @property
+    def closed(self) -> bool:
+        """读取lease状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    def _close_reader(self):
+        """关闭本lease唯一实际reader，失败仍保留未完成的子责任。
+
+        参数: 无。返回: None。异常: 原reader.close错误传播；完成后取消不留重复释放槽。
+        """
+        if self._reader is None:
+            return
+        # 正常返回即结束责任；真实reader已经closed后才抛错也已完成，不再二次抵销。
+        try:
+            self._reader.close()
+        except BaseException:
+            if getattr(self._reader, 'closed', False):
+                self._reader = None
+            raise
+        else:
+            self._reader = None
+
+    def _clear_temporary(self):
+        """结束有限工厂临时引用，不关闭借用对象。
+
+        参数: 无。返回: None。异常: 无主动异常；不遍历原rows或删除历史。
+        """
+        self._current = self._evidence = self._definitions = self._described = None
+        self._history = self._declarations = None
+
+    def close(self):
+        """先关真实reader，再丢自有元数据并逐笔归还固定费。
+
+        参数: 无。返回: None，完成后幂等。异常: 原FD/预算错误可重试，释放后取消不重复扣账。
+        副作用: 只关闭本lease的当前reader，不关闭调用方history/scan/其他reader。
+        """
+        if self._closed:
+            return
+        # 一旦开始清理就拒绝借出绑定；子FD和子费用未清完时保留本固定费及全部责任。
+        self._closing = True
+        # 单行内容借reader费用存活，先结束引用，避免子释放后取消仍留下长样本。
+        self._current = None
+        self._close_reader()
+        self._bindings = None
+        self._clear_temporary()
+        _release_owned_ram(self, self._cost, '_cost')
+        self._closed = True
+
+
+def _require_empty_source_scan(source, history, observed_scans):
+    """用本历史的真实扫描证明无字段来源的完整时钟，不从空描述猜测。
+
+    参数: source为原DeclaredSource；history为sealed历史；observed_scans为真实扫描tuple。
+    返回: None。异常: ValueError/ResultClosedError为缺失、重复、失效或不对应的证明。
+    不重新读取原CSV，不复制原行；后续工厂仍须逐源核当前历史文件的真实EOF。
+    """
+    matches = 0
+    for scan in observed_scans:
+        # getter只在scan仍活且成功完成时可用；同名不同历史不能冒充本次读取。
+        if scan.closed or scan.failed or not scan.finished:
+            raise ValueError('无字段来源的扫描证明须真实完成且仍可用')
+        plan = scan.source_plan
+        if plan.name not in history.validators:
+            raise ValueError('无字段来源的扫描不能包含当前历史之外的来源')
+        if plan.name != source.name:
+            continue
+        matches += 1
+        validator = history.validators[source.name]
+        completion = history.source_completions[source.name]
+        observation = scan.observation
+        if (scan.history is not history or scan.request is not validator.request
+                or plan.input_identity != source.input_identity
+                or plan.config.timebase != source.timebase or plan.config.offset_ns != source.offset_ns
+                or scan.history_sha256 != history.hashes[source.name].hexdigest()
+                or scan.counts != tuple(history.counts[source.name])
+                or observation.source != source.name or observation.session_id != validator.request.session_id
+                or not observation.source_eof or not completion.source_eof
+                or observation.observed_end_ns != completion.observed_end_ns):
+            raise ValueError('无字段来源的真实扫描与当前声明、请求或历史证明不符')
+    if matches != 1:
+        raise ValueError('无字段来源需唯一真实扫描的完整时基偏移证明')
+
+
+def require_decoded_source_contract(declarations: DeclarationBindings, source: DeclaredSource,
+                                    description: SourceDescription, request: ReadRequest) -> dict[str, SignalDefinition]:
+    """只核一来源的声明、实际描述和请求合同，保留所有原信号定义。
+
+    参数: declarations/source为同一当前声明；description/request为调用方实际读取
+        使用的原typed对象。未用声明可以保留，但无实际字段时投影必须为空；调用方仍须独立核实
+        同一次真实扫描的完整时基/偏移/来源身份和完成事实，本函数不认证扫描或EOF。
+    返回: 该来源全部别名到原SignalDefinition对象的dict；不裁成表达式依赖子集，
+        不生成DecodedBindings、DecodedSourceEvidence或假历史SHA。
+    异常: TypeError为非规定模型；ValueError为会话、domain、来源、完整时钟、
+        投影或字段/类型/单位/完整转换指纹不符。分配和取消错误原样传播。
+    副作用: 无文件、读取、预算或数值操作。调用方预付有限元数据工作区并负责后续
+        样本、全量观测和真实EOF证明；公共历史绑定仍必须完整核验实际磁盘文件。
+    """
+    definitions = described = clock_identity = definition = field = expected = None
+    try:
+        # 模型构造已经保证名称唯一与字段来源一致；纯入口不能依赖某个历史构造器
+        # 曾替调用方做过类型检查，也不能接受同名却不属于当前声明的来源。
+        if (not isinstance(declarations, DeclarationBindings) or not isinstance(source, DeclaredSource)
+                or not isinstance(description, SourceDescription) or not isinstance(request, ReadRequest)):
+            raise TypeError('来源合同需要typed声明/来源/描述/请求')
+        if source not in declarations.sources or description.name != source.name:
+            raise ValueError('实际描述来源与当前声明不对应')
+        if (request.session_id != declarations.session_id or request.domain_start_ns != (declarations.domain.start_ns if declarations.domain is not None else None)
+                or request.domain_end_ns != (declarations.domain.end_ns if declarations.domain is not None else None) or description.timebase_id != source.timebase.timebase_id):
+            raise ValueError('实际读取会话/domain/时基与当前声明不符')
+        definitions = {item.name: item for item in declarations.signals if item.source == source.name}
+        described = {item.name: item for item in description.fields}
+        clock_identity = source_timebase_identity(source.timebase, source.offset_ns)
+        # 时钟检查覆盖全部描述字段，不因当前请求空投影或未使用某字段而跳过。
+        if not description.fields:
+            if request.signal_names:
+                raise ValueError('无实际字段描述时读取投影必须为空，时钟须另以真实扫描证明')
+        elif any(item.field.locator.get('source_timebase_sha256') != clock_identity
+                 or item.field.locator.get('offset_ns') != source.offset_ns for item in description.fields):
+            raise ValueError('实际来源缺完整时基偏移证据或与当前声明不符')
+        if not set(request.signal_names) <= definitions.keys():
+            raise ValueError('实际读取投影包含当前未声明别名')
+        # 部分投影只核实际请求字段；未用声明保留为静态定义，不声称已经读取。
+        for name in request.signal_names:
+            definition = definitions[name]
+            field = described.get(name)
+            expected = describe_fields(source.name, (definition,))[0]
+            if (field is None or field.field.field != definition.field or field.dtype is not definition.dtype
+                    or field.unit != definition.unit or any(field.metadata.get(key) != value for key, value in expected.metadata.items())):
+                raise ValueError('实际字段/完整转换/原时基偏移与当前声明不符或缺指纹')
+        return definitions
+    finally:
+        # 失败后调用方可释放其合同费用；本层原异常frame不额外保活新索引/描述副本。
+        definitions = described = clock_identity = definition = field = expected = None
+        declarations = source = description = request = None
+
+
+def bind_decoded_history(declarations: DeclarationBindings, history: DecodedHistoryStore,
+                         *, observed_scans=()) -> DecodedBindingLease:
+    """先核对当前契约，再完整重放所有来源，只有实际EOF校验后才返回运行绑定。
+
+    参数: declarations当前配置声明；history该会话已seal的新历史，不能是building/closed；
+        observed_scans可选真实完成扫描tuple，只为无声明字段来源补完整时钟证明。
+    返回: DecodedBindingLease，样本不保留，来源摘要/计数/投影/EOF事实纳入bindings身份。
+    异常: 契约/损坏/预算/文件/取消错误原样传播；持续清理失败由原异常的
+        decoded_binding_lease_cleanup_owner持真实reader及费用，恢复后可close。
+    """
+    if not isinstance(declarations, DeclarationBindings) or not isinstance(history, DecodedHistoryStore):
+        raise TypeError('运行绑定需要DeclarationBindings和DecodedHistoryStore')
+    # 局部导入避免一般绑定入口提前加载来源读取协调器；不接受手造观测端点模型。
+    from .observed_ingestion import ObservedSourceScan
+    if type(observed_scans) is not tuple or any(type(scan) is not ObservedSourceScan for scan in observed_scans):
+        raise TypeError('无字段绑定证明需实际ObservedSourceScan tuple')
+    history._check('sealed')
+    if {item.name for item in declarations.sources} != set(history.validators):
+        raise ValueError('当前声明与实际历史来源不对应')
+    # 同一个真实owner贯穿预约、回放及返回，首次预算更新后取消不会落在保护块之外。
+    owner = DecodedBindingLease(history.budget)
+    try:
+        # 固定公式保持原额；单行读取另由原游标预算承担，不依据共享余额猜测所有权。
+        owner._history, owner._declarations = history, declarations
+        cost = 32768 + len(declarations.sources) * 8192 + len(declarations.signals) * 2048 + 16 * _metadata_bytes(
+            (declarations, tuple((item.description, item.request) for item in history.validators.values())))
+        _reserve_owned_ram(owner, cost, '_cost')
+        owner._evidence = []
+        completions = history.source_completions
+        for source in declarations.sources:
+            validator = history.validators[source.name]
+            description, request = validator.description, validator.request
+            owner._definitions = require_decoded_source_contract(declarations, source, description, request)
+            # 纯合同先拒绝无字段却有投影；随后仍以同一真实scan补完整空源时钟证明。
+            if not description.fields:
+                _require_empty_source_scan(source, history, observed_scans)
+            completion = completions[source.name]
+            if completion.session_id != declarations.session_id or not completion.source_eof:
+                raise ValueError('当前会话缺whole-source EOF事实')
+            sample_count, progress_count, final_progress = 0, 0, None
+            owner._reader = history.iter_records(source.name)
+            # 每次仅一条记录；样本经原游标核对来源/会话/投影/批次和实际SHA。
+            for owner._current in owner._reader:
+                if isinstance(owner._current, HistorySample):
+                    definition = owner._definitions[owner._current.name]
+                    labels = tuple(dict.fromkeys(label for _, label in definition.choices)) if definition.dtype is SignalDType.ENUM else ()
+                    if (owner._current.source_ref.field != definition.field or owner._current.value.dtype is not definition.dtype
+                            or owner._current.unit != definition.unit or owner._current.value.labels != labels):
+                        raise ResultFormatError('实际历史样本与当前绑定契约不符')
+                    sample_count += 1
+                elif isinstance(owner._current, HistoryProgress):
+                    progress_count += 1
+                    final_progress = owner._current
+                # 本行已完成校验；下次实际读可能自行EOF/清理，不跨该动作借留样本。
+                owner._current = None
+            # 提前close也会令for结束，但不能提供真实文件EOF证明。
+            if not owner._reader.verified_eof or final_progress != completion:
+                raise ResultFormatError('运行绑定未完成实际EOF核对或最终事实不一致')
+            owner._evidence.append(DecodedSourceEvidence(source=source.name, session_id=declarations.session_id,
+                description_sha256=_fingerprint(description), request_sha256=_fingerprint(request),
+                history_sha256=owner._reader.digest.hexdigest(), sample_count=sample_count, progress_count=progress_count,
+                projected_aliases=request.signal_names, observation_start_ns=description.observation_start_ns,
+                observation_end_ns=completion.observed_end_ns, source_eof=completion.source_eof))
+            # 原reader正常已在真实EOF处关闭；显式收尾成功后才结束唯一子责任槽。
+            owner._close_reader()
+        owner._bindings = DecodedBindings(declarations, tuple(owner._evidence))
+        owner._clear_temporary()
+        return owner
+    except BaseException as exc:
+        owner._failed = True
+        # reader构造/注册尚未返回时原工厂负责交出实际对象，禁止伪造半初始化owner。
+        child = getattr(exc, 'history_iterator_cleanup_owner', None)
+        if owner._reader is None and child is not None:
+            owner._reader = child
+        _cleanup_owner(owner, exc, 'decoded_binding_lease_cleanup_owner', '解码绑定工厂')
+        raise