chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/results/summary.py

@@ -0,0 +1,350 @@
+"""定义按需执行的精简指标行，不要求不存在的完整输入证明。
+
+只保留结果身份、业务数值、单位及完成/质量状态。事件或片段通过parent_id关联，
+不逐行重复配置、信号定义、时间对照或贡献；公开结果只接受当前扁平模型。
+本模型只校验结果字段，不读取输入或执行指标计算。
+"""
+
+from dataclasses import dataclass
+import json
+from math import isfinite
+
+from ..core.types import QualityFlag as Q
+from ..core.validation import require_identifier, require_text
+from ..timebase.conversion import require_int64_ns
+
+
+@dataclass(frozen=True)
+class SummaryCalculationRow:
+    """一条精简指标；未知用None，不能把缺失转换为正常零。"""
+
+    # 固定身份只用于关联本次结果，不代替原始输入哈希或逐条来源。
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    calculation_id: str
+    # 算子及父范围给出业务含义；session没有父对象。
+    operation: str
+    scope: str
+    parent_id: str | None
+    # 数值与质量必须一起读取，None不等于有效零。
+    value: int | float | None
+    unit: str
+    status: str
+    reason: str
+    quality: Q
+
+    def __post_init__(self):
+        """核对身份、数值类型及状态，不补造来源或时间信息。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为字段或组合错误。
+        """
+        if type(self.sequence) is not int or self.sequence < 0:
+            raise ValueError('精简指标序号需要非负原生int')
+        for name in ('dataset_id', 'entity_id', 'session_id', 'calculation_id'):
+            require_identifier(getattr(self, name), 'summary.'+name)
+        if self.operation not in ('integral', 'duration', 'min_time', 'max_time', 'time_weighted_mean',
+                           'sample_minimum', 'sample_maximum', 'sample_mean', 'legacy_sum'):
+            raise ValueError('精简指标不支持该算子')
+        if self.scope not in ('session', 'event', 'segment'):
+            raise ValueError('精简指标scope无效')
+        if self.scope == 'session':
+            if self.parent_id is not None:
+                raise ValueError('会话指标不能声明父事件或片段')
+        else:
+            require_text(self.parent_id, 'summary.parent_id')
+        if self.value is not None and (type(self.value) not in (int, float)
+                or type(self.value) is float and not isfinite(self.value)):
+            raise ValueError('精简指标值需要有限数值或None')
+        require_text(self.unit, 'summary.unit')
+        require_text(self.reason, 'summary.reason')
+        if self.status not in ('complete', 'partial', 'indeterminate'):
+            raise ValueError('精简指标status无效')
+        if self.status == 'indeterminate' and self.value is not None:
+            raise ValueError('无法确定的指标不能含可用数值')
+        if not isinstance(self.quality, Q):
+            raise TypeError('精简指标质量需要QualityFlag')
+
+
+SUMMARY_FIELDS = ('sequence', 'dataset_id', 'entity_id', 'session_id', 'calculation_id', 'operation',
+                  'scope', 'parent_id', 'value', 'unit', 'status', 'reason', 'quality')
+
+
+@dataclass(frozen=True)
+class SummaryCoverageCalculationRow(SummaryCalculationRow):
+    """仅明确设置覆盖门槛时补一个判定，不重复输出时长、比例或输入明细。"""
+
+    coverage_status: str
+
+    def __post_init__(self):
+        """保留数值政策与覆盖门槛两个不同事实。参数: 无。返回: None。异常: 非法判定。"""
+        super().__post_init__()
+        if self.coverage_status not in ('sufficient','indeterminate'):
+            raise ValueError('覆盖门槛判定无效')
+
+
+def _require_row_identity(row):
+    """核精简事件和配对的公共身份。参数: 冻结行。返回: None。异常: 类型或字段错误。"""
+    if type(row.sequence) is not int or row.sequence < 0:
+        raise ValueError('精简结果序号需要非负原生int')
+    for name in ('dataset_id','entity_id','session_id','rule_id'):
+        require_identifier(getattr(row,name),'summary.'+name)
+    if not isinstance(row.quality,Q):
+        raise TypeError('精简结果质量需要QualityFlag')
+
+
+@dataclass(frozen=True)
+class SummaryEventRow:
+    """一条业务事件；开始、确认、结束各有不同含义，不含原帧或逐条来源副本。"""
+
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    rule_id: str
+    event_id: str
+    start_ns: int
+    confirmed_ns: int
+    end_ns: int | None
+    status: str
+    trigger: str
+    quality: Q
+
+    def __post_init__(self):
+        """核实际业务端点，不能把未知结束填为零。参数: 无。返回: None。异常: 合同错误。"""
+        _require_row_identity(self)
+        require_text(self.event_id,'event_id')
+        start=require_int64_ns(self.start_ns,'start_ns')
+        confirmed=require_int64_ns(self.confirmed_ns,'confirmed_ns')
+        if confirmed < start:
+            raise ValueError('确认不能早于开始')
+        if self.status == 'point':
+            if self.end_ns is not None or start != confirmed:
+                raise ValueError('点事件没有活动结束时间')
+        elif self.status in ('closed','interrupted','truncated','timeout'):
+            end=require_int64_ns(self.end_ns,'end_ns')
+            if not start < end or confirmed > end:
+                raise ValueError('活动实际端点顺序无效')
+        else:
+            raise ValueError('精简事件状态无效')
+        require_text(self.trigger,'trigger')
+
+
+@dataclass(frozen=True)
+class SummarySequenceRow:
+    """一条配对结论，只关联既有事件ID并保存所选口径的延迟。"""
+
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    rule_id: str
+    result_id: str
+    request_id: str
+    response_id: str | None
+    decided_ns: int
+    delay_ns: int | None
+    status: str
+    quality: Q
+
+    def __post_init__(self):
+        """核配对及未知结果，不逐行重复规则和事件。参数: 无。返回: None。异常: 合同错误。"""
+        _require_row_identity(self)
+        for name in ('result_id','request_id'):
+            require_text(getattr(self,name),name)
+        require_int64_ns(self.decided_ns,'decided_ns')
+        if self.status == 'matched':
+            require_text(self.response_id,'response_id')
+            if require_int64_ns(self.delay_ns,'delay_ns') < 0:
+                raise ValueError('配对延迟不能为负')
+        elif self.status in ('no_response','indeterminate'):
+            if self.response_id is not None or self.delay_ns is not None:
+                raise ValueError('未匹配结果不能伪造响应和延迟')
+            if self.status == 'indeterminate' and self.quality == Q.NONE:
+                raise ValueError('未知配对必须说明质量原因')
+            if self.status == 'no_response' and self.quality != Q.NONE:
+                raise ValueError('缺失观测不能声明确定未响应')
+        else:
+            raise ValueError('精简配对状态无效')
+
+
+@dataclass(frozen=True)
+class SummarySegmentRow:
+    """片段只输出实际边界、状态和父事件ID，不重复请求边界/原事件/来源。"""
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    window_id: str
+    segment_id: str
+    start_ns: int | None
+    end_ns: int | None
+    status: str
+    parent_event_ids: tuple[str,...]
+    quality: Q
+
+    def __post_init__(self):
+        """检查实际范围和必需父关联。参数: 无。返回: None。异常: 字段/组合错误。"""
+        if type(self.sequence) is not int or self.sequence<0:
+            raise ValueError('片段sequence需非负原生int')
+        for name in ('dataset_id','entity_id','session_id','window_id'):
+            require_identifier(getattr(self,name),name)
+        require_text(self.segment_id,'segment_id')
+        if not isinstance(self.quality,Q) or type(self.parent_event_ids) is not tuple or not self.parent_event_ids:
+            raise TypeError('片段需质量及非空父ID tuple')
+        if len(set(self.parent_event_ids))!=len(self.parent_event_ids):
+            raise ValueError('片段父ID不能重复')
+        for parent in self.parent_event_ids:
+            require_text(parent,'parent_event_id')
+        if self.status=='empty':
+            if self.start_ns is not None or self.end_ns is not None:
+                raise ValueError('空片段不能伪造实际范围')
+        elif self.status in ('complete','partial'):
+            if require_int64_ns(self.start_ns)>=require_int64_ns(self.end_ns):
+                raise ValueError('片段需要正实际范围')
+        else:
+            raise ValueError('片段状态错误')
+
+
+SUMMARY_EVENT_FIELDS = ('sequence','dataset_id','entity_id','session_id','rule_id','event_id',
+    'start_ns','confirmed_ns','end_ns','status','trigger','quality')
+SUMMARY_SEQUENCE_FIELDS = ('sequence','dataset_id','entity_id','session_id','rule_id','result_id',
+    'request_id','response_id','decided_ns','delay_ns','status','quality')
+SUMMARY_MODELS = {SummaryCalculationRow: ('calculations',SUMMARY_FIELDS,7),
+    SummaryEventRow: ('events',SUMMARY_EVENT_FIELDS,8), SummarySequenceRow: ('sequences',SUMMARY_SEQUENCE_FIELDS,9)}
+SUMMARY_MODELS[SummarySegmentRow]=('segments',('sequence','dataset_id','entity_id','session_id','window_id',
+    'segment_id','start_ns','end_ns','status','parent_event_ids','quality'),11)
+@dataclass(frozen=True)
+class SummaryContributionRow:
+    """一条明确请求的逐消息贡献；仅定位计算，不复制原帧或输入值。"""
+
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    calculation_id: str
+    source: str
+    original_sequence: int
+    evaluation_index: int
+    value: float | None
+    reason: str
+    quality: Q
+
+    def __post_init__(self):
+        """核定位及贡献/跳过互斥。参数: 无。返回: None。异常: 类型或字段错误。"""
+        for name in ('sequence','original_sequence','evaluation_index'):
+            if type(getattr(self,name)) is not int or getattr(self,name)<0:
+                raise ValueError('贡献定位需非负原生整数')
+        for name in ('dataset_id','entity_id','session_id','calculation_id','source'):
+            require_identifier(getattr(self,name),name)
+        if not isinstance(self.quality,Q):
+            raise TypeError('贡献质量需QualityFlag')
+        if self.value is None:
+            if self.reason not in ('missing_input','condition_false','evaluation_error','nonfinite_input'):
+                raise ValueError('跳过贡献需要明确原因')
+        elif type(self.value) is not float or not isfinite(self.value) or self.reason!='contributed':
+            raise ValueError('有效贡献需要有限float及contributed状态')
+
+
+SUMMARY_MODELS[SummaryContributionRow]=('contributions',('sequence','dataset_id','entity_id','session_id',
+    'calculation_id','source','original_sequence','evaluation_index','value','reason','quality'),12)
+@dataclass(frozen=True)
+class SummaryInputRow:
+    """按请求保存一次所需输入；字段原值一份，不保存双时间表示或原帧副本。"""
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    source: str
+    original_sequence: int
+    time_ns: int | None
+    record_type: str
+    locator: str
+    values_json: str
+    quality: Q
+
+    def __post_init__(self):
+        """核定位与有限JSON标量，拒绝任意嵌套模型。参数: 无。返回: None。异常: 字段/格式错误。"""
+        for name in ('sequence','original_sequence'):
+            if type(getattr(self,name)) is not int or getattr(self,name)<0:raise ValueError('追溯序号需非负int')
+        for name in ('dataset_id','entity_id','session_id','source'):require_identifier(getattr(self,name),name)
+        if self.time_ns is not None:require_int64_ns(self.time_ns)
+        if self.record_type not in ('decoded_message','signal_sample','signal_clock') or not isinstance(self.quality,Q):
+            raise ValueError('追溯类型/质量无效')
+        require_text(self.locator,'trace.locator')
+        if type(self.values_json) is not str:raise TypeError('追溯值需JSON文本')
+        values=json.loads(self.values_json)
+        if type(values) is not dict:raise ValueError('追溯值需字段对象')
+        for name,value in values.items():
+            require_text(name,'trace.field')
+            if type(value) is dict:
+                if set(value)!= {'nonfinite'} or value['nonfinite'] not in ('nan','inf','-inf'):
+                    raise ValueError('追溯只允许明确非有限值标签')
+            elif value is not None and (type(value) not in (str,int,float,bool)
+                    or type(value) is float and not isfinite(value)):
+                raise ValueError('追溯字段需有限标量或明确非有限标签')
+
+
+SUMMARY_MODELS[SummaryInputRow]=('input_trace',('sequence','dataset_id','entity_id','session_id',
+    'source','original_sequence','time_ns','record_type','locator','values_json','quality'),13)
+@dataclass(frozen=True)
+class SummarySelectionRow:
+    """一条真实更新的选择结果；保业务值及三值选择，不重复输入证明。"""
+    sequence: int
+    dataset_id: str
+    entity_id: str
+    session_id: str
+    calculation_id: str
+    scope: str
+    parent_id: str | None
+    time_ns: int
+    value: int | float | bool | str | None
+    dtype: str
+    unit: str
+    valid: bool
+    selection: str
+    quality: Q
+
+    def __post_init__(self):
+        """核选择行身份和值类型。参数: 无。返回: None。异常: 类型/结构错误。"""
+        if type(self.sequence) is not int or self.sequence<0:raise ValueError('选择序号需要非负int')
+        for name in ('dataset_id','entity_id','session_id','calculation_id'):require_identifier(getattr(self,name),name)
+        if self.scope not in ('session','event','segment'):raise ValueError('选择范围类型无效')
+        if self.scope=='session':
+            if self.parent_id is not None:raise ValueError('会话选择不能声明父对象')
+        else:require_text(self.parent_id,'selection.parent_id')
+        require_int64_ns(self.time_ns);require_text(self.unit,'selection.unit')
+        kinds={'float64':float,'int64':int,'uint64':int,'bool':bool,'enum':str}
+        if self.dtype not in kinds or type(self.valid) is not bool or not isinstance(self.quality,Q):
+            raise TypeError('选择类型/有效性/质量错误')
+        if self.selection not in ('true','unknown') or self.selection=='unknown' and self.quality==Q.NONE:
+            raise ValueError('选择仅支持TRUE或有质量原因的UNKNOWN')
+        if self.valid:
+            if type(self.value) is not kinds[self.dtype] or type(self.value) is float and not isfinite(self.value):
+                raise ValueError('选择有效值与dtype不符')
+            if self.dtype=='int64' and not -(1<<63)<=self.value<(1<<63) or self.dtype=='uint64' and not 0<=self.value<(1<<64):
+                raise ValueError('选择整数超出dtype')
+        elif self.value is not None or self.quality==Q.NONE:
+            raise ValueError('选择无效值必须为空并保留质量原因')
+
+
+SUMMARY_MODELS[SummarySelectionRow]=('selections',('sequence','dataset_id','entity_id','session_id','calculation_id',
+    'scope','parent_id','time_ns','value','dtype','unit','valid','selection','quality'),14)
+SUMMARY_COLUMNS = {table: names for table,names,_ in SUMMARY_MODELS.values()}
+SUMMARY_MODELS[SummaryCoverageCalculationRow] = ('calculations',SUMMARY_FIELDS+('coverage_status',),10)
+
+
+def summary_fields(row):
+    """转换必要平坦字段，CSV和JSONL共用，不附另一份row_json。
+
+    参数: SummaryCalculationRow。返回: 固定字段dict。异常: TypeError为错误根类型。
+    """
+    try:
+        if type(row) not in SUMMARY_MODELS:
+            raise TypeError('精简字段需要SummaryCalculationRow')
+        result = {name: getattr(row, name) for name in SUMMARY_MODELS[type(row)][1]}
+        result['quality'] = int(row.quality)
+        return result
+    finally:
+        row = None

