chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/results/artifact_exports.py

@@ -0,0 +1,212 @@
+"""拥有本次新增导出目录及有界索引，发布时只复制并核对实际文件。
+
+每个导出至多16个普通文件；片段数量增长只增加磁盘索引，不积累路径列表。
+仅请求完整性诊断时保存摘要；复制沿必要读取计算，普通运行核文件身份与大小。
+"""
+
+from pathlib import Path
+import os
+import stat
+from hashlib import sha256
+import json
+from .frame_sort import FrameSort
+from .budget import _reserve_owned_ram,_release_owned_ram,_cleanup_owner
+from .errors import ResultClosedError,ResultFormatError
+from .raw_exports import _write_all
+
+
+class ArtifactExportStore:
+    """保存一次会话的信号/报文导出及独立清单，不借用原数据reader。"""
+
+    def __init__(self,budget,path,session_id,device_label,*,integrity=True):
+        """创建独占目录及索引。参数: 预算/path/会话/设备。返回: owner。异常: 配置/IO/预算错。
+        """
+        if type(integrity) is not bool: raise TypeError('integrity必须为bool')
+        self._integrity=integrity; self.index_info=None
+        self._budget=budget; self.path=Path(path); self.session_id=session_id; self.device_label=device_label
+        self._held_cost=self._fixed_cost=0; self._sort=None; self._input=self._output=self._index=self._cursor=None
+        self.count=0; self.state='building'; self._closed=False
+        try:
+            if device_label not in ('home','work') or any(p.casefold()=='refprojects' for p in self.path.resolve().parts):
+                raise ValueError('新导出需要实际设备标签及新工作目录')
+            _reserve_owned_ram(self,524288,'_fixed_cost')
+            self.path.mkdir(parents=True,exist_ok=False)
+            try:
+                self._sort=FrameSort(self.path/'inventory',budget,integrity=integrity)
+            except BaseException as error:
+                self._sort=getattr(error,'frame_sort_cleanup_owner',None); raise
+        except BaseException as error:
+            _cleanup_owner(self,error,'artifact_export_store_cleanup_owner','导出索引构造'); raise
+
+    @property
+    def closed(self):
+        """读取真实关闭状态。参数: 无。返回: bool。异常: 无。
+        """
+        return self._closed
+
+    @property
+    def owned_ram(self):
+        """汇总本仓及索引实际费用供父层核账。参数: 无。返回: bytes。异常: 无。
+        """
+        return self._held_cost+(0 if self._sort is None else self._sort._held_cost)
+
+    def next_path(self):
+        """提供当前导出独占子目录。参数: 无。返回: Path。异常: 非building。
+        """
+        if self._closed or self.state!='building':
+            raise ResultClosedError('导出索引不能新增')
+        return self.path/f'export-{self.count:08d}'
+
+    def _close_slot(self,slot):
+        """真实close成功后撤槽。参数: slot责任名。返回: None。异常: 原close错，保槽重试。
+        """
+        owner=getattr(self,slot)
+        if owner is not None:
+            owner.close(); setattr(self,slot,None)
+
+    @staticmethod
+    def _identity(path):
+        """取得普通文件的替换/修改标识。参数: Path。返回: 四整数tuple。异常: 链接/非普通文件/IO。"""
+        info=path.lstat()
+        if path.is_symlink() or not stat.S_ISREG(info.st_mode):
+            raise ResultFormatError('导出内容必须为普通文件')
+        return (info.st_dev,info.st_ino,info.st_size,info.st_mtime_ns)
+
+    def _file(self,path,destination=None,expected=None,identity=None):
+        """必要复制时才读内容；请求摘要则在同次读取计算。参数: 路径/目标/大小摘要/身份。返回: 大小和可选摘要。"""
+        if self._input is not None or self._output is not None:
+            raise ResultClosedError('导出文件还有未清理句柄')
+        before=self._identity(path)
+        # 摘要模式会核实际内容，允许修复为原字节后重试；普通模式没有内容依据，仍拒身份变化。
+        if identity is not None and tuple(identity)!=before and not self._integrity:
+            raise ResultFormatError('导出文件已被替换或修改')
+        if expected is not None and before[2]!=expected[0]:
+            raise ResultFormatError('导出文件大小与登记不同')
+        if destination is None and not self._integrity:
+            return before[2],None
+        self._input=path.open('rb',buffering=0)
+        opened=os.fstat(self._input.fileno())
+        if (opened.st_dev,opened.st_ino,opened.st_size,opened.st_mtime_ns)!=before:
+            raise ResultFormatError('导出文件在打开时变化')
+        if destination is not None:
+            self._output=destination.open('xb',buffering=0)
+        digest=sha256() if self._integrity else None; count=0
+        while True:
+            block=self._input.read(65536)
+            if not block: break
+            count+=len(block)
+            if count>before[2]: raise ResultFormatError('导出文件超过登记大小')
+            if digest is not None: digest.update(block)
+            if self._output is not None:
+                self._budget.reserve_spool(len(block)); _write_all(self._output,block)
+        value=None if digest is None else digest.hexdigest()
+        if count!=before[2] or self._identity(path)!=before:
+            raise ResultFormatError('导出文件在读取时变化')
+        if expected is not None and expected[1] is not None and value!=expected[1]:
+            raise ResultFormatError('导出文件内容与登记摘要不同')
+        self._close_slot('_output'); self._close_slot('_input')
+        # 写成功和真实close已确认；不再把新目标整份回读一次。
+        return count,value
+
+    def append(self,export_type,scope,interval,*,segment_id=None,completed_files=None):
+        """登记刚生成目录中有限文件的实际身份。参数: 类型/范围/区间/片段ID。返回: None。异常: 文件/索引错。
+        """
+        path=self.next_path(); files=[]
+        # 内部writer交出的有限事实避免登记时再次扫描；旧调用未交事实则按原开关读取。
+        supplied=None if completed_files is None else {item['name']:item for item in completed_files}
+        if supplied is not None and len(supplied)>16: raise ValueError('导出文件事实超过上限')
+        try:
+            if export_type not in ('signal_csv','can_frames') or scope not in ('session','segments'):
+                raise ValueError('导出种类或范围错误')
+            for entry in path.iterdir():
+                if len(files)>=16 or not entry.is_file() or entry.is_symlink() or not entry.name.isascii():
+                    raise ValueError('导出目录只允许至多16个普通文件')
+                identity=self._identity(entry)
+                if supplied is None:
+                    size,digest=self._file(entry,identity=identity)
+                else:
+                    fact=supplied.pop(entry.name,None)
+                    if fact is None or fact['bytes']!=identity[2]:
+                        raise ResultFormatError('导出文件与writer事实不符')
+                    size,digest=fact['bytes'],fact.get('sha256') if self._integrity else None
+                    if self._integrity and (type(digest) is not str or len(digest)!=64):
+                        raise ResultFormatError('请求摘要但writer没有提供')
+                files.append(dict(name=entry.name,bytes=size,_identity=identity,
+                    **({} if digest is None else {'sha256':digest})))
+            if supplied: raise ResultFormatError('writer登记的文件缺失')
+            if not any(f['name']=='manifest.json' for f in files):
+                raise ValueError('导出缺完成清单')
+            self._sort.append((self.count,),dict(index=self.count,export_type=export_type,scope=scope,segment_id=segment_id,
+                interval=None if interval is None else [interval.start_ns,interval.end_ns],
+                directory=path.name,files=sorted(files,key=lambda f:f['name']),device_label=self.device_label))
+            self.count+=1
+        except BaseException as error:
+            self.state='failed'; error.artifact_export_store_cleanup_owner=self; raise
+
+    def seal(self):
+        """封口目录索引后才允许移交。参数: 无。返回: None。异常: 状态/排序IO错。
+        """
+        self.next_path(); self._sort.seal(); self.state='sealed'
+
+    def copy_to(self,destination):
+        """逐目录复制到新发布位置，按请求在同次读取核摘要。参数: 新结果根。返回: exports.jsonl路径。异常: IO/完整性错。
+        """
+        if self._closed or self.state!='sealed' or self._cursor is not None or self._index is not None:
+            raise ResultClosedError('导出索引未封口或有发布资源待恢复')
+        root=Path(destination)/'exports'; root.mkdir(exist_ok=False)
+        index=Path(destination)/'exports.jsonl'
+        index_digest=sha256() if self._integrity else None; index_bytes=0
+        self.index_info=None
+        try:
+            self._index=index.open('xb',buffering=0)
+            self._cursor=self._sort._read(self._sort.path/f'{self._sort.level}-0.jsonl')
+            count=0
+            for key,sequence,record in self._cursor:
+                if key!=[count] and key!=(count,):
+                    raise ResultFormatError('导出索引序号不连续')
+                if record['directory']!=f'export-{count:08d}':
+                    raise ResultFormatError('导出索引目录错误')
+                target=root/record['directory']; target.mkdir(exist_ok=False)
+                for entry in record['files']:
+                    name=entry['name']
+                    if Path(name).name!=name or '/' in name or '\\' in name or ':' in name:
+                        raise ResultFormatError('导出索引包含不安全文件名')
+                    self._file(self.path/record['directory']/name,target/name,
+                        (entry['bytes'],entry.get('sha256')),entry['_identity'])
+                    # 修改标识仅用于当前文件生命周期，不逐文件发布另一套证明。
+                    del entry['_identity']
+                payload=(json.dumps(record,ensure_ascii=False,allow_nan=False,sort_keys=True)+'\n').encode('utf-8')
+                self._budget.reserve_spool(len(payload)); _write_all(self._index,payload); count+=1
+                if index_digest is not None: index_digest.update(payload)
+                index_bytes+=len(payload)
+            if count!=self.count:
+                raise ResultFormatError('导出索引数量不符')
+            self._close_slot('_cursor'); self._close_slot('_index')
+            self.index_info=dict(name=index.name,bytes=index_bytes,
+                **({} if index_digest is None else {'sha256':index_digest.hexdigest()}))
+            return index
+        except BaseException as error:
+            error.artifact_export_store_cleanup_owner=self
+            try:
+                self.recover_copy()
+            except BaseException as cleanup:
+                error.add_note('导出复制清理失败: '+type(cleanup).__name__)
+            raise
+
+    def recover_copy(self):
+        """关闭失败发布句柄，可重新发布到另一新目录。参数: 无。返回: None。异常: 实际close错可重试。
+        """
+        for slot in ('_output','_input','_cursor','_index'):
+            self._close_slot(slot)
+        # 生成器已退出而真实close持续失败时，句柄仍登记在索引仓，重试必须处理它们。
+        if self._sort is not None:
+            while self._sort.handles:
+                self._sort._close_file(self._sort.handles[-1])
+
+    def close(self):
+        """真实关闭索引及IO后释放自己的费用，保留磁盘。参数: 无。返回: None。异常: 原close错。
+        """
+        if self._closed:
+            return
+        self.recover_copy(); self._close_slot('_sort')
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost'); self._closed=True

