chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/sources/can_spec.py

@@ -0,0 +1,179 @@
+"""声明固定旧函数链的有序BLF来源，并保存解码样本的完整CAN定位。
+
+LegacyCANSpec接收首个Path、可选连续paths、一个DBC Path、明确通道、TimebaseSpec和原浮点秒
+表示，输出冻结声明；构造只查类型、后缀和纳秒偏移，不open/stat/resolve，不加载
+旧模块、CAN库或DBC，也不猜时区、单位、方向、实际观测范围和解码质量。
+CANSourceRef在通用会话/来源/field上保留原路径、profile、通道、信号、实际帧型、
+yield序号、原浮点秒及时间量化标志。field是ID/信号及可选帧类型的规范JSON，
+不能把原名称当DSL变量、隐藏改名、再次施加DBC缩放或声称原物理行号。
+仅依赖通用模型和基于标准库的CAN读取记录协议；无文件、子进程、reader或预算生命周期。
+"""
+
+# 冻结声明和显式路径不访问文件；原浮点秒只检查有限性，不恢复丢失精度。
+from dataclasses import dataclass
+from math import isfinite
+from pathlib import Path
+from ..core.models import SourceRef, TimebaseSpec
+from ..core.validation import require_identifier, require_text
+from ..legacy.records import (LegacyCANField, MAX_WIRE_BYTES, PROFILE_ID, decode_packet, field_from_dict)
+from ..timebase.conversion import require_int64_ns
+
+
+def _nonnegative_integer(value, name):
+    """检查原生非负通道/序号，不接受bool或外部整数子类替代。
+
+    参数: value为候选值；name为字段诊断名。返回: None，不重编号或转换类型。
+    异常: TypeError为非原生int，ValueError为负数；无I/O。
+    """
+    if type(value) is not int:
+        raise TypeError(name + '需要原生int')
+    if value < 0:
+        raise ValueError(name + '需要非负整数')
+
+
+def can_field_from_key(text):
+    """从严格规范JSON恢复完整原定位，复用CAN定位模型，不解析DBC。
+
+    参数: text为LegacyCANField.key生成的原生str，UTF-8包不超过65536字节。
+    返回: LegacyCANField，保信号名大小写、点号及可选帧类型，不读取DBC。
+    异常: TypeError/ValueError/UnicodeError为类型、JSON、重复键、字段、数值或非规范键；
+        不接受仅语义相同但空白、键序或转义不同的文本，不eval或反序列化任意对象。
+    """
+    if type(text) is not str:
+        raise TypeError('CAN field需要规范JSON str')
+    # 先以字符数拒绝明显超长输入，再核UTF-8字节、JSON树和唯一定位字段。
+    if not text or len(text) > MAX_WIRE_BYTES:
+        raise ValueError('CAN field为空或超过wire上限')
+    field = field_from_dict(decode_packet(text.encode('utf-8')))
+    if text != field.key:
+        raise ValueError('CAN field不是规范JSON定位键')
+    return field
+
+
+@dataclass(frozen=True)
+class LegacyCANSpec:
+    """冻结有序同格式BLF、单通道和单DBC声明，不认证输入文件或实际旧链能力。"""
+
+    name: str  # 当前计划来源的安全简单名称，不是DBC消息名。
+    path: Path  # 首个BLF声明；不扫描目录，连续文件由paths显式提供。
+    dbc_path: Path  # 同次worker原load_file的唯一DBC声明，不在此读取。
+    channel: int  # 明确单通道，非负原生int，不猜缺失通道。
+    timebase: TimebaseSpec  # 完整时基声明，来源名称相同不自动证明同步。
+    unit: str = 's'  # 原函数返回浮点秒，首版只接受s，不按文件名推断。
+    offset_ns: int = 0  # 明确int64固定纳秒偏移，不更改原timestamp。
+    legacy_profile: str = PROFILE_ID  # 唯一冻结sclicer-functions-v1，不自动回退profile。
+    decode_scope: str = 'requested'  # 默认仅处理本次实际需要的报文/字段；all显式保留完整诊断。
+    input_check: str = 'auto'  # auto按实际消费者检查；full显式检查全部原帧和时间。
+
+    paths: tuple[Path, ...] = ()  # 显式连续BLF；空tuple沿用path单文件，首项必须等于path。
+    decode_policy: str = 'legacy'  # 新版本默认strict；旧调用保原宽松解码。
+
+    @property
+    def input_paths(self):
+        """取得原序文件。参数: 无。返回: tuple。异常: 无；不扫描目录。"""
+        return self.paths or (self.path,)
+
+    def __post_init__(self):
+        """检查静态来源约束，路径和时基对象均原样保留。
+
+        参数: 无，读取本冻结声明字段。返回: None。
+        异常: TypeError为路径/通道/时基/单位/profile/偏移/解码范围类型错误；ValueError为名称、
+            后缀、通道、单位、profile或解码/检查范围不符；OverflowError为offset_ns超出int64。
+        副作用: 无open/stat/resolve/DBC/依赖加载，不核实存在性或实际BLF内容。
+        """
+        require_identifier(self.name, 'can.name')
+        # 后缀只限定本次支持范围；DBC保Path，不额外猜格式、改路径或检查内容。
+        if not isinstance(self.path, Path) or not isinstance(self.dbc_path, Path):
+            raise TypeError('CAN path/dbc_path需要Path')
+        if self.path.suffix.lower() != '.blf':
+            raise ValueError('首版CAN仅声明单BLF来源')
+        from ..legacy.decode_policy import validate_decode_policy
+        validate_decode_policy(self.decode_policy)
+        if (type(self.paths) is not tuple or len(self.paths) > 4096
+                or any(not isinstance(p, Path) or p.suffix.lower() != '.blf' for p in self.paths)
+                or self.paths and self.paths[0] != self.path):
+            raise ValueError('连续BLF需要原序Path tuple且首项等于path')
+        _nonnegative_integer(self.channel, 'can.channel')
+        if not isinstance(self.timebase, TimebaseSpec):
+            raise TypeError('CAN timebase需要TimebaseSpec')
+        if type(self.unit) is not str or type(self.legacy_profile) is not str:
+            raise TypeError('CAN unit/legacy_profile需要原生str')
+        if self.unit != 's' or self.legacy_profile != PROFILE_ID:
+            raise ValueError('CAN仅支持原浮点秒与sclicer-functions-v1')
+        # 通用时间校验允许其他Integral；此静态契约额外要求原生int而非隐式归一化。
+        if type(self.offset_ns) is not int:
+            raise TypeError('CAN offset_ns需要原生int')
+        require_int64_ns(self.offset_ns, 'can.offset_ns')
+        # 本模型只检查选项值；requested与整个计划的兼容性由静态规划统一检查。
+        if type(self.decode_scope) is not str:
+            raise TypeError('CAN decode_scope需要原生str')
+        if self.decode_scope not in ('all', 'requested'):
+            raise ValueError('CAN decode_scope需要all或requested')
+        # 检查策略与解码范围分开；完整计划负责确定实际时间消费者。
+        if type(self.input_check) is not str:
+            raise TypeError('CAN input_check需要原生str')
+        if self.input_check not in ('auto', 'full'):
+            raise ValueError('CAN input_check需要auto或full')
+
+
+@dataclass(frozen=True)
+class CANSourceRef(SourceRef):
+    """保留一次原yield对应样本的CAN身份，不替代实际绑定或质量检查。
+
+    继承session_id/source_name/field；实际定位须满足field声明的可选类型约束。
+    yield_sequence从0开始且保原来源顺序，同刻消息不会被去重；不是物理行号。
+    原timestamp和量化标志同时保留，不用新纳秒坐标覆盖原浮点诊断。
+    """
+
+    path: str  # 原单BLF路径文本，是否真实打开由实际read证明。
+    profile: str  # 实际固定旧函数链标识。
+    channel: int  # 明确来源通道。
+    signal: str  # 原DBC信号名，不裁剪、替换点号或改大小写。
+    frame_id: int  # 原报文ID，与field一致。
+    is_extended: bool  # 原定位标准/扩展帧标志。
+    is_fd: bool  # 原定位经典CAN/FD标志。
+    yield_sequence: int  # 0起原函数yield序号，不是legacy_sum的历史求值序号。
+    timestamp: float  # 有限原浮点秒，可保负数和-0.0；精度已损失时不能恢复。
+    time_quantized: bool  # 显式时间转换是否按纳秒量化，不等于浮点精度完好。
+
+    def __post_init__(self):
+        """校验通用身份与完整原定位相等，不访问路径或重新解码。
+
+        参数: 无。返回: None，全部原声明保持冻结。
+        异常: TypeError/ValueError/UnicodeError为身份、profile、JSON定位、序号、原时间
+            或量化标志非法，或field与附加定位冲突；没有失效补零或隐式别名。
+        """
+        super().__post_init__()
+        require_text(self.path, 'can_ref.path')
+        if type(self.profile) is not str or self.profile != PROFILE_ID:
+            raise ValueError('CANSourceRef仅支持sclicer-functions-v1')
+        # field保留用户的可选选择器，附加帧类型记录实际帧；无需逐条重新解析JSON。
+        _nonnegative_integer(self.channel, 'can_ref.channel')
+        if type(self.frame_id) is not int or type(self.signal) is not str:
+            raise TypeError('CANSourceRef实际ID需要int、信号名需要str')
+        if type(self.is_extended) is not bool or type(self.is_fd) is not bool:
+            raise TypeError('CANSourceRef必须保存实际帧类型bool')
+        actual = LegacyCANField(self.channel, self.signal, self.frame_id, self.is_extended, self.is_fd).key
+        # 规范键按名称排序，这两个字段都在signal之前；只删除完整键值及逗号。
+        # 信号文本中的双引号会被JSON转义，因此不能误删文本中的相似片段。
+        extended = '"is_extended":' + str(self.is_extended).lower() + ','
+        fd = '"is_fd":' + str(self.is_fd).lower() + ','
+        if type(self.field) is not str or self.field not in (
+                actual, actual.replace(extended, ''), actual.replace(fd, ''),
+                actual.replace(extended, '').replace(fd, '')):
+            raise ValueError('CANSourceRef实际帧与绑定定位不一致')
+        _nonnegative_integer(self.yield_sequence, 'can_ref.yield_sequence')
+        if type(self.timestamp) is not float:
+            raise TypeError('CANSourceRef timestamp需要原生float秒')
+        if not isfinite(self.timestamp):
+            raise ValueError('CANSourceRef timestamp必须有限')
+        if type(self.time_quantized) is not bool:
+            raise TypeError('CANSourceRef time_quantized需要bool')
+
+    @property
+    def evaluation_index(self):
+        """提供本次原yield位置的只读别名，明确不声称legacy_sum求值流已存在。
+
+        参数: 无。返回: 与yield_sequence完全相同的int。异常: 无；不产生额外求值或计数。
+        """
+        return self.yield_sequence