chronaxis/results/text_can_metadata.py

@@ -0,0 +1,64 @@
+"""保存新文本CAN同次读取取得的DBC身份、解析声明和实际观测事实。
+
+这是can-text-v1的独立清单，不冒充旧进程READY或未计算的原文件哈希。
+声明的路径/格式与实际读取计数分别保留；空来源不伪造首末时间。
+"""
+
+from dataclasses import dataclass
+from ..core.validation import require_identifier,require_text
+from ..timebase.conversion import require_int64_ns
+from .can_metadata import CANUnitCheck,CANFrameFormatNotice
+
+
+@dataclass(frozen=True)
+class TextCANSourceMetadata:
+    """仅接受冻结有限字段；实际事实由完成的ObservedSourceScan交付。"""
+
+    source: str
+    session_id: str
+    source_type: str
+    read_identity: str
+    inputs: tuple[tuple[str,str,int], ...]
+    dbc_path: str
+    dbc_sha256: str
+    cantools_version: str
+    record_count: int
+    decode_calls: int
+    first_ns: int | None
+    last_ns: int | None
+    unit_checks: tuple[CANUnitCheck,...]
+    frame_format_notices: tuple[CANFrameFormatNotice,...]=()
+    profile: str='can-text-v1'
+    decode_scope: str='requested'
+    time_scope: str='source'
+
+    def __post_init__(self):
+        """核实结构及计数一致性，不读文件。参数: 冻结字段。返回: None。异常: 类型/值错误。
+        """
+        for name in ('source','session_id'):
+            require_identifier(getattr(self,name),name)
+        for name in ('read_identity','dbc_path','cantools_version'):
+            require_text(getattr(self,name),name)
+        if (self.source_type not in ('can_asc','asc_or_blf','raw_can_csv') or self.profile!='can-text-v1'
+                or self.decode_scope!='requested' or self.time_scope!='source'):
+            raise ValueError('文本CAN清单策略错误')
+        if type(self.dbc_sha256) is not str or len(self.dbc_sha256)!=64 or any(c not in '0123456789abcdef' for c in self.dbc_sha256):
+            raise ValueError('文本CAN清单需要实际DBC SHA256')
+        if type(self.inputs) is not tuple or not 1<=len(self.inputs)<=4096:
+            raise ValueError('文本CAN清单需要有限有序输入')
+        for item in self.inputs:
+            if type(item) is not tuple or len(item)!=3:
+                raise ValueError('输入清单需要(path,parser,offset_ns)')
+            require_text(item[0],'path'); require_text(item[1],'parser'); require_int64_ns(item[2],'offset_ns')
+        if type(self.record_count) is not int or self.record_count<0 or type(self.decode_calls) is not int or not 0<=self.decode_calls<=self.record_count:
+            raise ValueError('文本CAN实际帧数与解码次数错误')
+        if not self.record_count:
+            if self.first_ns is not None or self.last_ns is not None:
+                raise ValueError('空文本CAN不能声明观测时间')
+        else:
+            require_int64_ns(self.first_ns,'first_ns'); require_int64_ns(self.last_ns,'last_ns')
+            if self.first_ns>self.last_ns:
+                raise ValueError('文本CAN观测时间倒退')
+        if (type(self.unit_checks) is not tuple or any(type(x) is not CANUnitCheck for x in self.unit_checks)
+                or type(self.frame_format_notices) is not tuple or any(type(x) is not CANFrameFormatNotice for x in self.frame_format_notices)):
+            raise TypeError('文本CAN单位/帧型清单需要冻结模型tuple')