chronaxis/results/binding_metadata.py

@@ -0,0 +1,54 @@
+"""保存清单中的预设版本与最终角色，不读取来源或重新执行工程契约。
+
+输入是计划构建器已检查、运行层又与实际绑定核对的有限角色记录，输出为冻结
+快照。记录只有别名和契约追溯，不含样本或原配置。contract_status仅表示给定
+声明元数据通过了检查，不能证明方向、位置或物理语义已经由系统测量核实。
+本模块只依赖标准库与核心字段校验，无I/O、预算或状态副作用。
+"""
+
+# 完整信号定义由RunMetadata另存；角色快照只引用同一清单的实际简单别名。
+from dataclasses import dataclass
+from ..core.validation import require_identifier, require_text
+
+
+@dataclass(frozen=True)
+class PresetRoleMetadata:
+    """保留角色选择和声明契约版本，字段冻结且不代表物理事实已验。"""
+
+    role: str  # 原预设角色。
+    alias: str  # 最终实际信号别名。
+    resolution: str  # explicit或semantic_unique。
+    contract_version: str  # 实际检查的角色契约版本。
+    contract_status: str = 'checked_against_declared_metadata'  # 校验的是给定声明。
+
+    def __post_init__(self):
+        """校验有限字段，不执行角色契约。参数: 无。返回: None。异常: 类型或非法状态。"""
+        require_identifier(self.role, 'preset_role.role')
+        require_identifier(self.alias, 'preset_role.alias')
+        require_text(self.contract_version, 'preset_role.contract_version')
+        # 两种选择方式都先由原构建器完成，不接受未知方式或升级后的物理验证状态。
+        if self.resolution not in ('explicit', 'semantic_unique'):
+            raise ValueError('预设角色查找方式需explicit或semantic_unique')
+        if self.contract_status != 'checked_against_declared_metadata':
+            raise ValueError('预设角色状态只能说明已检查声明元数据')
+
+
+@dataclass(frozen=True)
+class PresetBindingMetadata:
+    """按原计划顺序保存一个预设的版本和全部角色，角色不可重复。"""
+
+    preset_id: str  # 原预设ID。
+    preset_type: str  # 原预设种类，不从名称推断领域事实。
+    version: str  # 原预设版本，与角色契约版本独立。
+    roles: tuple[PresetRoleMetadata, ...]  # 有限冻结记录，不含输入行。
+
+    def __post_init__(self):
+        """核快照及角色唯一性。参数: 无。返回: None。异常: 类型、空身份或重复角色。"""
+        require_identifier(self.preset_id, 'preset_binding.preset_id')
+        require_text(self.preset_type, 'preset_binding.preset_type')
+        require_text(self.version, 'preset_binding.version')
+        if type(self.roles) is not tuple or any(type(role) is not PresetRoleMetadata for role in self.roles):
+            raise TypeError('预设清单角色需冻结PresetRoleMetadata tuple')
+        # 模型只检查内部结构；运行层另证别名和定义属于本次实际输入。
+        if len({role.role for role in self.roles}) != len(self.roles):
+            raise ValueError('预设清单不能重复同一角色')

