chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/decoded_binding.py

@@ -0,0 +1,197 @@
+"""把实际封存解码历史的来源证据关联为可执行的轻量信号绑定。
+
+输入为DeclarationBindings及逐来源DecodedSourceEvidence，输出不可变的
+DecodedBindings与独立运行身份。先检查SHA格式、投影、会话和whole-source EOF，
+再把完整实际证据与原声明身份纳入摘要；运行依赖还须存在于实际读取投影中。
+声明身份只证明配置，实际证据应由执行层工厂完整重放封存历史后生成。
+单独构造合法SHA文本或EOF字段本身不证明文件已读取、校验或具有这些内容。
+本模块仅依赖标准库和核心声明模型，不持有样本历史、不读写文件或加载NumPy。
+模型无关闭资源；执行层持有元数据的预算与生命周期由对应lease负责。
+"""
+
+# 冻结证据和运行身份；不引入数组、来源适配器或磁盘操作。
+from dataclasses import dataclass, field
+from hashlib import sha256
+from .binding import SignalDefinition, _identity
+from .declarations import DeclarationBindings
+from .validation import require_identifier
+from ..timebase.conversion import require_int64_ns
+
+
+def _require_sha256(value: str, name: str) -> None:
+    """只校验固定SHA-256文本格式，不声称摘要来自已核实文件。
+
+    参数: value为64位小写十六进制文本；name为错误定位字段。
+    返回: None；无数据读取或字符串归一化。
+    异常: TypeError为非原生str；ValueError为长度或字符不符。
+    """
+    # 明确拒绝隐式str转换，保留工厂生成的规范摘要。
+    if type(value) is not str:
+        raise TypeError(f'{name}需要原生SHA-256字符串')
+    # 固定字符域同时拒绝大写、空白、换行和非十六进制字符。
+    if len(value) != 64 or any(character not in '0123456789abcdef' for character in value):
+        raise ValueError(f'{name}需要64位小写十六进制SHA-256')
+
+
+@dataclass(frozen=True)
+class DecodedSourceEvidence:
+    """保存工厂已核对的一份来源历史事实，字段冻结且不保存逐条样本。
+
+    三份摘要分别关联实际描述、请求和规范历史，不以文件名代替数据身份。
+    counts记录全源重放总量，projected_aliases保存实际请求投影顺序。
+    观测端点允许未知且保持None；EOF只接受整个来源结束，不能冒充批次结束。
+    模型仅验证证据结构，实际文件、字段、计数和摘要由执行层工厂负责核实。
+    """
+
+    source: str  # 当前声明中的唯一来源名。
+    session_id: str  # 当前实际重放所属会话。
+    description_sha256: str  # 实际来源描述及完整转换契约摘要。
+    request_sha256: str  # 本次读取范围、投影和批次声明摘要。
+    history_sha256: str  # 已核实规范历史字节摘要，不冒充原始日志摘要。
+    sample_count: int  # 全源实际样本总数，非负原生整数。
+    progress_count: int  # 全源实际批次进度记录数，至少包含最终EOF。
+    projected_aliases: tuple[str, ...]  # 实际读取的唯一简单别名，空投影合法。
+    observation_start_ns: int | None  # 原描述中的已知会话坐标首端；未知不补0。
+    observation_end_ns: int | None  # 最终EOF中的已知会话坐标终点；未知不补周期。
+    source_eof: bool  # 必须为True，表示整个配置来源已完成。
+
+    def __post_init__(self) -> None:
+        """检查固定身份、摘要格式、全源计数、投影和精确观测端点。
+
+        参数: 无，读取冻结字段；时间单位均为整数纳秒。
+        返回: None；合法整数端点规范为原生int，None保持未知。
+        异常: TypeError/ValueError为结构或事实矛盾；时间溢出异常原样传播。
+        副作用: 仅在构造期规范本对象端点，不访问来源或验证文件内容。
+        """
+        # 来源/会话名称不能借点号路径或任意对象绕过身份检查。
+        require_identifier(self.source, 'decoded.source')
+        require_identifier(self.session_id, 'decoded.session_id')
+        # 三种证据用途不同，逐项校验而不把任一摘要当另一个摘要使用。
+        for name, value in (('description_sha256', self.description_sha256),
+                            ('request_sha256', self.request_sha256),
+                            ('history_sha256', self.history_sha256)):
+            _require_sha256(value, f'decoded.{name}')
+        # bool不是计数；最终EOF至少对应一条实际进度记录。
+        if type(self.sample_count) is not int or self.sample_count < 0:
+            raise ValueError('decoded.sample_count需要非负原生int')
+        if type(self.progress_count) is not int or self.progress_count < 1:
+            raise ValueError('decoded.progress_count需要至少为1的原生int')
+        # 冻结投影顺序，不隐式消除重复或接受可变列表。
+        if type(self.projected_aliases) is not tuple:
+            raise TypeError('decoded.projected_aliases需要tuple')
+        for alias in self.projected_aliases:
+            require_identifier(alias, 'decoded.projected_alias')
+        if len(set(self.projected_aliases)) != len(self.projected_aliases):
+            raise ValueError('decoded.projected_aliases不能重复')
+        # 单个已知端点独立检查；不凭请求域或投影首样本推断未知端点。
+        start = None if self.observation_start_ns is None else require_int64_ns(self.observation_start_ns, 'decoded.observation_start_ns')
+        end = None if self.observation_end_ns is None else require_int64_ns(self.observation_end_ns, 'decoded.observation_end_ns')
+        if start is not None and end is not None and end < start:
+            raise ValueError('decoded来源观测终点早于起点')
+        # 普通批次结束不能升级为可执行证据，只接真正全源耗尽的明确bool。
+        if type(self.source_eof) is not bool or not self.source_eof:
+            raise ValueError('decoded证据需要真正whole-source EOF=True')
+        # 身份编码只接原生标量，整数规范保留精确坐标，不改变端点含义。
+        object.__setattr__(self, 'observation_start_ns', start)
+        object.__setattr__(self, 'observation_end_ns', end)
+
+
+@dataclass(frozen=True)
+class DecodedBindings:
+    """冻结当前声明与实际解码历史证据，供编译和两个数值context入口使用。
+
+    sources必须与声明来源一一对应，投影只能包含该来源声明的原信号别名。
+    identity使用decoded-binding-v1前缀与完整证据，不能与声明或memory身份混用。
+    resolve仅委托冻结声明；执行前仍检查实际投影和已有同步政策。
+    本对象不保存SourceSpec.rows，也不能交给材料化完整内存历史的快捷入口。
+    """
+
+    declarations: DeclarationBindings  # 原配置关系与同步依据；其身份仍只是声明证明。
+    sources: tuple[DecodedSourceEvidence, ...]  # 已核对来源事实，保留工厂的固定顺序。
+    identity: str = field(init=False)  # 声明加实际证据的独立SHA-256运行身份。
+
+    def __post_init__(self) -> None:
+        """检查来源/会话/投影归属，再生成与完整实际证据关联的身份。
+
+        参数: 无，读取declarations与sources；所有容器必须冻结。
+        返回: None；构造identity，不重新读取历史或改变声明。
+        异常: TypeError/ValueError为模型、重复/缺少来源、会话或投影冲突。
+        """
+        # 只接明确类型，声明或自由dict不能自行冒充实际来源证据。
+        if (not isinstance(self.declarations, DeclarationBindings) or type(self.sources) is not tuple
+                or any(not isinstance(item, DecodedSourceEvidence) for item in self.sources)):
+            raise TypeError('解码绑定需要DeclarationBindings和DecodedSourceEvidence tuple')
+        names = {item.source for item in self.sources}
+        if len(names) != len(self.sources) or names != {item.name for item in self.declarations.sources}:
+            raise ValueError('解码证据来源必须唯一且与声明完全对应')
+        for evidence in self.sources:
+            # 来源事实不能跨会话借用，即使字段/摘要文本相同也不接受。
+            if evidence.session_id != self.declarations.session_id:
+                raise ValueError('解码证据会话与当前声明不一致')
+            aliases = {item.name for item in self.declarations.signals if item.source == evidence.source}
+            if not set(evidence.projected_aliases).issubset(aliases):
+                raise ValueError('解码投影包含其他来源或未声明别名')
+        # 完整证据保留来源/请求/历史摘要、原范围、全源计数和实际投影；不只哈希配置。
+        payload = ('decoded-binding-v1', self.declarations.identity,
+                   tuple((item.source, item.session_id, item.description_sha256, item.request_sha256,
+                          item.history_sha256, item.sample_count, item.progress_count, item.projected_aliases,
+                          item.observation_start_ns, item.observation_end_ns, item.source_eof) for item in self.sources))
+        object.__setattr__(self, 'identity', sha256(_identity(payload).encode('utf-8')).hexdigest())
+
+    @property
+    def signals(self) -> tuple[SignalDefinition, ...]:
+        """读取当前冻结信号声明，不创建原始行或数值历史。
+
+        参数: 无。返回: SignalDefinition tuple。异常: 无；属性不能重新赋值。
+        """
+        return self.declarations.signals
+
+    @property
+    def projected_signals(self) -> tuple[SignalDefinition, ...]:
+        """按原声明顺序返回实际历史投影中的定义，不把未读取声明当作运行状态。
+
+        参数: 无，使用当前已校验sources中的projected_aliases。
+        返回: 原SignalDefinition对象组成的tuple；signals仍保留完整声明。
+        异常: 分配或取消错误原样传播。调用执行层须先为有限索引和tuple预付费用。
+        不读取历史、不改变绑定身份，也不把不同来源的投影误判为同步依据。
+        """
+        selected = None
+        try:
+            selected = {name for source in self.sources for name in source.projected_aliases}
+            return tuple(item for item in self.declarations.signals if item.name in selected)
+        finally:
+            selected = None
+
+    @property
+    def derived_names(self) -> tuple[str, ...]:
+        """读取当前统一名称空间中的派生别名。
+
+        参数: 无。返回: str tuple。异常: 无；不把派生名称当实际读入列。
+        """
+        return self.declarations.derived_names
+
+    def resolve(self, name: str) -> SignalDefinition:
+        """按当前声明查找原信号定义，不推断字段或执行数值转换。
+
+        参数: name为安全简单别名。返回: 当前SignalDefinition。
+        异常: ValueError为非法或未声明名称；查找本身不证明该别名已投影。
+        """
+        return self.declarations.resolve(name)
+
+    def require_synchronized(self, names: tuple[str, ...]) -> None:
+        """先证明全部实际依赖已读取，再应用既有多源同步政策。
+
+        参数: names为展开后的原信号依赖tuple；空依赖合法。
+        返回: None；不修改投影、偏移或同步声明。
+        异常: TypeError为错误容器；ValueError为未知/未投影依赖或同步缺项。
+        """
+        # 可变/无限依赖容器不能绕过冻结编译协议。
+        if type(names) is not tuple:
+            raise TypeError('解码联合依赖names必须为tuple')
+        evidence_by_source = {item.source: item for item in self.sources}
+        for name in names:
+            definition = self.resolve(name)
+            if name not in evidence_by_source[definition.source].projected_aliases:
+                raise ValueError(f'运行依赖未在实际解码投影中：{name}')
+        # offset数值或同名时基不替代原有核实同步依据；不另立宽松政策。
+        self.declarations.require_synchronized(names)