chronaxis/results/threshold_metadata.py

@@ -0,0 +1,105 @@
+"""保存一次阈值报警预设在实际观测范围内的时长汇总。
+
+输入是同次迟滞状态机累计的整数纳秒，不再次读取信号或推算缺口内状态。
+有未知时间时只报告已知报警累计，完整总时长为空；无观测不返回正常零。
+快照只随有限预设数增长，由结果清单预算承担，重复发布不会重新计算。
+"""
+
+from dataclasses import dataclass
+from math import isfinite
+from ..core.models import Interval
+from ..core.validation import require_identifier
+
+
+@dataclass(frozen=True)
+class ThresholdDurationMetadata:
+    """冻结报警、已知与未知时长，完整总数只在整个观测范围已知时给出。"""
+
+    preset_id: str  # 本次计划的预设ID。
+    rule_id: str  # 实际生成的迟滞规则ID，可关联事件表。
+    observed_start_ns: int | None  # 实际时钟组起点，无观测为None。
+    observed_end_ns: int | None  # 实际时钟组末点，不向请求末端外推。
+    known_active_duration_ns: int  # 已知报警区间的准确整数纳秒和。
+    known_duration_ns: int  # 已知报警或未报警的总纳秒。
+
+    def __post_init__(self):
+        """检查固定计数和观测范围的一致性。
+
+        参数: 无。返回: None。异常: TypeError/ValueError为身份、范围或计数矛盾。
+        """
+        require_identifier(self.preset_id, 'threshold.preset_id')
+        require_identifier(self.rule_id, 'threshold.rule_id')
+        if (self.observed_start_ns is None) != (self.observed_end_ns is None):
+            raise ValueError('阈值汇总观测端点必须同时存在或同时为空')
+        if self.observed_start_ns is not None:
+            if type(self.observed_start_ns) is not int or type(self.observed_end_ns) is not int:
+                raise TypeError('阈值汇总端点须原生整数纳秒')
+            Interval(self.observed_start_ns, self.observed_end_ns)
+        if any(type(value) is not int for value in (self.known_active_duration_ns, self.known_duration_ns)):
+            raise TypeError('阈值汇总时长须原生整数纳秒')
+        if not 0 <= self.known_active_duration_ns <= self.known_duration_ns <= self.observed_duration_ns:
+            raise ValueError('报警/已知时长不得超过实际观测范围')
+
+    @property
+    def observed_duration_ns(self):
+        """取得实际半开范围长度。参数: 无。返回: int纳秒。异常: 无。"""
+        return 0 if self.observed_start_ns is None else self.observed_end_ns - self.observed_start_ns
+
+    @property
+    def unknown_duration_ns(self):
+        """取得未确定报警状态的时长。参数: 无。返回: int纳秒。异常: 无。"""
+        return self.observed_duration_ns - self.known_duration_ns
+
+    @property
+    def total_duration_ns(self):
+        """完整总时长不能由未知区间推测。参数: 无。返回: int或None。异常: 无。"""
+        return self.known_active_duration_ns if self.observed_duration_ns > 0 and self.unknown_duration_ns == 0 else None
+
+    @property
+    def status(self):
+        """区分完整、部分、全未知和无观测。参数: 无。返回: 状态文本。异常: 无。"""
+        if self.observed_duration_ns == 0:
+            return 'no_observation'
+        if self.known_duration_ns == 0:
+            return 'indeterminate'
+        return 'partial' if self.unknown_duration_ns else 'complete'
+
+    def to_dict(self):
+        """将纳秒事实及便于阅读的秒数写入清单。
+
+        参数: 无。返回: 独立dict。异常: 无；调用方在复制前预付元数据费用。
+        """
+        return dict(preset_id=self.preset_id, rule_id=self.rule_id,
+            observed_start_ns=self.observed_start_ns, observed_end_ns=self.observed_end_ns,
+            observed_duration_ns=self.observed_duration_ns, known_duration_ns=self.known_duration_ns,
+            known_active_duration_ns=self.known_active_duration_ns, unknown_duration_ns=self.unknown_duration_ns,
+            total_duration_ns=self.total_duration_ns,
+            total_duration_s=None if self.total_duration_ns is None else self.total_duration_ns / 10**9,
+            known_active_duration_s=self.known_active_duration_ns / 10**9, status=self.status)
+
+
+@dataclass(frozen=True)
+class SummaryThresholdDuration:
+    """新合同只保存一个累计值和单位；partial说明它只是已知部分。"""
+
+    preset_id: str
+    rule_id: str
+    value: float | None
+    status: str
+    unit: str = 's'
+
+    def __post_init__(self):
+        """检查唯一单位和未知总量。参数: 无。返回: None。异常: 非法身份/数值/状态。"""
+        require_identifier(self.preset_id,'preset_id')
+        require_identifier(self.rule_id,'rule_id')
+        if self.value is not None and (type(self.value) not in (int,float) or not isfinite(self.value) or self.value<0):
+            raise ValueError('报警时长必须为非负有限值或未知')
+        if self.unit!='s' or self.status not in ('no_observation','indeterminate','partial','complete'):
+            raise ValueError('报警汇总单位或状态无效')
+        if (self.status in ('no_observation','indeterminate')) != (self.value is None):
+            raise ValueError('无观测/全未知为空，完整或部分累计必须有可核实值')
+
+    def to_dict(self):
+        """发布一种数值单位，不附重复ns/s或时间范围。参数: 无。返回: dict。异常: 无。"""
+        return dict(preset_id=self.preset_id,rule_id=self.rule_id,unit=self.unit,
+            value=self.value,status=self.status)

