chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/integral_terms_numpy.py

@@ -0,0 +1,127 @@
+"""用真实数组计算有限块的原序ZOH面积项，不在块内先求和或换单位。
+
+输入为无条件CalculationSeries/CalculationDefinition，输出只读(N-1,)面积/有效掩码与IntegralFacts。
+先裁剪int64端点，批量计算整数差、秒、乘积及非有限/下溢掩码，UNKNOWN不补正常零。
+整数到float的判据用独立NumPy转换核；覆盖归约独立，不调用标量面积或覆盖实现。
+元数据循环仅恢复未知Interval，不承担数值计算；不修改输入或读写文件。
+输出及临时数组需在调用方有限块workspace内消费；本纯核不提供独立内存上限。
+"""
+
+# 数值全部用真实ufunc/掩码/归约；只共享冻结事实和配置门槛。
+from dataclasses import dataclass
+import numpy as np
+from .integral_terms import IntegralFacts, require_integral_terms
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric_numpy import DTYPES, NumericArray, to_float_numpy
+from .types import QualityFlag as Q
+
+
+@dataclass(frozen=True)
+class NumpyIntegralTerms:
+    """持有只读面积及显式有效掩码，数组保持原区间顺序。"""
+
+    areas: np.ndarray  # float64形状(N-1,)，无效位置0只是存储。
+    valid: np.ndarray  # bool形状(N-1,)，True位置可归约。
+    facts: IntegralFacts  # 当前块原请求/覆盖/诊断和完整真实来源。
+
+    def __post_init__(self):
+        """检查真实一维同长只读数组，不接受object或非有限占位。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为数组或事实错误。
+        """
+        # 只接受同形真实数值列，返回后禁止原地改写冻结面积事实。
+        if (not isinstance(self.areas, np.ndarray) or not isinstance(self.valid, np.ndarray)
+                or self.areas.dtype != np.float64 or self.valid.dtype != bool
+                or self.areas.ndim != 1 or self.areas.shape != self.valid.shape
+                or not isinstance(self.facts, IntegralFacts)):
+            raise TypeError('数组积分项需要同长一维float64/bool及IntegralFacts')
+        if (self.areas.flags.writeable or self.valid.flags.writeable
+                or not np.all(np.isfinite(self.areas)) or np.any(~self.valid & (self.areas != 0))):
+            raise ValueError('数组积分项必须只读且有限，无效位置仅0存储')
+
+
+def compute_integral_terms_numpy(series, spec, *, step_ns=None, retain_unknown_ranges=True, valid_until_ns=None):
+    """批量生成未转换面积与有效掩码，独立计算覆盖和样本数。
+
+    参数: series为有限CalculationSeries，spec为无条件integral请求；step_ns省略保持
+        实际积分，指定时只接收所选驱动真实更新，按实际交集比例计周期。
+        retain_unknown_ranges=False跳过未知范围对象构造，仍计算有效时长和质量。
+        valid_until_ns为同长实际有效截止；到达截止即失效，不改变记录对分母。
+    返回: NumpyIntegralTerms；实际临时/输出列为N或N-1，面积单位input_unit乘秒。
+    异常: 输入/单位/时间/分配错误传播；浮点故障追加质量并使对应项无效。
+    """
+    # typed请求先校验，实际交集仍为整数ns；输入不被裁剪改写。
+    require_integral_terms(series, spec, step_ns=step_ns, valid_until_ns=valid_until_ns)
+    if type(retain_unknown_ranges) is not bool:
+        raise TypeError('未知区间保留选项需要bool')
+    start = max(series.observation.start_ns, spec.window.start_ns)
+    end = min(series.observation.end_ns, spec.window.end_ns)
+    actual = Interval(start, end) if start <= end else None
+    # N个值/有效性/uint16质量列；未知0仅存储，独立转换核检查定宽精度。
+    column = NumericArray(series.values[0].dtype,
+        np.array([value.value if value.valid else 0 for value in series.values], dtype=DTYPES[series.values[0].dtype]),
+        np.array([value.valid for value in series.values], dtype=bool),
+        np.array([int(value.quality) for value in series.values], dtype=np.uint16))
+    values = to_float_numpy(column)
+    # 绝对时间不先转float；只对正裁剪区间求安全int64差。
+    times = np.array(series.times_ns, dtype=np.int64)
+    left, right = np.maximum(times[:-1], np.int64(start)), np.minimum(times[1:], np.int64(end))
+    observed = right > left
+    # 仅当前块的必要截止掩码；原始右端点继续作为周期比例的分母。
+    effective_right = right
+    expired_samples = None
+    if valid_until_ns is not None:
+        deadlines = np.array([item if item is not None else (1 << 63) - 1 for item in valid_until_ns], dtype=np.int64)
+        has_deadline = np.array([item is not None for item in valid_until_ns], dtype=bool)
+        expired_samples = has_deadline & (times >= deadlines)
+        effective_right = np.maximum(left, np.minimum(right, deadlines[:-1]))
+    effective = observed if valid_until_ns is None else observed & (effective_right > left)
+    durations = np.zeros(len(left), dtype=np.int64)
+    np.subtract(effective_right, left, out=durations, where=effective)
+    # N与N-1临时列均为当前块副本；mask限制乘法，面积为input_unit乘秒。
+    valid_values, quality_values = values.valid.copy(), values.quality.copy()
+    if expired_samples is not None:
+        valid_values[expired_samples] = False
+        quality_values[expired_samples] |= int(Q.STALE)
+        quality_values[:-1][observed & (effective_right < right)] |= int(Q.STALE)
+    keep = effective & valid_values[:-1]
+    areas = np.zeros(len(left), dtype=np.float64)
+    seconds = durations.astype(np.float64)
+    if step_ns is None:
+        seconds /= 1_000_000_000
+    else:
+        # 完整记录对作为分母；只算当前有限块，不创建第二时间轴或取整权重。
+        # CalculationSeries严格递增且观测跨度受int64限制，diff不会溢出或为零。
+        seconds /= np.diff(times)
+        seconds *= step_ns / 1_000_000_000
+    with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+        np.multiply(values.values[:-1], seconds, out=areas, where=keep)
+    # 计算失败既影响当前面积也影响同位置样本可用性，原输入列保持不变。
+    nonfinite = keep & ~np.isfinite(areas)
+    underflow = keep & (areas == 0) & (values.values[:-1] != 0)
+    quality_values[:-1][nonfinite] |= int(Q.NONFINITE)
+    quality_values[:-1][underflow] |= int(Q.PRECISION_LOSS)
+    valid_values[:-1][nonfinite | underflow] = False
+    keep = effective & valid_values[:-1]
+    areas[~keep] = 0.0
+    # 真实样本半开计数；非负有效dt总和受原实际跨度int64上界约束。
+    actual_updates = np.array(series.actual_value_updates, dtype=bool)
+    actual_samples = actual_updates & (times >= start) & (times < end)
+    sample_count = int(np.count_nonzero(actual_samples & valid_values))
+    duration = int(np.sum(durations, where=keep, dtype=np.int64))
+    # 只OR实际样本和已观察正区间的诊断，窗口外末点不污染结果。
+    diagnostic = np.array([int(value) for value in series.diagnostics], dtype=np.uint16) | quality_values
+    relevant = actual_samples.copy()
+    relevant[:-1] |= observed
+    quality = Q(int(np.bitwise_or.reduce(diagnostic, where=relevant, initial=0)))
+    # 只对有限块的诊断恢复Interval，原时间不经float，合并仅限相邻未知。
+    unknown = (tuple(Interval(int(effective_right[index] if keep[index] else left[index]), int(right[index]))
+                     for index in np.flatnonzero(observed & (~keep | (effective_right < right))))
+               if retain_unknown_ranges else ())
+    facts = IntegralFacts(spec, actual, duration, sample_count, merge_ranges(unknown), quality,
+                          series.unit, series.binding_identity, series.source_refs)
+    # 输出仍归调用方块workspace存活范围；纯核没有独立资源owner。
+    areas.setflags(write=False)
+    keep.setflags(write=False)
+    return NumpyIntegralTerms(areas, keep, facts)