chronaxis/sources/can_updates.py

@@ -0,0 +1,160 @@
+"""把三种原始报文入口的必要值交付给同一个逐消息计算模型。
+
+投影只保存有限字段定位和可共享的来源引用。BLF交付的键是DBC信号名，
+文本入口交付的键是规范字段；转换后均为原DBC信号名，不保留载荷副本、
+原时间字符串或第二套时间。LegacyDecodedUpdate是已有计算模型的名称，
+使用它不代表复现旧程序的缓存行为。
+"""
+
+from types import MappingProxyType
+
+from ..core.models import SourceRef
+from ..core.validation import require_identifier
+from ..legacy.records import LegacyCANField
+from ..legacy.updates import LegacyDecodedUpdate, LegacyUntimedUpdate
+
+
+def require_message_keys(keys, *, channel=None):
+    """校验有限触发声明。参数: keys完整定位tuple、可选来源通道。返回: 原tuple。异常: ValueError。"""
+    if type(keys) is not tuple or len(keys) > 4096:
+        raise ValueError('消息触发定位需要最多4096项tuple')
+    for key in keys:
+        if (type(key) is not tuple or len(key) != 4 or type(key[0]) is not int or key[0] < 0
+                or type(key[1]) is not int or key[2] is not None and type(key[2]) is not bool
+                or key[3] is not None and type(key[3]) is not bool
+                or not 0 <= key[1] <= (0x7ff if key[2] is False else 0x1fffffff)
+                or channel is not None and key[0] != channel):
+            raise ValueError('消息触发定位需要合法通道、ID、扩展及FD标志，且属于当前来源通道')
+    return keys
+
+
+class CANUpdateProjection:
+    """按完整报文身份索引所需字段；同一帧的多个别名只传一次物理值。"""
+
+    def __init__(self, source, session_id, fields, *, message_keys=(), clock_fields=()):
+        """建立有限投影，不读取DBC或输入文件。
+
+        参数: source/session_id为来源和会话；fields为所需LegacyCANField元组；
+            message_keys为无值公式仍需触发的(channel,id,extended,fd)元组；
+            clock_fields只借DBC候选确定驱动帧，不加入值解码或值输出。
+        返回: None；初始化实例状态。异常: TypeError/ValueError为字段、身份或同帧信号定位冲突。
+        """
+        if (type(fields) is not tuple or type(clock_fields) is not tuple
+                or any(type(field) is not LegacyCANField for field in (*fields,*clock_fields))):
+            raise TypeError('消息投影需要LegacyCANField tuple')
+        require_identifier(source, 'message.source')
+        require_identifier(session_id, 'message.session_id')
+        groups = {}
+        for key in require_message_keys(message_keys):
+            groups.setdefault(key, {})
+        self._value_fields = frozenset(fields)
+        for field in dict.fromkeys((*fields, *clock_fields)):
+            key = (field.channel, field.frame_id, field.is_extended, field.is_fd)
+            group = groups.setdefault(key, {})
+            if field.signal in group and group[field.signal] != field:
+                raise ValueError('同一报文信号存在不同定位')
+            group[field.signal] = field
+        # 引用只标识必需的来源及代表字段，逐帧序号由已有更新模型保存一次。
+        self._groups = MappingProxyType({key: (tuple(group.values()),
+            SourceRef(session_id, source, next(iter(group.values())).key if group else '__raw_message__'))
+            for key, group in groups.items()})
+        self.source = source
+        self._seen = {}
+        self._resolved = {}
+        self._dbc_frames = {}
+        self.compatibility_fields = {}
+
+    def configure_metadata(self, facts):
+        """安装同次DBC的有限候选。参数: facts字段事实。返回: None。异常: 非法定位错误。
+        """
+        from ..legacy.records import field_from_dict
+        self._dbc_frames = {field_from_dict(dict(fact['locator'])): tuple(tuple(pair) for pair in fact['dbc_frames'])
+                            for fact in facts if 'dbc_frames' in fact}
+
+    def for_read(self, facts):
+        """为单次读取隔离已见状态。参数: facts同次DBC事实。返回: 新投影。异常: 元数据错误。
+        """
+        from copy import copy
+        result = copy(self)
+        result._seen = {}
+        result._resolved = {}
+        result.compatibility_fields = {}
+        result.configure_metadata(facts)
+        return result
+
+    def _matching(self, frame):
+        """匹配四种可选选择器，记录唯一实际身份。参数: frame。返回: 字段和引用或None。异常: 迟到歧义。
+        """
+        if frame.is_remote_frame or frame.is_error_frame:
+            return None
+        frame_key = (frame.channel, frame.arbitration_id, frame.is_extended_id, frame.is_fd)
+        if frame_key in self._resolved:
+            return self._resolved[frame_key]
+        actual = (frame.is_extended_id, frame.is_fd)
+        fields, reference = {}, None
+        for extended in (frame.is_extended_id, None):
+            for fd in (frame.is_fd, None):
+                key = (frame.channel, frame.arbitration_id, extended, fd)
+                item = self._groups.get(key)
+                if item is None:
+                    continue
+                # 候选定义里没有该信号的另一种同ID帧属于无关输入，不制造失效更新。
+                selected = []
+                for field in item[0]:
+                    candidates = self._dbc_frames.get(field)
+                    if candidates is not None and not any(e == actual[0] and (f == actual[1] or f and not actual[1])
+                                                          for e, f in candidates):
+                        continue
+                    selected.append(field)
+                    if candidates is not None and not actual[1] and (actual[0], False) not in candidates:
+                        self.compatibility_fields[field] = actual[0]
+                if item[0] and not selected:
+                    continue
+                for identity_key in selected or (key,):
+                    previous = self._seen.get(identity_key)
+                    if previous is not None and previous != actual:
+                        missing = 'is_extended' if previous[0] != actual[0] else 'is_fd'
+                        raise ValueError('同一报文绑定匹配多种实际帧，请补充 ' + missing)
+                    self._seen[identity_key] = actual
+                fields.update((field, None) for field in selected)
+                reference = reference or item[1]
+        if reference is None:
+            return None
+        result = (tuple(fields), reference)
+        # 只缓存已声明且成功匹配的身份，最多每声明四种，不随无关报文数量增长。
+        self._resolved[frame_key] = result
+        return result
+
+    def accepts_frame(self, frame):
+        """判断是否有值或触发需求。参数: 原帧。返回: bool。异常: 非原帧属性错。"""
+        return self._matching(frame) is not None
+
+    def fields_for(self, frame):
+        """定位目标数据帧，未知ID/其他通道或帧型不参与本投影。
+
+        参数: frame为实际读取器交付且已校验的原帧。返回: 字段元组，非目标为空。
+        异常: 非原帧对象缺少必需属性时AttributeError；不吞读取错误。
+        """
+        item = self._matching(frame)
+        return () if item is None else item[0]
+
+    def build(self, frame, sequence, values, time_ns, *, canonical_keys=False):
+        """只拣选计算字段，复用已有有时间/无时间更新及其严格值检查。
+
+        参数: frame为原帧，sequence为本来源原序号，values为已解码映射，
+            time_ns为实际映射时间或明确未采集的None；canonical_keys说明文本字段键。
+        返回: LegacyDecodedUpdate/LegacyUntimedUpdate；非目标数据帧返回None。
+        异常: 类型/数值/身份错误原样传播，不缓存前条值补齐缺失。
+        """
+        if type(canonical_keys) is not bool:
+            raise TypeError('canonical_keys需要bool')
+        item = self._matching(frame)
+        if item is None:
+            return None
+        fields, reference = item
+        selected = {field.signal: values.get(field.key if canonical_keys else field.signal)
+                    for field in fields if field in self._value_fields}
+        update_type = LegacyUntimedUpdate if time_ns is None else LegacyDecodedUpdate
+        return update_type(time_ns, self.source, frame.channel, frame.arbitration_id,
+                    frame.is_extended_id, frame.is_fd, frame.is_remote_frame,
+                    frame.is_error_frame, reference, sequence, sequence, selected)