chronaxis/runner.py

@@ -0,0 +1,121 @@
+"""把分析计划交给同一公共入口检查、解释和执行，返回可流式读取的结果。
+
+AnalysisRunner接收已经由load_analysis_plan或AnalysisPlan.from_dict构建的计划。validate和explain
+只查看声明，沿用planning.reports，不打开CSV、DBC或旧日志。run才创建独立
+RunSession，首次扫描来源、封存新历史并依次运行已有四个分析阶段；这里不重写
+读取、数值算法或发布。返回AnalysisResult表示analysis_complete，write另行发布。
+
+显式backend只替换内部执行视图中的计算方式，保留原配置identity、raw_config和
+来源对象；清单另记实际后端。AnalysisRunner本身没有输入、FD或跨运行状态，能够重复运行
+同一计划，每次使用独立资源。成功前全部输入关闭；失败保原cause及最高运行恢复
+owner，取消保原KeyboardInterrupt/SystemExit。暂存与诊断保留，不宣称回滚输入。
+"""
+
+# 只在run时加载实际执行组件；静态检查不创建预算、工作目录或来源adapter。
+from dataclasses import replace
+from .planning.plan import AnalysisPlan
+from .planning.models import ExecutionPlan
+from .planning.reports import validate_analysis_plan, explain_analysis_plan
+from .results.errors import AnalysisError
+from .results.spool import _cleanup_owner
+
+
+class AnalysisRunner:
+    """保存可选后端覆盖，复用同一静态校验，逐次创建独立运行资源。
+
+    _backend为None或已支持的明确后端，不自动回退。实例不持有执行结果或活动
+    session；结果所有权交给调用者，失败未清完资源通过原异常的最高owner恢复。
+    """
+
+    def __init__(self, backend=None):
+        """选择是否覆盖计划后端，不读取任何来源或配置文件。
+
+        参数: backend为None/reference/numpy；None使用各次计划原execution.backend。
+        返回: None；初始化实例状态。异常: TypeError为非文本覆盖；ValueError为未知后端。
+        """
+        # 明确拒绝任意对象和隐藏回退，不能把拼错的后端当成默认NumPy。
+        if backend is not None:
+            if type(backend) is not str:
+                raise TypeError('AnalysisRunner backend需要reference、numpy或None')
+            if backend not in ('reference', 'numpy'):
+                raise ValueError('AnalysisRunner仅支持reference与numpy后端')
+        self._backend = backend
+
+    @property
+    def backend(self):
+        """读取构造时的覆盖选择，不表示某个尚未运行计划的实际后端。
+
+        参数: 无。返回: None/reference/numpy。异常: 无。
+        """
+        return self._backend
+
+    def _effective_plan(self, plan):
+        """保留原声明身份，只为明确覆盖创建内部执行视图。
+
+        参数: plan为已构建AnalysisPlan。返回: 原plan或仅execution.backend不同的新view。
+        异常: TypeError为非计划/执行声明；不重新解析配置或复制原输入行。
+        """
+        if not isinstance(plan, AnalysisPlan) or not isinstance(plan.execution, ExecutionPlan):
+            raise TypeError('AnalysisRunner需要load_analysis_plan或AnalysisPlan.from_dict构建的计划')
+        # 来源、绑定及raw_config仍借原对象；后端是本次执行选项，不伪造另一份输入。
+        if self._backend is None or self._backend == plan.execution.backend:
+            return plan
+        return replace(plan, execution=replace(plan.execution, backend=self._backend))
+
+    def validate(self, plan):
+        """报告声明是否合法及执行路径是否已接入，不提前读取数据。
+
+        参数: plan为已构建AnalysisPlan。返回: 同一共享ValidationReport，保留实际字段/范围未验警告。
+        异常: TypeError为非AnalysisPlan或非法执行模型；正常计划的静态问题写入报告errors，
+            不以校验成功证明输入文件内容有效。副作用: 无来源I/O或目录创建。
+        """
+        # 使用相同有效视图和纯静态报告，避免校验后偷偷换另一套后端能力。
+        return validate_analysis_plan(self._effective_plan(plan))
+
+    def explain(self, plan):
+        """列出真实依赖、各节点后端、历史需求及声明预算，不启动分析。
+
+        参数: plan为已构建AnalysisPlan。返回: ExplainReport，plan_identity保原声明身份。
+        异常: TypeError为非AnalysisPlan或非法执行模型；调用者绕过解析器手工破坏typed
+            引用时可能产生AttributeError/KeyError，应重新从完整配置构造计划。
+        副作用: 不读取CSV/DBC，也不测量实耗。
+        """
+        # 规则状态驱动与数组节点分别由同一报告说明，不把覆盖当整个计划标量回退。
+        return explain_analysis_plan(self._effective_plan(plan))
+
+    def run(self, plan, work_dir=None):
+        """验证后执行一次真实分析，输入全关才返回独立AnalysisResult。
+
+        参数: plan为已构建AnalysisPlan；work_dir为全新工作目录或None（唯一专用目录）。
+        返回: analysis_complete的AnalysisResult，由调用者close/上下文管理，write另行发布。
+        异常: TypeError为错误plan；验证或运行错误为AnalysisError，保原cause和诊断；
+            KeyboardInterrupt/SystemExit原样传播。持续清理失败用runner_cleanup_owner.close恢复。
+        副作用: 创建本次新暂存；扫描来源一次、后续仅回读新history，不自动删除或发布文件。
+        """
+        effective = self._effective_plan(plan)
+        validation = validate_analysis_plan(effective)
+        if validation.errors or not validation.valid or not validation.execution_ready:
+            raise AnalysisError('计划尚不能执行：' + ('；'.join(validation.errors) or '所需执行路径不可用'))
+        session = None
+        try:
+            # 惰性加载保证validate/explain没有实际来源组件的创建或调用。
+            from .execution.run_session import RunSession
+            session = RunSession(effective, work_dir=work_dir)
+            return session.execute()
+        except BaseException as exc:
+            # 未返回构造有自己的最高owner；正常构造后仍由唯一session关闭全部本次资源。
+            owner = getattr(exc, 'runner_cleanup_owner', None)
+            if owner is None:
+                owner = session
+            if owner is not None:
+                _cleanup_owner(owner, exc, 'runner_cleanup_owner', '公共分析运行')
+            # 保留原分析异常与取消类型；其他业务错误通过cause说明最初失败位置。
+            if isinstance(exc, (AnalysisError, KeyboardInterrupt, SystemExit)):
+                raise
+            error = AnalysisError('分析运行失败：' + str(exc))
+            recovery = getattr(exc, 'runner_cleanup_owner', None)
+            if recovery is not None:
+                error.runner_cleanup_owner = recovery
+            for note in getattr(exc, '__notes__', ()):
+                error.add_note(note)
+            raise error from exc