chronaxis/results/budget.py

@@ -0,0 +1,138 @@
+"""维护共享资源账本、自有RAM交易槽及未返回owner的有限清理协议。
+
+输入为显式正整数限额及申请bytes，输出为检查后的当前/峰值统计。
+RAM申请先校验再分配，释放只能抵销已申请金额；spool保留诊断文件，累计不释放。
+AnalysisRunner及执行组件共用账本登记数组nbytes、状态和历史存储费用；它不代表全进程RSS上限。
+三个资源事务helper只围绕直接预算调用登记实际归属，或委托真实owner.close，
+不创建来源、数组或文件。轻量累计器可复用这些协议，无需加载结果编解码和暂存。
+"""
+
+# 明确超限异常，首版不降采样、丢结果或偷改窗口。
+from .errors import BudgetExceededError
+
+
+def _reserve_owned_ram(owner, amount: int, slot: str) -> None:
+    """预约一笔RAM并按实际账本登记owner及指定槽位，覆盖成功后取消。
+
+    参数: owner已初始化_budget/_held_cost/slot；amount为bytes；slot为实际费用字段。
+    返回: None。异常: 原预算/取消传播，未实际入账不增加自有费用。
+    边界: 仅围绕一次单线程直接预算调用判断，不用子操作后的总额猜测借用费用。
+    """
+    # 预算回调可能先更新再抛异常，finally必须登记已成功的这一笔申请。
+    before = owner._budget.ram_bytes
+    try:
+        owner._budget.reserve_ram(amount)
+    finally:
+        if owner._budget.ram_bytes == before + amount:
+            owner._held_cost += amount
+            setattr(owner, slot, getattr(owner, slot) + amount)
+
+
+def _release_owned_ram(owner, amount: int, slot: str) -> None:
+    """抵销一笔实际自有RAM，释放前取消保留金额，释放后取消立即清账。
+
+    参数: owner持有实际_budget/_held_cost/slot；amount为bytes；slot为对应实际费用。
+    返回: None。异常: 原预算/取消传播，恢复后不得重复抵销已释放金额。
+    """
+    # 空槽不调用外部预算回调，也不把未付金额用于抵销其他owner的费用。
+    if amount == 0:
+        return
+    before = owner._budget.ram_bytes
+    try:
+        owner._budget.release_ram(amount)
+    finally:
+        if owner._budget.ram_bytes == before - amount:
+            owner._held_cost -= amount
+            setattr(owner, slot, getattr(owner, slot) - amount)
+
+
+def _cleanup_owner(owner, exc: BaseException, attribute: str, label: str) -> None:
+    """尝试关闭构造未返回的真实owner，持续失败将恢复句柄附在原异常。
+
+    参数: owner为实际部分构造对象；exc为原异常；attribute为恢复属性名；label为说明。
+    返回: None，不覆盖原异常。异常: 关闭错误记录在原异常notes中，不向外替换它。
+    """
+    # 至多两次处理瞬时关闭取消；持续故障保留原对象，调用方恢复后显式close。
+    for attempt in range(2):
+        try:
+            owner.close()
+            break
+        except BaseException as cleanup:
+            exc.add_note(f'{label}清理第{attempt + 1}次失败: {type(cleanup).__name__}')
+    if not (getattr(owner, '_closed', False) or getattr(owner, 'closed', False)):
+        setattr(exc, attribute, owner)
+        exc.add_note(f'释放恢复后调用{attribute}.close()')
+
+
+class ResourceBudget:
+    """保存限额与单线程共享计数；每次申请失败都保持原计数不变。"""
+
+    def __init__(self, memory_budget_bytes: int = 268435456, spool_quota_bytes: int | None = None):
+        """校验并初始化资源计数，不分配数组或创建文件。
+
+        参数: memory_budget_bytes为RAM估算bytes；spool_quota_bytes为可选累计限额。
+        返回: 新账本。异常: ValueError为bool、非正数或非原生int。
+        """
+        # 配置从计划传入也重新校验，不能把None磁盘配额解释为无限物理磁盘。
+        for value in (memory_budget_bytes, spool_quota_bytes):
+            if value is not None and (type(value) is not int or value <= 0):
+                raise ValueError('资源限额需要正原生int')
+        if memory_budget_bytes is None:
+            raise ValueError('RAM限额不能省略')
+        self.memory_budget_bytes = memory_budget_bytes
+        self.spool_quota_bytes = spool_quota_bytes
+        self.ram_bytes = self.peak_ram_bytes = self.spool_bytes = 0
+
+    def reserve_ram(self, amount: int) -> None:
+        """在分配前保守申请新层RAM，失败不修改账本。
+
+        参数: amount为非负原生int bytes。返回: None。
+        异常: ValueError为金额错误；BudgetExceededError为超限。
+        """
+        # 使用Python整数避免账本定宽溢出。
+        self._amount(amount)
+        if self.ram_bytes + amount > self.memory_budget_bytes:
+            raise BudgetExceededError(f'新分析层RAM估算超限: {self.ram_bytes}+{amount}>{self.memory_budget_bytes}')
+        self.ram_bytes += amount
+        self.peak_ram_bytes = max(self.peak_ram_bytes, self.ram_bytes)
+
+    def release_ram(self, amount: int) -> None:
+        """释放已有申请，不能凭负数或重复释放隐藏状态开销。
+
+        参数: amount为非负原生int bytes。返回: None。
+        异常: ValueError为金额错误或超出当前申请。
+        """
+        self._amount(amount)
+        if amount > self.ram_bytes:
+            raise ValueError('RAM释放超出当前申请')
+        self.ram_bytes -= amount
+
+    def reserve_spool(self, amount: int) -> None:
+        """写入前累计申请磁盘量，失败或部分写入也保守保留申请。
+
+        参数: amount为非负原生int bytes。返回: None。
+        异常: ValueError为金额错误；BudgetExceededError为累计超配额。
+        """
+        self._amount(amount)
+        if self.spool_quota_bytes is not None and self.spool_bytes + amount > self.spool_quota_bytes:
+            raise BudgetExceededError('累计磁盘暂存超过spool_quota_bytes')
+        self.spool_bytes += amount
+
+    @staticmethod
+    def _amount(amount: int) -> None:
+        """检查金额，防止布尔和负数影响预算。
+
+        参数: amount为申请金额。返回: None。异常: ValueError为非法金额。
+        """
+        if type(amount) is not int or amount < 0:
+            raise ValueError('资源金额需要非负原生int')
+
+    def snapshot(self) -> dict:
+        """返回独立的小型资源快照，不修改计数。
+
+        参数: 无。返回: 限额、当前/峰值RAM估算和累计spool预留。
+        异常: 无；整进程RSS不在此模型内。
+        """
+        return {'memory_budget_bytes': self.memory_budget_bytes, 'spool_quota_bytes': self.spool_quota_bytes,
+                'ram_estimated_bytes': self.ram_bytes, 'peak_ram_estimated_bytes': self.peak_ram_bytes,
+                'spool_reserved_bytes': self.spool_bytes, 'whole_process_rss': 'not_measured'}