chronaxis/core/integral_terms_reference.py

@@ -0,0 +1,91 @@
+"""独立标量计算有限块中的原序ZOH面积项，保留未知与覆盖事实。
+
+输入为无选择条件的CalculationSeries/CalculationDefinition，输出ReferenceIntegralTerms。
+逐正区间先裁剪整数ns，再乘当前有效值；不跨UNKNOWN，不先求和或换单位。
+严格检查整数到float精度、乘积非有限和非零下溢，并更新该区间样本可用性。
+只依赖标准库及typed核心，不调用NumPy、不读文件、不修改输入。
+所有有限列表/冻结输出在调用方块workspace内使用，单独调用不提供内存上限。
+"""
+
+# 标量有限性及精度判据独立于数组核，只有模型与门槛共享。
+from math import isfinite
+from .integral_terms import IntegralFacts, ReferenceIntegralTerms, require_integral_terms
+from .calculations import merge_ranges
+from .models import Interval
+from .numeric import ScalarValue, to_float_reference
+from .types import QualityFlag as Q
+from .record_intervals import clipped_record_seconds
+
+
+def compute_integral_terms_reference(series, spec, *, step_ns=None, retain_unknown_ranges=True, valid_until_ns=None):
+    """逐区间计算原序未转换面积与明确有效掩码。
+
+    参数: series为有限CalculationSeries；spec为无条件integral CalculationDefinition；step_ns省略
+        保持实际积分，指定时输入仅含所选驱动真实更新，按实际交集比例计周期。
+        retain_unknown_ranges=False不构造未知区间明细，保留计算所需的有效时长/质量。
+        valid_until_ns为同长实际有效截止，None项表示本块无额外截止；到达截止即失效。
+    返回: ReferenceIntegralTerms，areas/valid长度N-1；面积单位为input_unit乘秒。
+    异常: 输入/单位/时间/分配错误传播；数值精度/溢出/下溢写入质量并使面积无效。
+    """
+    # 先验证请求；裁剪仍在精确整数ns域，无交集不产生实际范围。
+    require_integral_terms(series, spec, step_ns=step_ns, valid_until_ns=valid_until_ns)
+    if type(retain_unknown_ranges) is not bool:
+        raise TypeError('未知区间保留选项需要bool')
+    start = max(series.observation.start_ns, spec.window.start_ns)
+    end = min(series.observation.end_ns, spec.window.end_ns)
+    actual = Interval(start, end) if start <= end else None
+    # 每值转换独立检查精度，不改变原ScalarValue。
+    values = [to_float_reference(value) for value in series.values]
+    # 已经失效的驱动快照不能继续计算；过期时间不由固定周期延长。
+    if valid_until_ns is not None:
+        for index, deadline in enumerate(valid_until_ns):
+            if deadline is not None and series.times_ns[index] >= deadline:
+                value = values[index]
+                values[index] = ScalarValue(value.value, value.dtype, False, value.quality | Q.STALE, value.labels)
+    # 列长度受调用方有限输入约束；逐区间保留原顺序，不累计面积总值。
+    areas, valid, unknown = [], [], []
+    duration, sample_count, quality = 0, 0, Q.NONE
+    for index in range(len(series.times_ns) - 1):
+        left, right = max(start, series.times_ns[index]), min(end, series.times_ns[index + 1])
+        area, keep = 0.0, False
+        if left < right:
+            deadline = None if valid_until_ns is None else valid_until_ns[index]
+            effective_right = right if deadline is None else max(left, min(right, deadline))
+            # 非零实际区间才纳入来源诊断，末点不增加面积。
+            value = values[index]
+            quality |= series.diagnostics[index] | value.quality
+            if effective_right < right:
+                quality |= Q.STALE
+            if value.valid and left < effective_right:
+                seconds = ((effective_right - left) / 1_000_000_000 if step_ns is None else
+                           clipped_record_seconds(series.times_ns[index], series.times_ns[index + 1],
+                                                  spec.window if effective_right == right else Interval(left, effective_right),
+                                                  step_ns=step_ns))
+                term = value.value * seconds
+                failure = Q.NONFINITE if not isfinite(term) else Q.PRECISION_LOSS if term == 0 and value.value != 0 else Q.NONE
+                if failure == Q.NONE:
+                    area, keep = term, True
+                    duration += effective_right - left
+                else:
+                    # 失败项和该位置真实样本均不可核实，不把下溢当正常零。
+                    quality |= failure
+                    values[index] = ScalarValue(value.value, value.dtype, False, value.quality | failure, value.labels)
+            # 无效正区间保留位置和原因，未观察区间不伪造未知覆盖。
+            if not keep and retain_unknown_ranges:
+                unknown.append(Interval(left, right))
+            elif retain_unknown_ranges and effective_right < right:
+                unknown.append(Interval(effective_right, right))
+        # 保留每个原区间的槽位及顺序，未知0存储只能结合False掩码使用。
+        areas.append(area)
+        valid.append(keep)
+    # 样本只来自半开窗口内真实更新；面积故障已在局部转换列标无效。
+    for index, time in enumerate(series.times_ns):
+        if start <= time < end and series.actual_value_updates[index]:
+            value = values[index]
+            quality |= series.diagnostics[index] | value.quality
+            if value.valid:
+                sample_count += 1
+    # 仅紧凑诊断与冻结事实，原绑定/来源引用保持，不生成最终指标状态。
+    facts = IntegralFacts(spec, actual, duration, sample_count, merge_ranges(unknown), quality,
+                          series.unit, series.binding_identity, series.source_refs)
+    return ReferenceIntegralTerms(tuple(areas), tuple(valid), facts)