chronaxis/sources/__init__.py

@@ -0,0 +1,23 @@
+"""公开内存来源、已解码信号表及公共批次协议。
+
+MemorySourceAdapter接收已有内存原行，SignalCSVSourceAdapter接收明确格式
+的已解码CSV配置；二者逐批输出SignalSeries和SignalBatch，并共用
+SourceDescription、ReadRequest及BatchValidator的身份与进度检查。
+导入只加载类型和计算模块，不打开输入文件或DBC，也不创建工作目录。
+CAN配置与原报文定位在can_spec，公共AnalysisRunner已接单BLF/单DBC的旧公开链；
+本模块的内存/CSV入口不代替CAN运行包装，也不代表其他旧入口已迁移。
+"""
+
+# 内存适配器传送已有原行的更新，不构造完整历史保持序列。
+from .memory import MemorySourceAdapter
+# CSV配置与逐样本定位用于明确的已解码表，不根据后缀猜原始报文。
+from .csv_spec import CSVSourceRef, SignalCSVSpec
+# 静态导入不会打开CSV，读取由实际迭代器执行。
+from .signal_csv import SignalCSVSourceAdapter
+# 对外暴露有结构校验的类型，不用object占位。
+from .models import FieldDescription, FieldLocation, ReadRequest, SignalBatch, SignalSeries, SourceCapabilities, SourceDescription
+# 生命周期协议和跨批校验可由其他已解码来源适配器共用。
+from .protocol import BatchValidator, SourceAdapter, SourceClosedError, SourceReadError
+
+# 保留内存/CSV与通用批次的公开名单；CAN通过计划与AnalysisRunner入口执行。
+__all__ = ['MemorySourceAdapter', 'SignalCSVSpec', 'CSVSourceRef', 'SignalCSVSourceAdapter', 'FieldDescription', 'FieldLocation', 'ReadRequest', 'SignalBatch', 'SignalSeries', 'SourceCapabilities', 'SourceDescription', 'BatchValidator', 'SourceAdapter', 'SourceClosedError', 'SourceReadError']