chronaxis/sources/csv_spec.py

@@ -0,0 +1,133 @@
+"""声明独立已解码信号表的格式，并保存每个CSV样本的位置。
+
+SignalCSVSpec接收有序路径、时间列、时间单位、时区、编码、分隔符和
+缺失标记，输出冻结配置；构造仅检查声明，不打开文件或根据后缀猜格式。
+CSVSourceRef在通用来源引用上增加文件路径、记录末物理行和原始单元格
+文本，供实际读取后追溯。时间量化诊断单独保留，不从文件名推断观测范围。
+"""
+
+# encoding合法性可以静态检查，不读取输入表内容。
+import codecs
+# 冻结配置与继承来源引用，不创建可变全局状态。
+from dataclasses import dataclass
+# 绝对日期没有自身时区偏移时需要明确tzinfo，不能采用机器当前时区。
+from datetime import tzinfo
+# 文件路径只作声明，不查询文件状态、不打开文件，也不重新排序。
+from pathlib import Path
+# 每样本引用沿用已验收的会话/来源/字段校验。
+from ..core.models import SourceRef, TimebaseSpec
+# 时间类型区别于表示单位，不能互相猜测。
+from ..core.types import TimeType
+# 字段保留原文，来源名是简单标识。
+from ..core.validation import require_identifier, require_text
+# offset遵守精确纳秒范围。
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class SignalCSVSpec:
+    """保存已解码信号表的格式和时钟声明，保留paths的给定顺序。
+
+    name标识来源，paths指定连续输入文件；timebase给出相对公共起点或绝对
+    时钟，time_column与unit解释时间单元格，offset_ns是显式纳秒偏移。
+    timezone只用于缺少自身时区的绝对日期。encoding、sep和missing_values
+    明确表格解析规则；声明检查不会核实文件存在性或实际表头。
+
+    实际适配器把每行每个请求列当作一次观测。缺失文本精确匹配后转None，
+    表示明确缺失更新；旧Filter输出中的空白未更新含义须另按旧来源契约接入。
+    """
+
+    name: str  # 当前计划来源名。
+    paths: tuple[Path, ...]  # 明确连续文件顺序，不扫描目录自动排序。
+    timebase: TimebaseSpec  # relative公共起点/absolute明确声明。
+    time_column: str  # 原时间列名，必须在每个表头存在。
+    unit: str  # s/ms/us/ns或absolute的ISO8601。
+    offset_ns: int = 0  # 显式固定偏移，不能证明同步。
+    timezone: tzinfo | None = None  # ISO无offset时明确采用的时区。
+    encoding: str = 'utf-8'  # 不猜文件编码。
+    delimiter: str = ','  # 单字符分隔符，不自动sniff。
+    missing_values: tuple[str, ...] = ('',)  # 精确匹配原cell，不strip标记。
+
+    def __post_init__(self) -> None:
+        """检查表格格式与时间声明，保持路径和缺失标记的原顺序。
+
+        参数:
+            无。使用name、paths、timebase、time_column、unit、offset_ns、
+            timezone、encoding、sep和missing_values字段。
+        返回:
+            None。只检查冻结实例，不读取表头或数据。
+        异常:
+            TypeError: 路径、时区或声明结构类型错误。
+            ValueError: 时间单位、名称、分隔符或缺失标记不合法。
+            LookupError: 编码名称不受本机编码注册表支持。
+            OverflowError: offset_ns超出整数纳秒范围。
+        """
+        # 来源名必须是计划内安全别名。
+        require_identifier(self.name, 'csv.name')
+        # paths必须明确非空，不能接受字符串作为可迭代字符路径。
+        if not isinstance(self.paths, tuple) or not self.paths or any(not isinstance(path, Path) for path in self.paths):
+            # 不从目录猜测会话/文件顺序。
+            raise TypeError('csv.paths需要非空tuple[Path]')
+        # 必须明确时基/表示单位，ISO只用于absolute。
+        if not isinstance(self.timebase, TimebaseSpec) or self.unit not in ('s', 'ms', 'us', 'ns', 'ISO8601') or self.unit == 'ISO8601' and self.timebase.time_type is not TimeType.ABSOLUTE:
+            # 原始报文时间策略不在此通用表接口猜测。
+            raise ValueError('csv时基/时间单位错误')
+        # 原列名完整保留，不自动改名。
+        require_text(self.time_column, 'csv.time_column')
+        # 合法偏移也不会自动证明与另一来源已同步。
+        require_int64_ns(self.offset_ns, 'csv.offset_ns')
+        # 时区仅接受已经解析的显式tzinfo。
+        if self.timezone is not None and not isinstance(self.timezone, tzinfo):
+            # 配置解析层负责把地区时区名称或固定偏移文本转换为tzinfo。
+            raise TypeError('csv.timezone需要tzinfo')
+        # 编码名称是明确配置，查询注册表不会读取CSV文件。
+        require_text(self.encoding, 'csv.encoding')
+        # 未知编码在执行前报告，不尝试自动检测。
+        codecs.lookup(self.encoding)
+        # csv标准reader只接一个非换行分隔符。
+        if type(self.delimiter) is not str or len(self.delimiter) != 1 or self.delimiter in '\r\n':
+            # TSV可显式用tab，任意多字符分隔拒绝。
+            raise ValueError('csv.delimiter需要单个非换行字符')
+        # 标记可为空字符串但必须原生str、唯一冻结tuple。
+        if not isinstance(self.missing_values, tuple) or any(type(item) is not str for item in self.missing_values) or len(set(self.missing_values)) != len(self.missing_values):
+            # 不把未知格式猜为无效0。
+            raise ValueError('csv.missing_values需要唯一字符串tuple')
+
+
+@dataclass(frozen=True)
+class CSVSourceRef(SourceRef):
+    """保留单个已读取样本的文件位置和原始文本。
+
+    继承的session_id、source_name和field确定会话、来源及原字段。
+    path指出文件，line_number是CSV记录结束的物理行，time_text和value_text
+    保留原单元格文本；time_quantized标记时间是否发生纳秒量化。
+    引用不保存sequence，稳定原行序号由SignalSeries的sequence列另行保存。
+    引号内跨多行的记录以最后物理行为位置，不能把它解释成记录首行。
+    """
+
+    path: str  # 实际读取路径原文。
+    line_number: int  # csv reader给出的记录末物理行，1开始。
+    time_text: str  # 原时间cell文本。
+    value_text: str  # 原字段cell文本，解析异常诊断不丢原文。
+    time_quantized: bool  # 时间转换曾按纳秒half-even量化。
+
+    def __post_init__(self) -> None:
+        """检查继承的来源身份和CSV附加定位，不访问路径。
+
+        参数:
+            无。读取来源身份、path、line_number、time_text、value_text和time_quantized。
+        返回:
+            None。文本保持原样，缺失单元格允许value_text为空字符串。
+        异常:
+            TypeError或ValueError: 来源名称、字段、路径、正整数行号或附加字段类型错误。
+        副作用:
+            无文件访问；引用构造本身不能证明path已经成功打开。
+        """
+        # 基类校验会话/来源/原字段，不能省略而只留下行号。
+        super().__post_init__()
+        # 路径文本必须非空；是否成功打开由实际读取适配器另行核实。
+        require_text(self.path, 'csv_ref.path')
+        # 物理行号明确正数，不接受True或0。
+        if type(self.line_number) is not int or self.line_number <= 0 or type(self.time_text) is not str or type(self.value_text) is not str or type(self.time_quantized) is not bool:
+            # 缺失cell可以value_text为空，不因此丢来源。
+            raise ValueError('CSVSourceRef行号/文本/量化类型错误')