chronaxis/core/direct_message.py

@@ -0,0 +1,387 @@
+"""保存直接消息累计的版本化扫描证据，不声称消息历史曾写入磁盘。
+
+输入由执行层在同次真实扫描、EOF和读取资源关闭后提取；本模块仅校有限结构，
+不读CAN/DBC、不重算信号、不认证手造对象。旧signal_stream_sha256明确对应全部
+声明信号的规范HistorySample/HistoryProgress流，既非原文件SHA，也非消息仓SHA。
+新输入证据单独保存全部原时间及实际保留计算记录的传输内容摘要；不生成普通
+信号样本，不以零样本数或旧摘要字段冒充整套信号检查，也不覆盖未传输的帧载荷。
+全原帧观测、投影和指标ID选择分别保留，避免把信号样本数误作原帧数。结果解码时
+重新执行严格校验；身份由全部字段及独立版本生成，不借用MessageBindings身份。
+"""
+
+from dataclasses import dataclass, field
+
+from .message_binding import _hash_parts
+from .validation import require_identifier, require_text
+from ..timebase.conversion import require_int64_ns
+
+
+def _text(value, name, *, identifier=False):
+    """检查原生非空文本。参数: 原值、字段名及名称开关。返回: None。异常: 原类型/文本错误。"""
+    if type(value) is not str:
+        raise TypeError(name + '需要原生str')
+    (require_identifier if identifier else require_text)(value, name)
+
+
+def _sha(value, name):
+    """检查规范SHA文本，不把标签冒充摘要。参数: 原值及字段名。返回: None。异常: 类型/格式错误。"""
+    _text(value, name)
+    if len(value) != 64 or any(char not in '0123456789abcdef' for char in value):
+        raise ValueError(name + '需要64位小写SHA-256')
+
+
+@dataclass(frozen=True)
+class DirectMessageEvidence:
+    """冻结一次已完成扫描的有限事实；构造成功本身不证明实际读取发生。"""
+
+    source: str  # 原计划中的CAN来源名。
+    session_id: str  # 同次请求的会话身份。
+    decoder_profile: str  # 同次READY确认的旧解码profile。
+    read_identity: str  # 实际read的UUID，不用于稳定输入身份。
+    input_identity: str  # 原来源声明的输入身份，不冒充原文件内容SHA。
+    source_contract_sha256: str  # 来源配置、时基、偏移和输入声明的规范摘要。
+    description_sha256: str  # 原adapter描述的规范摘要。
+    request_sha256: str  # 本次全部别名、请求范围及批上限的规范摘要。
+    signal_stream_sha256: str  # 已校验信号样本/进度流摘要；不存在对应消息历史文件。
+    projected_aliases: tuple[str, ...]  # 原请求的完整别名顺序，允许空投影。
+    progress_count: int  # 实际验证的进度记录数，含最终EOF记录。
+    sample_count: int  # 已校验信号样本数，多信号时不同于原帧数。
+    observed_frame_count: int  # 全部原yield数，包括不匹配指标或没有信号的帧。
+    first_time_ns: int | None  # 全原帧首个映射时间，空源为None。
+    last_time_ns: int | None  # 全原帧最后映射时间，不补采样周期。
+    observed_start_ns: int | None  # 来源实际观测范围起点，可保声明的更早起点。
+    observed_end_ns: int | None  # 真实EOF确认的观测终点。
+    calculation_frame_ids: tuple[int, ...]  # 指标请求的去重原ID，非全部读取帧集合。
+    source_eof: bool  # 必须True；工厂还需核实际进程结束和read关闭。
+    evidence_kind: str = 'can-direct-scan-v1'  # 与消息仓证据完全独立的固定版本。
+    identity: str = field(init=False)  # 全字段版本化SHA，含本次read UUID。
+
+    def __post_init__(self):
+        """核扫描范围、真实EOF标志和固定选择域，再计算独立身份。
+
+        参数: 全部构造字段。返回: None，时间规范为原生int，identity为全字段SHA。
+        异常: TypeError/ValueError为结构矛盾；时间越界、编码及取消错误原样传播。
+        执行工厂还须核同scan/read/request及预算归属；此模型不开放假历史字段。
+        """
+        for name in ('source', 'session_id'):
+            _text(getattr(self, name), 'direct.' + name, identifier=True)
+        for name in ('decoder_profile', 'read_identity', 'input_identity'):
+            _text(getattr(self, name), 'direct.' + name)
+        if type(self.evidence_kind) is not str or self.evidence_kind != 'can-direct-scan-v1':
+            raise ValueError('直接消息证据只支持can-direct-scan-v1')
+        for name in ('source_contract_sha256', 'description_sha256', 'request_sha256', 'signal_stream_sha256'):
+            _sha(getattr(self, name), 'direct.' + name)
+        if type(self.projected_aliases) is not tuple:
+            raise TypeError('直接扫描投影需要tuple')
+        for alias in self.projected_aliases:
+            _text(alias, 'direct.projected_alias', identifier=True)
+        if len(set(self.projected_aliases)) != len(self.projected_aliases):
+            raise ValueError('直接扫描投影不能重复')
+        for name in ('progress_count', 'sample_count', 'observed_frame_count'):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError('direct.' + name + '需要非负原生int')
+        if not self.progress_count or self.source_eof is not True:
+            raise ValueError('直接扫描证据需要完整EOF及至少一次进度记录')
+        if not self.projected_aliases and self.sample_count:
+            raise ValueError('空投影不能有信号样本')
+        for name in ('first_time_ns', 'last_time_ns', 'observed_start_ns', 'observed_end_ns'):
+            value = getattr(self, name)
+            if value is not None:
+                object.__setattr__(self, name, require_int64_ns(value, 'direct.' + name))
+        if self.observed_frame_count == 0:
+            if self.first_time_ns is not None or self.last_time_ns is not None or self.sample_count:
+                raise ValueError('全空扫描不能有原帧首末或信号样本')
+        elif (self.first_time_ns is None or self.last_time_ns is None
+                or self.observed_start_ns is None or self.observed_end_ns is None
+                or not self.observed_start_ns <= self.first_time_ns <= self.last_time_ns <= self.observed_end_ns):
+            raise ValueError('非空直接扫描需有序首末及包含原帧的观测范围')
+        if (self.observed_start_ns is not None and self.observed_end_ns is not None
+                and self.observed_start_ns > self.observed_end_ns):
+            raise ValueError('直接扫描观测范围不能回退')
+        if type(self.calculation_frame_ids) is not tuple or not self.calculation_frame_ids:
+            raise TypeError('直接累计指标帧ID需要非空tuple')
+        previous = -1
+        for frame_id in self.calculation_frame_ids:
+            if type(frame_id) is not int or not 0 <= frame_id <= 0x1fffffff or frame_id <= previous:
+                raise ValueError('直接累计帧ID须为严格递增且范围合法的原生int')
+            previous = frame_id
+        parts = None
+        try:
+            # 用长度前缀hash编码每字段；嵌套tuple先明确数量，不以文本拼接猜边界。
+            parts = (self.evidence_kind, self.source, self.session_id, self.decoder_profile,
+                self.read_identity, self.input_identity, self.source_contract_sha256,
+                self.description_sha256, self.request_sha256, self.signal_stream_sha256,
+                str(len(self.projected_aliases)), *self.projected_aliases,
+                str(self.progress_count), str(self.sample_count), str(self.observed_frame_count),
+                *(str(value) if value is not None else 'none' for value in
+                    (self.first_time_ns, self.last_time_ns, self.observed_start_ns, self.observed_end_ns)),
+                str(len(self.calculation_frame_ids)), *(str(value) for value in self.calculation_frame_ids), 'true')
+            object.__setattr__(self, 'identity', _hash_parts(parts))
+        finally:
+            parts = None
+
+
+@dataclass(frozen=True)
+class DirectMessageInputEvidence:
+    """冻结按实际需求完成读取的输入事实，与旧普通信号扫描证据分开。
+
+    原时间摘要按原序连接每帧大端float64字节，保留正负零；记录摘要连接每条
+    已严格解包记录的四字节长度及JSON字节，两者均不包含批头，故不依赖分批。
+    它们不是BLF文件SHA，也不证明未保留帧的载荷；实际投影范围由请求、描述、
+    所需别名和指标ID共同标识。构造仅检查有限结构，完成工厂仍须核同次读取、
+    全部时间映射、EOF与资源成功关闭，并先预约模型和身份计算的内存。
+    """
+
+    source: str  # 计划中的CAN来源名称。
+    session_id: str  # 同次读取和累计所属的会话身份。
+    decoder_profile: str  # 实际READY确认的旧解码profile。
+    read_identity: str  # 同次真实read UUID，不用于跨运行稳定输入身份。
+    input_identity: str  # 原来源输入声明身份，不冒充BLF内容SHA。
+    source_contract_sha256: str  # 来源配置、时基、偏移与输入声明的规范摘要。
+    description_sha256: str  # 实际来源描述，包含解码策略和字段选择范围。
+    request_sha256: str  # 实际请求字段、范围、批上限等的规范摘要。
+    original_timestamps_sha256: str  # 全部原帧时间字节流SHA，包含未保留帧的时间。
+    retained_records_sha256: str  # 保留记录长度及JSON字节流SHA，仅覆盖实际投影内容。
+    required_aliases: tuple[str, ...]  # 本次实际计算所需别名顺序，常量指标允许为空。
+    observed_frame_count: int  # 全部原yield数量，不限于目标ID或有效计算。
+    retained_record_count: int  # 严格解包的实际保留记录数，不等同求值或贡献数。
+    first_time_ns: int | None  # 全原帧首个映射时间；空输入为None。
+    last_time_ns: int | None  # 全原帧最后映射时间，不补采样周期。
+    observed_start_ns: int | None  # 实际观测范围起点，可包括声明的更早起点。
+    observed_end_ns: int | None  # 真实EOF确认的观测终点。
+    calculation_frame_ids: tuple[int, ...]  # 指标请求的去重原ID，严格递增。
+    source_eof: bool  # 只能为True；工厂另核真实EOF和成功关闭。
+    evidence_kind: str = 'can-direct-input-v2'  # 与旧信号流及消息历史证据不同的版本。
+    identity: str = field(init=False)  # 全部字段及版本的SHA，包含本次read UUID。
+
+    def __post_init__(self):
+        """核实际选择、两路内容摘要及完整读取范围，计算独立版本身份。
+
+        参数: 全部构造字段；计数为非负原生int，时间为可规范化的int64纳秒。
+        返回: None；时间规范为原生int，identity写入全字段版本化SHA。
+        异常: TypeError/ValueError为结构矛盾，时间溢出、编码或取消错误原样传播。
+        无文件或进程操作；SHA文本合法不等于此构造器认证了实际输入内容。
+        """
+        # 输入身份与读取身份保持原含义，不把同名旧证据或自由标签当成新版本。
+        for name in ('source', 'session_id'):
+            _text(getattr(self, name), 'direct_input.' + name, identifier=True)
+        for name in ('decoder_profile', 'read_identity', 'input_identity'):
+            _text(getattr(self, name), 'direct_input.' + name)
+        if type(self.evidence_kind) is not str or self.evidence_kind != 'can-direct-input-v2':
+            raise ValueError('直接输入证据只支持can-direct-input-v2')
+        for name in ('source_contract_sha256', 'description_sha256', 'request_sha256',
+                'original_timestamps_sha256', 'retained_records_sha256'):
+            _sha(getattr(self, name), 'direct_input.' + name)
+
+        # 空别名不等于空记录：纯参数表达式仍按实际selector消息求值。
+        if type(self.required_aliases) is not tuple:
+            raise TypeError('直接输入所需别名需要tuple')
+        for alias in self.required_aliases:
+            _text(alias, 'direct_input.required_alias', identifier=True)
+        if len(set(self.required_aliases)) != len(self.required_aliases):
+            raise ValueError('直接输入所需别名不能重复')
+        for name in ('observed_frame_count', 'retained_record_count'):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError('direct_input.' + name + '需要非负原生int')
+        if self.retained_record_count > self.observed_frame_count:
+            raise ValueError('保留计算记录数不能超过全部原帧数')
+        if self.source_eof is not True:
+            raise ValueError('直接输入证据需要真实完整EOF')
+
+        # 两路都是原字节流SHA；零项的规范值已知，不能用任意摘要假装空输入。
+        empty_sha256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+        if not self.observed_frame_count and self.original_timestamps_sha256 != empty_sha256:
+            raise ValueError('无原帧时原时间摘要必须为空字节流SHA-256')
+        if not self.retained_record_count and self.retained_records_sha256 != empty_sha256:
+            raise ValueError('无保留记录时记录摘要必须为空字节流SHA-256')
+
+        # 先规范时间再比较。空来源可保声明范围，但不伪造首末原帧时间。
+        for name in ('first_time_ns', 'last_time_ns', 'observed_start_ns', 'observed_end_ns'):
+            value = getattr(self, name)
+            if value is not None:
+                object.__setattr__(self, name, require_int64_ns(value, 'direct_input.' + name))
+        if (self.observed_start_ns is None) != (self.observed_end_ns is None):
+            raise ValueError('直接输入观测范围起终必须同时存在或同时为空')
+        if not self.observed_frame_count:
+            if self.first_time_ns is not None or self.last_time_ns is not None:
+                raise ValueError('全空直接输入不能有原帧首末时间')
+        elif (self.first_time_ns is None or self.last_time_ns is None
+                or self.observed_start_ns is None or self.observed_end_ns is None
+                or not self.observed_start_ns <= self.first_time_ns <= self.last_time_ns <= self.observed_end_ns):
+            raise ValueError('非空直接输入需有序首末及包含原帧的观测范围')
+        if (self.observed_start_ns is not None and self.observed_end_ns is not None
+                and self.observed_start_ns > self.observed_end_ns):
+            raise ValueError('直接输入观测范围不能回退')
+
+        # ID只表示指标选择，不声称全部原帧ID集合或所有帧都产生了计算记录。
+        if type(self.calculation_frame_ids) is not tuple or not self.calculation_frame_ids:
+            raise TypeError('直接输入指标帧ID需要非空tuple')
+        previous = -1
+        for frame_id in self.calculation_frame_ids:
+            if type(frame_id) is not int or not 0 <= frame_id <= 0x1fffffff or frame_id <= previous:
+                raise ValueError('直接输入帧ID须为严格递增且范围合法的原生int')
+            previous = frame_id
+        parts = None
+        try:
+            # 字段与tuple均有明确边界；把两个摘要分别绑定，不能互换后保留身份。
+            parts = (self.evidence_kind, self.source, self.session_id, self.decoder_profile,
+                self.read_identity, self.input_identity, self.source_contract_sha256,
+                self.description_sha256, self.request_sha256, self.original_timestamps_sha256,
+                self.retained_records_sha256, str(len(self.required_aliases)), *self.required_aliases,
+                str(self.observed_frame_count), str(self.retained_record_count),
+                *(str(value) if value is not None else 'none' for value in
+                    (self.first_time_ns, self.last_time_ns, self.observed_start_ns, self.observed_end_ns)),
+                str(len(self.calculation_frame_ids)), *(str(value) for value in self.calculation_frame_ids), 'true')
+            object.__setattr__(self, 'identity', _hash_parts(parts))
+        finally:
+            # 取消或编码失败不由本帧额外保留新身份tuple；外层负责模型费用恢复。
+            parts = None
+
+
+@dataclass(frozen=True)
+class DemandMessageInputEvidence:
+    """保存按需处理范围与实际输入，允许完全不采集时间。
+
+    source模式的时间摘要连接每帧float64字节，其他模式为None。记录摘要连接每条
+    已严格解包记录的四字节长度及JSON字节，两者均不包含批头，故不依赖分批。
+    它们不是BLF文件SHA，也不证明未保留帧的载荷；实际投影范围由请求、描述、
+    所需别名和指标ID共同标识。构造仅检查有限结构，完成工厂仍须核同次读取、
+    声明范围内的时间检查、EOF与资源成功关闭，并先预约模型和身份计算的内存。
+    """
+
+    source: str  # 计划中的CAN来源名称。
+    session_id: str  # 同次读取和累计所属的会话身份。
+    decoder_profile: str  # 实际READY确认的旧解码profile。
+    read_identity: str  # 同次真实read UUID，不用于跨运行稳定输入身份。
+    input_identity: str  # 原来源输入声明身份，不冒充BLF内容SHA。
+    source_contract_sha256: str  # 来源配置、时基、偏移与输入声明的规范摘要。
+    description_sha256: str  # 实际来源描述，包含解码策略和字段选择范围。
+    request_sha256: str  # 实际请求字段、范围、批上限等的规范摘要。
+    original_timestamps_sha256: str | None  # 只有source模式提供全部原帧时间SHA。
+    retained_records_sha256: str  # 保留记录长度及JSON字节流SHA，仅覆盖实际投影内容。
+    required_aliases: tuple[str, ...]  # 本次实际计算所需别名顺序，常量指标允许为空。
+    observed_frame_count: int  # 全部原yield数量，不限于目标ID或有效计算。
+    retained_record_count: int  # 严格解包的实际保留记录数，不等同求值或贡献数。
+    first_time_ns: int | None  # source为全来源首时间，selected为目标首时间，none未采集。
+    last_time_ns: int | None  # 对应采集范围的末时间，不补采样周期。
+    observed_start_ns: int | None  # 实际观测范围起点，可包括声明的更早起点。
+    observed_end_ns: int | None  # 真实EOF确认的观测终点。
+    calculation_frame_ids: tuple[int, ...]  # 指标请求的去重原ID，严格递增。
+    source_eof: bool  # 只能为True；工厂另核真实EOF和成功关闭。
+    time_scope: str  # none/selected/source，只描述实际采集范围。
+    input_check: str  # auto/full，实际worker握手认证的检查策略。
+    evidence_kind: str = 'can-demand-input-v1'  # 与旧信号流及消息历史证据不同的版本。
+    identity: str = field(init=False)  # 全部字段及版本的SHA，包含本次read UUID。
+
+    def __post_init__(self):
+        """核实际选择、两路内容摘要及完整读取范围，计算独立版本身份。
+
+        参数: 全部构造字段；计数为非负原生int，时间为可规范化的int64纳秒。
+        返回: None；时间规范为原生int，identity写入全字段版本化SHA。
+        异常: TypeError/ValueError为结构矛盾，时间溢出、编码或取消错误原样传播。
+        无文件或进程操作；SHA文本合法不等于此构造器认证了实际输入内容。
+        """
+        # 输入身份与读取身份保持原含义，不把同名旧证据或自由标签当成新版本。
+        for name in ('source', 'session_id'):
+            _text(getattr(self, name), 'direct_input.' + name, identifier=True)
+        for name in ('decoder_profile', 'read_identity', 'input_identity'):
+            _text(getattr(self, name), 'direct_input.' + name)
+        if type(self.evidence_kind) is not str or self.evidence_kind != 'can-demand-input-v1':
+            raise ValueError('直接输入证据只支持can-demand-input-v1')
+        for name in ('source_contract_sha256', 'description_sha256', 'request_sha256',
+                'retained_records_sha256'):
+            _sha(getattr(self, name), 'direct_input.' + name)
+
+        # 不采集全原时间时使用None，禁止空SHA或目标时间SHA冒充全时间证据。
+        if type(self.time_scope) is not str or self.time_scope not in ('none', 'selected', 'source'):
+            raise ValueError('按需输入时间范围仅none/selected/source')
+        if type(self.input_check) is not str or self.input_check not in ('auto', 'full'):
+            raise ValueError('按需输入检查范围仅auto/full')
+        if self.input_check == 'full' and self.time_scope != 'source':
+            raise ValueError('完整检查必须覆盖整个来源时间')
+        if self.time_scope == 'source':
+            _sha(self.original_timestamps_sha256, 'demand.original_timestamps_sha256')
+        elif self.original_timestamps_sha256 is not None:
+            raise ValueError('未采集全部原时间时不能声明全时间摘要')
+
+        # 空别名不等于空记录：纯参数表达式仍按实际selector消息求值。
+        if type(self.required_aliases) is not tuple:
+            raise TypeError('直接输入所需别名需要tuple')
+        for alias in self.required_aliases:
+            _text(alias, 'direct_input.required_alias', identifier=True)
+        if len(set(self.required_aliases)) != len(self.required_aliases):
+            raise ValueError('直接输入所需别名不能重复')
+        for name in ('observed_frame_count', 'retained_record_count'):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError('direct_input.' + name + '需要非负原生int')
+        if self.retained_record_count > self.observed_frame_count:
+            raise ValueError('保留计算记录数不能超过全部原帧数')
+        if self.source_eof is not True:
+            raise ValueError('直接输入证据需要真实完整EOF')
+
+        # 两路都是原字节流SHA；零项的规范值已知，不能用任意摘要假装空输入。
+        empty_sha256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+        if self.time_scope == 'source' and not self.observed_frame_count and self.original_timestamps_sha256 != empty_sha256:
+            raise ValueError('无原帧时原时间摘要必须为空字节流SHA-256')
+        if not self.retained_record_count and self.retained_records_sha256 != empty_sha256:
+            raise ValueError('无保留记录时记录摘要必须为空字节流SHA-256')
+
+        # 先规范时间再比较。空来源可保声明范围，但不伪造首末原帧时间。
+        for name in ('first_time_ns', 'last_time_ns', 'observed_start_ns', 'observed_end_ns'):
+            value = getattr(self, name)
+            if value is not None:
+                object.__setattr__(self, name, require_int64_ns(value, 'direct_input.' + name))
+        if (self.observed_start_ns is None) != (self.observed_end_ns is None):
+            raise ValueError('直接输入观测范围起终必须同时存在或同时为空')
+        if self.time_scope == 'none':
+            if any(getattr(self, name) is not None for name in
+                    ('first_time_ns', 'last_time_ns', 'observed_start_ns', 'observed_end_ns')):
+                raise ValueError('无时间输入不能伪造首末或观测范围')
+        elif self.time_scope == 'selected':
+            if self.observed_start_ns is not None or self.observed_end_ns is not None:
+                raise ValueError('目标记录范围不能冒充整个来源的观测范围')
+            if self.retained_record_count:
+                if self.first_time_ns is None or self.last_time_ns is None or self.first_time_ns > self.last_time_ns:
+                    raise ValueError('非空目标时间需有序首末')
+            elif self.first_time_ns is not None or self.last_time_ns is not None:
+                raise ValueError('没有目标记录不能声明目标首末时间')
+        elif not self.observed_frame_count:
+            if self.first_time_ns is not None or self.last_time_ns is not None:
+                raise ValueError('全空直接输入不能有原帧首末时间')
+        elif (self.first_time_ns is None or self.last_time_ns is None
+                or self.observed_start_ns is None or self.observed_end_ns is None
+                or not self.observed_start_ns <= self.first_time_ns <= self.last_time_ns <= self.observed_end_ns):
+            raise ValueError('全来源时间证明需包含全部原帧首末')
+
+        # 空来源也不能以声明边界绕过有序范围检查。
+        if (self.observed_start_ns is not None and self.observed_end_ns is not None
+                and self.observed_start_ns > self.observed_end_ns):
+            raise ValueError('按需输入观测范围不能回退')
+
+        # ID只表示指标选择，不声称全部原帧ID集合或所有帧都产生了计算记录。
+        if type(self.calculation_frame_ids) is not tuple or not self.calculation_frame_ids:
+            raise TypeError('直接输入指标帧ID需要非空tuple')
+        previous = -1
+        for frame_id in self.calculation_frame_ids:
+            if type(frame_id) is not int or not 0 <= frame_id <= 0x1fffffff or frame_id <= previous:
+                raise ValueError('直接输入帧ID须为严格递增且范围合法的原生int')
+            previous = frame_id
+        parts = None
+        try:
+            # 字段与tuple均有明确边界；把两个摘要分别绑定，不能互换后保留身份。
+            parts = (self.evidence_kind, self.source, self.session_id, self.decoder_profile,
+                self.read_identity, self.input_identity, self.source_contract_sha256,
+                self.description_sha256, self.request_sha256, self.time_scope, self.input_check,
+                self.original_timestamps_sha256 or 'not_collected',
+                self.retained_records_sha256, str(len(self.required_aliases)), *self.required_aliases,
+                str(self.observed_frame_count), str(self.retained_record_count),
+                *(str(value) if value is not None else 'none' for value in
+                    (self.first_time_ns, self.last_time_ns, self.observed_start_ns, self.observed_end_ns)),
+                str(len(self.calculation_frame_ids)), *(str(value) for value in self.calculation_frame_ids), 'true')
+            object.__setattr__(self, 'identity', _hash_parts(parts))
+        finally:
+            # 取消或编码失败不由本帧额外保留新身份tuple；外层负责模型费用恢复。
+            parts = None