chronaxis/results/can_metadata.py

@@ -0,0 +1,247 @@
+"""冻结同次CAN读取、原始暂存和DBC单位核对的结构化运行事实。
+
+CANUnitCheck只保存原声明与同次公开DBC单位的比较；CANSourceMetadata保存会话、
+profile、声明路径、实际read身份/进程、原帧数、映射首末、封口暂存SHA与累计费用、
+依赖/vendor版本证据及单位检查。CANFrameFormatNotice明确记录已授权的单向DBC声明
+差异，真实帧不转换。输入均为有限明确字段，输出冻结模型，不塞JSON
+字符串或伪造DBC内容哈希。缺DBC单位仍保None/空原值并记declared，不提升为verified。
+本模块仅校类型、内部一致性与唯一性，无路径访问、DBC解析、进程、预算或I/O副作用；
+构造成功不能证明来源已读完、进程已退出、暂存已核验或物理单位已测量。
+"""
+
+# 只登记三类有限冻结模型；运行侧提供真实证据，声明侧不重新读取来源。
+from dataclasses import dataclass
+from ..core.validation import require_identifier, require_text
+from ..legacy.records import PROFILE_ID, LegacyCANField
+from ..timebase.conversion import require_int64_ns
+
+
+def _integer(value, name, minimum=0):
+    """校验非负原生整数，拒绝bool和外部整数替代。
+
+    参数: value为候选值；name为字段名；minimum为含端点下限。返回: None。
+    异常: TypeError为非原生int，ValueError为小于下限。
+    """
+    if type(value) is not int:
+        raise TypeError(name + '需要原生int')
+    if value < minimum:
+        raise ValueError(name + '低于允许下限')
+
+
+def _sha256(value, name):
+    """校验64位hex摘要原文，不把路径、版本或随机身份冒充内容SHA。
+
+    参数: value为候选摘要；name定位字段。返回: None，保大小写原值。
+    异常: TypeError/ValueError为类型、长度或非hex字符；不读取文件证明实际内容。
+    """
+    if type(value) is not str:
+        raise TypeError(name + '需要str')
+    if len(value) != 64 or any(char not in '0123456789abcdefABCDEF' for char in value):
+        raise ValueError(name + '需要64位hex SHA256')
+
+
+def _pairs(value, name, hashes=False):
+    """检查版本或vendor摘要的冻结键值对，不能重复键或接受可变字典。
+
+    参数: value为tuple[tuple[str,str],...]；name定位字段；hashes指值是否需要SHA。
+    返回: None。异常: TypeError/ValueError为结构、空文本、重复键或非法SHA。
+    """
+    if type(value) is not tuple:
+        raise TypeError(name + '需要tuple')
+    keys = set()
+    for pair in value:
+        if type(pair) is not tuple or len(pair) != 2 or any(type(item) is not str for item in pair):
+            raise TypeError(name + '需要原生文本二元tuple')
+        require_text(pair[0], name + '.key')
+        require_text(pair[1], name + '.value')
+        if pair[0] in keys:
+            raise ValueError(name + '键重复')
+        keys.add(pair[0])
+        if hashes:
+            _sha256(pair[1], name + '.sha256')
+
+
+@dataclass(frozen=True)
+class CANUnitCheck:
+    """保原声明单位及同次DBC单位；verified只表示非空原文本完全相同。"""
+
+    alias: str  # 同一运行signal_bindings中的简单别名，不是DBC信号名称。
+    input_unit: str  # 原解码输入单位，不是额外线性转换后的输出单位。
+    dbc_unit: str | None  # 同次公开signal.unit原值，None/空字符串均原样保留。
+    status: str  # verified或declared；不表示物理测量已验。
+
+    def __post_init__(self):
+        """校验单位比较事实，不去空格、换算或重复施加DBC缩放。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为字段类型或状态与原单位冲突。
+        """
+        require_identifier(self.alias, 'can_unit.alias')
+        require_text(self.input_unit, 'can_unit.input_unit')
+        if self.dbc_unit is not None and type(self.dbc_unit) is not str:
+            raise TypeError('can_unit.dbc_unit需要str或None')
+        if type(self.status) is not str or self.status not in ('verified', 'declared'):
+            raise ValueError('CAN单位状态仅verified/declared')
+        missing = self.dbc_unit is None or self.dbc_unit == ''
+        if self.status == 'verified' and (missing or self.dbc_unit != self.input_unit):
+            raise ValueError('verified需要非空DBC单位与原input_unit完全相同')
+        if self.status == 'declared' and not missing:
+            raise ValueError('declared仅用于DBC单位None或空字符串')
+
+
+@dataclass(frozen=True)
+class CANFrameFormatNotice:
+    """保存DBC声明FD但选中实际经典CAN的有限提示，不证明任意原帧均匹配。
+
+    alias关联本次实际信号声明，其余字段完整保存原定位和同次DBC帧型。
+    仅单向差异合法；真实帧仍由读取层原通道/ID/标准/FD校验，不改变原帧。
+    """
+
+    alias: str  # 同次实际signal_bindings简单别名。
+    channel: int  # 原定位通道，不冒称DBC能证明物理通道。
+    signal: str  # 同次DBC核对的原信号名称，保全文。
+    frame_id: int  # 与原显式定位一致的数值报文ID。
+    is_extended: bool  # 原标准/扩展定位；本兼容不放宽该项。
+    dbc_is_fd: bool  # 同次DBC声明，唯一允许值为原生True。
+    requested_is_fd: bool  # 显式或自动识别得到经典CAN，唯一允许False；不改写原帧。
+    code: str = 'dbc_fd_classic_selector'  # 稳定机器码，不接受其他自由兼容政策。
+
+    def __post_init__(self):
+        """核固定提示及原定位类型，不访问DBC或把声明当实际帧转换。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为非法类型、方向或固定code。
+        """
+        require_identifier(self.alias, 'can_frame_format.alias')
+        LegacyCANField(self.channel, self.signal, self.frame_id,
+                       self.is_extended, self.requested_is_fd)
+        if type(self.dbc_is_fd) is not bool or type(self.is_extended) is not bool:
+            raise TypeError('DBC帧型提示需要原生bool')
+        if self.dbc_is_fd is not True or self.requested_is_fd is not False:
+            raise ValueError('仅兼容DBC FD声明与显式经典CAN定位')
+        if type(self.code) is not str or self.code != 'dbc_fd_classic_selector':
+            raise ValueError('CAN帧型提示code非法')
+
+
+@dataclass(frozen=True)
+class CANSourceMetadata:
+    """保存一条真实read的有限事实；内部模型校验不认证实际读取或资源释放。"""
+
+    source: str  # 同计划安全来源名。
+    session_id: str  # 同次分析会话，运行清单另核会话归属。
+    legacy_profile: str  # 固定sclicer-functions-v1。
+    path: str  # 原单BLF路径文本，不在元数据模型中resolve。
+    dbc_path: str  # 同次原load_file路径，不是DBC内容哈希。
+    channel: int  # 明确单通道，非负原生int。
+    read_identity: str  # 同次实际read身份，不与随机运行ID或物理行号混淆。
+    worker_pid: int  # 实际子进程正整数PID，不能用bool表示。
+    frame_count: int  # 原yield总数，不是投影信号样本数。
+    first_ns: int | None  # 原帧映射后首坐标；空来源为None。
+    last_ns: int | None  # 原帧映射后末坐标；不伪造请求domain的终点。
+    raw_store_path: str | None  # 本次封口原始帧暂存路径；计划不需原帧导出时为None。
+    raw_store_sha256: str | None  # 仅实际保存原帧时给整流SHA，不冒充原BLF或DBC的SHA。
+    raw_spool_bytes: int  # 本raw_store累计预留字节，不是RSS或已归还磁盘。
+    dependency_versions: tuple[tuple[str, str], ...]  # 同次READY版本事实，键唯一。
+    vendor_sha256: tuple[tuple[str, str], ...]  # 同次三原模块证据，键唯一、值为SHA。
+    unit_checks: tuple[CANUnitCheck, ...]  # 每别名单位事实，不能重复别名。
+    frame_format_notices: tuple[CANFrameFormatNotice, ...] = ()  # 无差异保空，不新增旧序列化键或费用。
+    decode_scope: str = 'all'  # 默认不新增旧清单键；requested由同次READY认证。
+    decode_frame_ids: tuple[int, ...] = ()  # requested实际固定ID集合，覆盖本次所需字段和触发报文。
+    decoded_values_policy: str = 'all_values-v1'  # 旧全字段默认不加清单键；按需只传实际所需字段。
+    input_check: str = 'full'  # 旧记录默认完整检查，新策略由实际READY确认。
+    time_scope: str = 'source'  # none/selected/source，首末范围不可混称。
+    check_policy_version: str | None = None  # 仅新按需策略给版本。
+    retained_record_count: int | None = None  # 实际保留原记录数。
+    full_check_count: int = 0  # 非原生输入完整检查回退数。
+    selected_first_ns: int | None = None  # 仅selected提供目标首时间。
+    selected_last_ns: int | None = None  # 目标末时间，不是文件末时间。
+
+    def __post_init__(self):
+        """核标识、计数/首末、摘要及冻结子记录，不访问原输入或暂存。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为类型、范围或内部事实冲突，
+            OverflowError为非空首末超int64；不把声明校验写成实际EOF/哈希验证成功。
+        """
+        require_identifier(self.source, 'can_source.source')
+        require_identifier(self.session_id, 'can_source.session_id')
+        for name in ('path', 'dbc_path', 'read_identity'):
+            require_text(getattr(self, name), 'can_source.' + name)
+        if type(self.legacy_profile) is not str or self.legacy_profile != PROFILE_ID:
+            raise ValueError('CAN清单仅支持sclicer-functions-v1')
+        _integer(self.channel, 'can_source.channel')
+        _integer(self.worker_pid, 'can_source.worker_pid', 1)
+        _integer(self.frame_count, 'can_source.frame_count')
+        _integer(self.raw_spool_bytes, 'can_source.raw_spool_bytes')
+        # 明确记录实际解码范围；bool与int相等不能被tuple比较误当成同一策略。
+        if type(self.decode_scope) is not str or self.decode_scope not in ('all', 'requested'):
+            raise ValueError('CAN解码方式仅all/requested')
+        if (type(self.decode_frame_ids) is not tuple or len(self.decode_frame_ids) > 4096
+                or any(type(value) is not int or not 0 <= value <= 0x1fffffff for value in self.decode_frame_ids)):
+            raise TypeError('CAN固定解码集合需至多4096个29位原生整数的tuple')
+        if (any(left >= right for left, right in zip(self.decode_frame_ids, self.decode_frame_ids[1:]))
+                or self.decode_scope == 'all' and self.decode_frame_ids):
+            raise ValueError('CAN固定解码ID需严格递增，all不另设固定集合')
+        # 原requested历史可以保全字段；新字段投影必须明确声明，不能冒称all。
+        if (type(self.decoded_values_policy) is not str
+                or self.decoded_values_policy not in ('all_values-v1', 'requested_fields-v1')):
+            raise ValueError('CAN解码字段策略仅all_values-v1/requested_fields-v1')
+        if self.decode_scope == 'all' and self.decoded_values_policy != 'all_values-v1':
+            raise ValueError('all解码方式必须保留all_values-v1字段策略')
+        # 空来源不制造零长实际观测；非空真实单点可first==last，保int64原坐标。
+        if self.input_check not in ('auto', 'full') or self.time_scope not in ('none', 'selected', 'source'):
+            raise ValueError('CAN实际检查/时间范围非法')
+        if self.input_check == 'full' and self.time_scope != 'source':
+            raise ValueError('完整检查必须提供全来源时间范围')
+        if self.input_check == 'auto' and self.check_policy_version != 'demand-check-v1':
+            raise ValueError('按需检查需要明确策略版本')
+        if self.retained_record_count is not None:
+            _integer(self.retained_record_count, 'can_source.retained_record_count')
+            if self.retained_record_count > self.frame_count:
+                raise ValueError('保留记录数超过原读取数')
+        _integer(self.full_check_count, 'can_source.full_check_count')
+        if self.full_check_count > self.frame_count:
+            raise ValueError('完整回退数超过原读取数')
+        if self.time_scope != 'selected' and (self.selected_first_ns is not None or self.selected_last_ns is not None):
+            raise ValueError('只有目标时间模式能声明目标首末')
+        if self.time_scope != 'source':
+            if self.first_ns is not None or self.last_ns is not None:
+                raise ValueError('未采集全部时间不能声明全来源首末')
+            if self.time_scope == 'selected':
+                if not self.retained_record_count:
+                    # 没有目标记录（或没有已核实的目标计数）不能制造目标时间范围。
+                    if self.selected_first_ns is not None or self.selected_last_ns is not None:
+                        raise ValueError('没有目标记录不能声明目标首末时间')
+                else:
+                    require_int64_ns(self.selected_first_ns)
+                    require_int64_ns(self.selected_last_ns)
+                    if self.selected_first_ns > self.selected_last_ns:
+                        raise ValueError('目标时间首末回退')
+        elif self.frame_count == 0:
+            if self.first_ns is not None or self.last_ns is not None:
+                raise ValueError('空CAN来源首末必须None')
+        else:
+            if type(self.first_ns) is not int or type(self.last_ns) is not int:
+                raise TypeError('非空CAN首末需要原生int64')
+            require_int64_ns(self.first_ns, 'can_source.first_ns')
+            require_int64_ns(self.last_ns, 'can_source.last_ns')
+            if self.first_ns > self.last_ns:
+                raise ValueError('CAN首坐标不能晚于末坐标')
+        # 不保存原帧是计划明确选择的事实；不能填假路径或空文件SHA冒充已保存。
+        # 三项必须同时表示未保存，实际保留的仓仍严格检查原路径和摘要。
+        if self.raw_store_path is None:
+            if self.raw_store_sha256 is not None or self.raw_spool_bytes != 0:
+                raise ValueError('未保存原帧时路径/SHA必须为None且原帧暂存费用为0')
+        else:
+            require_text(self.raw_store_path, 'can_source.raw_store_path')
+            _sha256(self.raw_store_sha256, 'can_source.raw_store_sha256')
+        _pairs(self.dependency_versions, 'can_source.dependency_versions')
+        _pairs(self.vendor_sha256, 'can_source.vendor_sha256', hashes=True)
+        if type(self.unit_checks) is not tuple or any(type(item) is not CANUnitCheck for item in self.unit_checks):
+            raise TypeError('CAN单位清单需要CANUnitCheck tuple')
+        if len({item.alias for item in self.unit_checks}) != len(self.unit_checks):
+            raise ValueError('CAN单位清单别名重复')
+        if (type(self.frame_format_notices) is not tuple
+                or any(type(item) is not CANFrameFormatNotice for item in self.frame_format_notices)):
+            raise TypeError('CAN帧型提示需要冻结CANFrameFormatNotice tuple')
+        aliases = {item.alias for item in self.unit_checks}
+        if (len({item.alias for item in self.frame_format_notices}) != len(self.frame_format_notices)
+                or any(item.alias not in aliases or item.channel != self.channel for item in self.frame_format_notices)):
+            raise ValueError('CAN帧型提示不能重复、跨来源通道或引用未知别名')