chronaxis/sources/descriptions.py

@@ -0,0 +1,65 @@
+"""把显式信号定义转成来源的静态字段描述。
+
+输入是来源名称、SignalDefinition元组和可选定位信息，输出FieldDescription
+元组。每项保留表达式别名、原字段、输出类型与单位，并保存转换、有效期、
+可选语义、方向、测量位置和枚举标签。内存来源与已解码CSV共用该转换。
+本模块不读取输入文件或DBC，也不核实声明是否与实际表头或物理测量一致。
+"""
+
+# 自由元数据仍使用JSON结构，类型在模型边界深冻结。
+from collections.abc import Mapping
+# 完整配置契约只保存稳定摘要，避免把原无效NaN等塞进JSON元数据。
+from hashlib import sha256
+# 明确绑定定义是已验收的配置契约。
+from ..core.binding import SignalDefinition, _identity
+from ..core.models import TimebaseSpec
+from ..timebase.conversion import require_int64_ns
+# enum固定域由声明提供，不能在batch内猜测。
+from ..core.types import SignalDType
+# 公开字段描述保留原定位，与表达式别名分开。
+from .models import FieldDescription, FieldLocation, JsonValue
+
+
+def source_timebase_identity(timebase: TimebaseSpec, offset_ns: int) -> str:
+    """为实际适配器使用的时基种类/原点/固定偏移生成独立摘要。
+
+    参数: timebase已校验TimebaseSpec；offset_ns为整数纳秒偏移。
+    返回: SHA256文本，仅标识配置，不证明物理时钟同步已核实。
+    异常: TypeError/OverflowError为未声明时基或非法偏移；不读取输入。
+    """
+    if not isinstance(timebase, TimebaseSpec):
+        raise TypeError('时基身份需要TimebaseSpec')
+    offset = require_int64_ns(offset_ns, 'source.offset_ns')
+    # 单凭相同ID不能证明相同起点；完整原点/种类进入配置指纹。
+    payload = ('source-timebase-v1', timebase.timebase_id, timebase.time_type.value, timebase.origin, offset)
+    return sha256(_identity(payload).encode('utf-8')).hexdigest()
+
+
+def describe_fields(source: str, signals: tuple[SignalDefinition, ...], locator: Mapping[str, JsonValue] | None = None) -> tuple[FieldDescription, ...]:
+    """逐项保存字段定位和转换声明，不把声明当作实际数据核实。
+
+    参数:
+        source (str): 当前来源名称。
+        signals (tuple[SignalDefinition, ...]): 该来源已解析的显式信号定义。
+        locator (Mapping | None): 可附加的静态定位信息，默认None，使用空对象。
+    返回:
+        tuple[FieldDescription, ...]。保持定义顺序，元数据和定位映射深度冻结。
+        valid_for_ns是有效值最多保持的时长声明；本函数不在此执行保持或过期判断。
+        原始CAN的None表示等待同次DBC周期解析，不表示无限保持。
+    异常:
+        TypeError或ValueError: 字段描述或定位信息不符合公共模型要求。
+    副作用:
+        无输入扫描；同一原字段的多个别名分别保留自己的显式转换。
+    """
+    # 未给定位时为空对象，不从路径猜通道/消息或工程语义。
+    location = {} if locator is None else locator
+    # 每别名描述自己的转换，允许同原字段显式不同映射。
+    return tuple(FieldDescription(item.name, FieldLocation(source, item.field, location), item.dtype, item.unit,
+                                  {'normalization_sha256': sha256(_identity(('normalization-v1', item.identity())).encode('utf-8')).hexdigest(),
+                                   'input_unit': item.input_unit, 'scale': item.scale, 'offset': item.offset,
+                                   'valid_for_ns': item.valid_for_ns, 'semantic_id': item.semantic_id, 'unit_status': item.unit_status,
+                                   'mapping_version': item.mapping_version, 'semantic_contract_version': item.semantic_contract_version,
+                                   'sign_convention': item.sign_convention, 'input_sign_convention': item.input_sign_convention,
+                                   'direction_factor': item.direction_factor, 'measurement_location': item.measurement_location,
+                                   'same_time_policy': item.same_time_policy,
+                                   'labels': tuple(dict.fromkeys(label for _, label in item.choices)) if item.dtype is SignalDType.ENUM else ()}) for item in signals)