chronaxis/core/export_interpolation.py

@@ -0,0 +1,54 @@
+"""计算离线导出的线性值；不改变分析中的向后保持、事件或积分语义。
+
+调用方已确定相邻有效端点、范围及最大间隔。参考实现用精确有理数计算后转
+float64；NumPy实现以一维longdouble数组计算后转float64，计算内核独立。
+整数纳秒先作精确相对差，避免把很大的绝对时间直接转浮点。输出为估计值，
+不声称恢复真实观测；无文件、预算或全局状态。
+"""
+
+from fractions import Fraction
+from math import isfinite
+import numpy as np
+
+
+def linear_reference(times, left_ns, right_ns, left_value, right_value):
+    """独立标量线性参考。参数: times有限ns tuple、相邻端点时间/数值。返回: float tuple。
+
+    异常: 时间/数值非法或结果不有限；只接受严格位于两个端点之间的目标。
+    """
+    if (not left_ns < right_ns or any(not left_ns < t < right_ns for t in times)
+            or not isfinite(left_value) or not isfinite(right_value)):
+        raise ValueError('插值需要有效有序两端与内部目标')
+    left,right = Fraction(left_value),Fraction(right_value)
+    result = tuple(float(left+(right-left)*Fraction(t-left_ns,right_ns-left_ns)) for t in times)
+    if any(not isfinite(value) for value in result):
+        raise ValueError('插值结果非有限')
+    return result
+
+
+def linear_numpy(times, left_ns, right_ns, left_value, right_value):
+    """独立数组线性计算。参数: 同reference。返回: shape(N,) float64 ndarray。
+
+    异常: 时间/值非法或结果不有限；数组副本限当前有限块，不使用object数组。
+    """
+    if (not left_ns < right_ns or any(not left_ns < t < right_ns for t in times)
+            or not isfinite(left_value) or not isfinite(right_value)):
+        raise ValueError('插值需要有效有序两端与内部目标')
+    # 先精确减绝对坐标再装箱，按相同时间权重对整块执行真实数组运算。
+    relative = np.asarray([t-left_ns for t in times],dtype=np.longdouble)
+    span=np.longdouble(right_ns-left_ns)
+    left,right=np.longdouble(left_value),np.longdouble(right_value)
+    # Windows longdouble可能就是float64；用较近端点的增量，减少两项乘法及抵消误差。
+    # 两个合法极大有限端点的差可能溢出，只在该明确中间状态采用凸组合。
+    with np.errstate(over='ignore'):
+        difference=right-left
+    if np.isfinite(difference):
+        from_right=np.asarray([right_ns-t for t in times],dtype=np.longdouble)
+        values=np.where(relative<=from_right,left+difference*(relative/span),
+                        right-difference*(from_right/span)).astype(np.float64)
+    else:
+        alpha=relative/span
+        values=np.asarray((1-alpha)*left+alpha*right,dtype=np.float64)
+    if not np.all(np.isfinite(values)):
+        raise ValueError('插值结果非有限')
+    return values