chronaxis/core/mean_weights_numpy.py

@@ -0,0 +1,29 @@
+"""以独立NumPy运算执行均值权重归一化，不调用标量数值核。"""
+
+import numpy as np
+from .types import QualityFlag as Q
+
+
+def normalized_mean_terms(values, weights, denominator):
+    """对有限数值列先除整窗正分母再乘值，返回只读项和质量。
+
+    参数: 同形一维有效值/权重数组及已核实正分母。返回: (ndarray, QualityFlag)。
+    异常: 结构或分配错误传播；非有限和非零下溢记质量，不修补结果。
+    """
+    try:
+        if values.ndim != 1 or weights.shape != values.shape or not np.isfinite(denominator) or denominator <= 0:
+            raise ValueError('均值需要同形一维输入和有限正分母')
+        if np.any(~np.isfinite(values)) or np.any(~np.isfinite(weights)) or np.any(weights <= 0):
+            raise ValueError('均值回读需要有限数值和正权重')
+        with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+            terms = np.multiply(values, weights / denominator)
+        quality = Q.NONE
+        if np.any(~np.isfinite(terms)):
+            quality |= Q.NONFINITE
+        if np.any((terms == 0) & (values != 0)):
+            quality |= Q.PRECISION_LOSS
+        terms.setflags(write=False)
+        return terms, quality
+    finally:
+        # 保留原异常，断开本帧借用列，避免调用方保存traceback时延长其生命周期。
+        values = weights = terms = None

chronaxis/core/mean_weights_reference.py

@@ -0,0 +1,27 @@
+"""复用标量均值的先归一化再相乘规则，避免先求面积导致溢出。"""
+
+from math import isfinite
+from .types import QualityFlag as Q
+
+
+def normalized_mean_terms(values, weights, denominator):
+    """将有限有效值按整窗正分母加权，返回原序项和计算质量。
+
+    参数: 同长有效数值/正权重序列，denominator为已核实总权重。
+    返回: (tuple, QualityFlag)。异常: 结构或分配错误传播；非有限/下溢标质量。
+    """
+    try:
+        if len(values) != len(weights) or not isfinite(denominator) or denominator <= 0:
+            raise ValueError('均值需要同长输入和有限正分母')
+        terms, quality = [], Q.NONE
+        for value, weight in zip(values, weights):
+            if not isfinite(value) or not isfinite(weight) or weight <= 0:
+                raise ValueError('均值回读需要有限数值和正权重')
+            term = value * (weight / denominator)
+            failure = Q.NONFINITE if not isfinite(term) else Q.PRECISION_LOSS if term == 0 and value != 0 else Q.NONE
+            quality |= failure
+            terms.append(term if failure == Q.NONE else 0.0)
+        return tuple(terms), quality
+    finally:
+        # 保留原异常，断开本帧借用列，避免调用方保存traceback时延长其生命周期。
+        values = weights = terms = None

chronaxis/core/message_binding.py

@@ -0,0 +1,305 @@
+"""为当前消息表达式声明参数，并把独立消息仓事实关联为运行绑定。
+
+ExpressionParameter将显式单位的配置数值规范成精确FLOAT64。MessageDeclarations
+引用当前DeclarationBindings中选定来源的原SignalDefinition，不复制或虚构信号、
+普通历史或TTL；当前policy只使用本条消息原字典，不继承上一条值。
+MessageSourceEvidence只检查显式来源标签、全仓摘要、条数和首末的结构；
+MessageBindings将其与完整声明身份关联。真正封存文件的EOF/SHA/条数验证由
+执行层bind_message_store负责，单独构造证据不证明来源文件已经读取。
+
+本模块只保存冻结配置与有限事实，不读文件、不执行表达式、不加载NumPy或
+CAN，也不证明仓来自同一次CAN捕获或DBC单位已核实。这些关联留给实际生产端。
+身份使用新版本前缀与固定字段的长度前缀增量SHA，不改变普通绑定的身份协议。
+模型及调用者保留的配置由调用者拥有；执行工厂另付其新运行元数据费用。
+"""
+
+# 参数、证据及绑定均不可变；数值配置不从对象隐式推断。
+from dataclasses import dataclass, field
+from hashlib import sha256
+from math import isfinite
+
+from .binding import SignalDefinition
+from .declarations import DeclarationBindings
+from .types import SignalDType
+from .units import UNIT_TABLE
+from .validation import require_identifier, require_text
+from ..timebase.conversion import require_int64_ns
+
+
+def _hash_parts(parts: tuple[str, ...]) -> str:
+    """按固定模型字段顺序增量编码文本身份，失败不保活新增整段编码副本。
+
+    参数: parts为本模块已检查的原生文本tuple，首项含独立版本前缀。
+    返回: 小写SHA-256文本；每段UTF-8字节有长度前缀，分隔符不能造成碰撞。
+    异常: 原Unicode、内存或取消错误；不调用外部repr或保存全量canonical文本。
+    """
+    raw = None
+    try:
+        digest = sha256()
+        for part in parts:
+            # 每次只保留一段编码；不同文本和字段边界均进入新身份。
+            if type(part) is not str:
+                raise TypeError('消息身份只编码已检查的原生文本')
+            raw = part.encode('utf-8')
+            digest.update(str(len(raw)).encode('ascii'))
+            digest.update(b':')
+            digest.update(raw)
+            raw = None
+        return digest.hexdigest()
+    finally:
+        # 执行工厂可能在此异常后抵费，TB不得留下本层新编码或parts容器。
+        raw = parts = None
+
+
+@dataclass(frozen=True)
+class ExpressionParameter:
+    """保存一个有明确单位、不可被对方重赋单位的FLOAT64配置参数。
+
+    只接受原生有限int/float；int须能精确转为有限float，不能静默舍入。
+    该参数不是信号或裸数字literal，不产生来源依赖和时间保持状态。
+    """
+
+    name: str  # 表达式使用的安全简单名称。
+    value: int | float  # 构造后规范为有限原生float。
+    unit: str  # 明确单位标签；不按对方信号自动改写。
+    unit_status: str = field(init=False)  # 只说明标签是否属于已有单位表。
+
+    def __post_init__(self) -> None:
+        """验证参数名称、精确数值及单位，不执行来源或表达式。
+
+        参数: 无，读取name/value/unit。
+        返回: None，value规范成FLOAT64可精确表示的原生float。
+        异常: TypeError为非原生数值；ValueError为非有限、有损整数或声明非法。
+        """
+        if type(self.name) is not str or type(self.unit) is not str:
+            raise TypeError('表达式参数名称和单位需要原生str')
+        require_identifier(self.name, 'parameter.name')
+        require_text(self.unit, 'parameter.unit')
+        if type(self.value) not in (int, float):
+            raise TypeError('表达式参数只接受原生int/float，不能为bool')
+        # 在配置边界证明精确性，不把参数有损转换拖到每条消息求值中。
+        try:
+            number = float(self.value)
+        except OverflowError as exc:
+            raise ValueError('表达式参数不能表示为有限FLOAT64') from exc
+        if not isfinite(number) or type(self.value) is int and int(number) != self.value:
+            raise ValueError('表达式参数必须能精确表示为有限FLOAT64')
+        object.__setattr__(self, 'value', number)
+        object.__setattr__(self, 'unit_status', 'verified' if self.unit in UNIT_TABLE else 'unverified')
+
+    @property
+    def dtype(self) -> SignalDType:
+        """读取固定数值类型；参数: 无；返回: FLOAT64；异常: 无。"""
+        return SignalDType.FLOAT64
+
+
+@dataclass(frozen=True)
+class MessageDeclarations:
+    """为一个选定来源建立独立的当前消息名称空间，不制造运行证明。
+
+    signals引用原声明中的同一SignalDefinition对象。原定义的转换声明保留，
+    其TTL不在本模型执行；依赖仅能来自selected source。parameters及局部
+    derived_names不能覆盖原计划任何signal/derived，也不能互相覆盖。
+    """
+
+    declarations: DeclarationBindings  # 完整原配置声明及身份，非实际文件证明。
+    source: str  # 只允许这个原来源的信号参与当前消息表达式。
+    parameters: tuple[ExpressionParameter, ...] = ()  # 有明确单位的配置参数。
+    derived_names: tuple[str, ...] = ()  # 当前指标显式登记的局部派生名。
+    message_policy: str = 'current_message-v1'  # 只看当前字典，不沿用缓存或TTL。
+    identity: str = field(init=False)  # 完整原配置与消息配置的独立声明SHA。
+
+    def __post_init__(self) -> None:
+        """核对来源、完整名称空间与policy，生成静态消息声明身份。
+
+        参数: 无，读取冻结字段，不读取文件或DBC。
+        返回: None；保原定义对象，不将声明身份当真实仓EOF证明。
+        异常: TypeError为模型/容器错误；ValueError为来源、名称或policy冲突。
+        """
+        if not isinstance(self.declarations, DeclarationBindings):
+            raise TypeError('消息声明需要DeclarationBindings')
+        if type(self.source) is not str:
+            raise TypeError('消息来源需要原生str')
+        require_identifier(self.source, 'message.source')
+        if self.source not in {item.name for item in self.declarations.sources}:
+            raise ValueError('消息来源不在原声明中')
+        if (type(self.parameters) is not tuple or type(self.derived_names) is not tuple
+                or any(type(item) is not ExpressionParameter for item in self.parameters)):
+            raise TypeError('消息参数与局部派生名称需要typed tuple')
+        if type(self.message_policy) is not str or self.message_policy != 'current_message-v1':
+            raise ValueError('消息policy仅支持current_message-v1')
+        # 全原计划名称都受保护，不能利用selected source隐藏其他来源的名称冲突。
+        names = {item.name for item in self.declarations.signals} | set(self.declarations.derived_names)
+        for parameter in self.parameters:
+            if parameter.name in names:
+                raise ValueError('消息参数与原声明或其他参数名称冲突：' + parameter.name)
+            names.add(parameter.name)
+        for name in self.derived_names:
+            if type(name) is not str:
+                raise TypeError('消息局部派生名称需要原生str')
+            require_identifier(name, 'message.derived_name')
+            if name in names:
+                raise ValueError('消息局部派生名称冲突：' + name)
+            names.add(name)
+        parts = None
+        try:
+            # 数量字段固定参数与派生分段；完整base身份含未选来源，不能遗漏配置变化。
+            parts = ('message-declaration-v1', self.declarations.identity, self.source,
+                     self.message_policy, str(len(self.parameters)))
+            parts += tuple(value for item in self.parameters
+                           for value in (item.name, item.value.hex(), item.unit, item.unit_status))
+            parts += (str(len(self.derived_names)), *self.derived_names)
+            object.__setattr__(self, 'identity', _hash_parts(parts))
+        finally:
+            # 只清本层新身份容器，原声明/参数仍由调用者持有。
+            parts = None
+
+    @property
+    def signals(self) -> tuple[SignalDefinition, ...]:
+        """选择同一原定义对象；参数: 无；返回: tuple；异常: 无主动异常。"""
+        return tuple(item for item in self.declarations.signals if item.source == self.source)
+
+    def resolve(self, name: str) -> SignalDefinition:
+        """只定位本来源原信号，参数名称另由编译器处理。
+
+        参数: name为安全简单信号别名。返回: 原SignalDefinition对象。
+        异常: ValueError为未知、其他来源或非法名称；不从点号猜测原字段。
+        """
+        require_identifier(name, 'message.signal_alias')
+        for definition in self.signals:
+            if definition.name == name:
+                return definition
+        raise ValueError('未知或不属消息来源的信号别名：' + name)
+
+    def require_synchronized(self, names: tuple[str, ...]) -> None:
+        """检查实际依赖均在本来源，不借其他来源的同步声明引入缓存值。
+
+        参数: names为展开后的原信号依赖tuple，空依赖合法。
+        返回: None；单源当前字典不需要合并其他来源时钟。
+        异常: TypeError为容器错误；ValueError为非本来源或未知依赖。
+        """
+        if type(names) is not tuple:
+            raise TypeError('消息依赖names需要tuple')
+        for name in names:
+            self.resolve(name)
+
+
+@dataclass(frozen=True)
+class MessageSourceEvidence:
+    """保存独立解码消息仓的有限事实，仅校结构而不声明真实回读已发生。
+
+    decoder_profile/read_identity是仓内显式标签，不认证旧CAN来源。原序SHA
+    包含记录和值/映射时间；首末可相同，空仓必须两端None且条数为0。
+    """
+
+    source: str  # 本消息来源。
+    session_id: str  # 原声明会话。
+    decoder_profile: str  # 显式解码来源标签，不冒充计算policy。
+    read_identity: str  # 仓的显式读取标识，CAN同次关联由生产端另核。
+    store_sha256: str  # 已封口全消息行流摘要。
+    record_count: int  # 全decoded条数，不是普通历史样本数。
+    first_time_ns: int | None  # 全仓首条映射坐标，空仓为None。
+    last_time_ns: int | None  # 全仓最后坐标，不补采样周期。
+
+    def __post_init__(self) -> None:
+        """验证有限证据一致性，单独构造不能替代实际EOF校验。
+
+        参数: 无，读取冻结字段。返回: None，已知时间规范成原生int。
+        异常: TypeError/ValueError为类型、SHA、条数或首末矛盾；时间超界原样传播。
+        """
+        if any(type(value) is not str for value in (self.source, self.session_id,
+                                                   self.decoder_profile, self.read_identity)):
+            raise TypeError('消息证据来源、会话及读取标签需要原生str')
+        require_identifier(self.source, 'message_evidence.source')
+        require_identifier(self.session_id, 'message_evidence.session_id')
+        require_text(self.decoder_profile, 'message_evidence.decoder_profile')
+        require_text(self.read_identity, 'message_evidence.read_identity')
+        if type(self.store_sha256) is not str:
+            raise TypeError('消息仓摘要需要原生str')
+        if (len(self.store_sha256) != 64
+                or any(char not in '0123456789abcdef' for char in self.store_sha256)):
+            raise ValueError('消息仓摘要需要64位小写十六进制SHA-256')
+        if type(self.record_count) is not int or self.record_count < 0:
+            raise ValueError('消息条数需要非负原生int')
+        if self.record_count == 0:
+            if self.first_time_ns is not None or self.last_time_ns is not None:
+                raise ValueError('空消息仓首末必须为None')
+            return
+        if self.first_time_ns is None or self.last_time_ns is None:
+            raise ValueError('非空消息仓必须有真实首末时间')
+        # 共享int64单端点规则允许真实零长观测，不计算两端差值造成溢出。
+        first = require_int64_ns(self.first_time_ns, 'message_evidence.first_time_ns')
+        last = require_int64_ns(self.last_time_ns, 'message_evidence.last_time_ns')
+        if last < first:
+            raise ValueError('消息仓终点早于起点')
+        object.__setattr__(self, 'first_time_ns', first)
+        object.__setattr__(self, 'last_time_ns', last)
+
+
+@dataclass(frozen=True)
+class MessageBindings:
+    """关联消息声明与实际仓证据，保持独立于普通DecodedBindings的运行身份。
+
+    证据实际性由bind_message_store完整回读负责；本模型只校结构/归属。
+    不证明普通历史、TTL、DBC字段单位或同次CAN捕获，也不保存逐条记录。
+    """
+
+    declarations: MessageDeclarations  # 单源消息配置及完整原声明身份。
+    evidence: MessageSourceEvidence  # 执行工厂核实后的仓事实，非手造即证明。
+    identity: str = field(init=False)  # 独立message-binding-v1身份。
+
+    def __post_init__(self) -> None:
+        """核对声明与证据来源/会话，增量生成有限运行身份。
+
+        参数: 无，读取declarations/evidence。返回: None，不再次打开消息仓。
+        异常: TypeError为模型错误；ValueError为来源/会话不符；编码或取消原错传播。
+        """
+        if not isinstance(self.declarations, MessageDeclarations) or not isinstance(self.evidence, MessageSourceEvidence):
+            raise TypeError('消息运行绑定需要MessageDeclarations和MessageSourceEvidence')
+        if (self.evidence.source != self.declarations.source
+                or self.evidence.session_id != self.declarations.declarations.session_id):
+            raise ValueError('消息仓证据的来源或会话与当前声明不符')
+        parts = None
+        try:
+            # 每一证据字段都进入独立身份，不把read标签或同名配置单独当输入证明。
+            evidence = self.evidence
+            parts = ('message-binding-v1', self.declarations.identity, evidence.source,
+                     evidence.session_id, evidence.decoder_profile, evidence.read_identity,
+                     evidence.store_sha256, str(evidence.record_count),
+                     'none' if evidence.first_time_ns is None else str(evidence.first_time_ns),
+                     'none' if evidence.last_time_ns is None else str(evidence.last_time_ns))
+            object.__setattr__(self, 'identity', _hash_parts(parts))
+        finally:
+            # 原错误可被调用者保留，执行层抵费后不由本TB留下新身份容器。
+            parts = None
+
+    @property
+    def signals(self) -> tuple[SignalDefinition, ...]:
+        """读取同一原信号定义；参数: 无；返回: tuple；异常: 无主动异常。"""
+        return self.declarations.signals
+
+    @property
+    def parameters(self) -> tuple[ExpressionParameter, ...]:
+        """读取冻结配置参数；参数: 无；返回: tuple；异常: 无。"""
+        return self.declarations.parameters
+
+    @property
+    def derived_names(self) -> tuple[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:
+        """执行前复核全部依赖属于本来源，不执行普通TTL或时钟合并。
+
+        参数: names为原信号依赖tuple。返回: None。
+        异常: TypeError/ValueError为容器或非本来源依赖。
+        """
+        self.declarations.require_synchronized(names)