chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/planning/plan.py

@@ -0,0 +1,294 @@
+"""把分析配置转换成经过静态检查的分析计划。
+
+使用入口：
+    AnalysisPlan.from_dict(config, base_dir=...)接收一个配置字典。
+    load_analysis_plan(path)读取一个JSON/YAML配置文件，再调用from_dict检查内容。
+输出都是AnalysisPlan，其中保存来源、信号、表达式、规则、窗口和指标，
+以及计划采用的计算方式、资源预算和输出格式。
+
+处理顺序是：检查字段与版本 → 复制配置 → 检查来源和信号声明
+→ 检查表达式及相互引用 → 保存计划。静态检查是根据配置声明判断
+是否合法，不读取待分析的日志或CSV；省略CAN信号元数据时按需读DBC，不执行计算。
+
+from_dict的相对路径以base_dir为基准，省略时使用当前工作目录；
+load_analysis_plan以各定义的声明文件所在目录为基准，一层imports先展开。路径只转换为绝对定位，不读取目标。
+配置字典和列表会复制并冻结，调用者之后修改原配置不会改变计划快照。
+
+当前计划支持的来源由parse_sources检查；预设先校验角色并合入公共节点；尚未接入的旧profile、
+旧完整积分兼容和未接入原始输出格式会被拒绝。message_calculations仅显式
+current_message-v1逐消息计算；原帧和重建帧统一由can_frames声明。
+execution中的预算与outputs中的格式
+只是经过检查的声明；实际执行由AnalysisRunner落实，文件发布由AnalysisResult.write负责。
+配置通过不表示本次来源已读取、实际结果或输出已经验证。
+identity用于区分配置和来源定位声明，不证明磁盘上的输入内容已经核实。
+
+本模块依赖核心声明模型和planning中的字段检查、来源解析及节点解析。
+from_dict不执行输入I/O；load_analysis_plan只打开指定配置及一层公共定义文件并及时关闭句柄。
+"""
+
+# 创建不可变模型并计算声明哈希；语法解析交共享配置入口。
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from collections.abc import Mapping
+# 核心模型提供本计划的名称、来源关系和时间范围检查。
+from ..core.declarations import DeclarationBindings, DeclaredSource
+from ..core.expression import DerivedDefinition, StaticExpression
+from .config_groups import public_errors
+from ..core.models import Interval
+from ..core.types import TimeType
+# 固定CAN配置和profile标识只含静态模型，不导入reader、writer或旧依赖。
+from ..sources.can_spec import LegacyCANSpec
+from ..legacy.records import PROFILE_ID
+# 字段、来源和计算节点分别交给对应解析模块。
+from ..configuration import load_configuration, ConfigurationError
+from ..configuration.diagnostics import locate_error
+from .checks import (PlanValidationError, configuration_error, array_at, canonical, choice_at, coordinate_at, json_value,
+                     metadata_at, model_at, number_at, object_at, require_json_value, text_at, timezone_at)
+from .inputs import parse_sources, parse_signals
+from .models import DatasetPlan, DerivedPlan, ExecutionPlan, MessageCalculationPlan, CalculationPlan, OutputPlan, RulePlan, SignalPlan, SourcePlan, WindowPlan
+from .message_calculations import parse_message_calculations
+from .legacy_execution import require_can_decode_scope
+from .nodes import expression_at, parse_calculations, parse_rules, parse_windows
+from .preset_models import PresetSpec, RoleBinding
+from .sequences import SequencePlan, parse_sequences
+from .intervals import IntervalPlan, DiagnosticPlan
+
+
+@dataclass(frozen=True)
+class AnalysisPlan:
+    """保存一个会话的分析配置，以及静态检查得到的对象。
+
+    通过from_dict或load_analysis_plan构建，依次保存输入来源、信号、派生计算、
+    条件规则、窗口与指标。实例字段不能重新赋值；原配置及自由元数据
+    保存为独立的只读快照，不保留调用者可变字典或列表的引用。
+
+    bindings只描述“哪个信号来自哪里”，derived_expressions是已检查的
+    表达式结构；二者不表示真实数据已经读取或能够直接运行。
+    execution与outputs保存执行及输出声明，创建本类不会启动计算或发布文件。
+
+    identity由配置和来源定位声明计算，用于区分计划；不能据此断言CSV内容、
+    实际列、内存使用或分析结果已核实。各次构建的绑定和声明相互独立。
+    """
+
+    config_version: int  # 唯一当前结构版本3；执行接线由能力报告约束。
+    dataset: DatasetPlan  # 分析对象、会话和请求时间范围。
+    sources: tuple[SourcePlan, ...]  # 已解析的来源配置，保持用户声明顺序。
+    signals: tuple[SignalPlan, ...]  # 原字段与信号名称、类型、单位及有效期声明。
+    derived: tuple[DerivedPlan, ...]  # 由已有信号计算的新信号，例如功率及其元数据。
+    rules: tuple[RulePlan, ...]  # 已经检查的布尔条件和时序规则。
+    windows: tuple[WindowPlan, ...]  # 已检查的活动或时间点窗口，以及所引用的规则。
+    calculations: tuple[CalculationPlan, ...]  # 统计指标及其范围、计算口径、单位和缺失数据策略。
+    presets: tuple[PresetSpec, ...]  # 原预设v1声明，冻结并保留生成参数。
+    preset_bindings: tuple[tuple[RoleBinding, ...], ...]  # 本次解析角色的原定义与契约，不继承旧来源。
+    execution: ExecutionPlan  # 计算方式、分批大小和资源预算声明，尚未实际执行。
+    outputs: OutputPlan  # 结果表及清单的格式声明，尚未写出文件。
+    bindings: DeclarationBindings  # 名称与来源之间的声明关系，不含实际读取的信号值。
+    derived_expressions: tuple[StaticExpression, ...]  # 全部派生表达式的检查结果，已拒绝循环依赖。
+    metadata: Mapping  # 调用者附加的只读元数据，不改变计算规则。
+    raw_config: Mapping  # 原配置的独立只读副本。
+    base_dir: Path  # 相对来源路径的解释基准，保存为绝对路径。
+    identity: str  # 配置及来源定位声明的SHA-256哈希，不是文件内容哈希。
+    message_calculations: tuple[MessageCalculationPlan, ...] = ()  # 显式当前消息计算；旧位置参数及缺省行为保留。
+    sequences: tuple[SequencePlan, ...] = ()  # 可选点事件FIFO配对；旧计划不增加结果表。
+    intervals: 'IntervalPlan | None' = None  # 当前记录流的有限间隔声明。
+    diagnostics: 'DiagnosticPlan | None' = None  # 分别声明追溯、完整性检查与现场留存。
+
+    @classmethod
+    @public_errors
+    def from_dict(cls, config: dict, *, base_dir: Path | str | None = None) -> 'AnalysisPlan':
+        """复制配置字典，检查版本3的静态要求；新版本执行能力另行验证。
+
+        参数:
+            config (dict): 使用Python原生字典、列表和标量的分析声明；可由YAML加载取得。
+                必填config_version、dataset、sources、signals；derived、rules、windows、
+                sequences、calculations、message_calculations、presets、execution、outputs、
+                intervals、diagnostics和metadata按需提供。完整结构见用户手册配置字段参考。
+                字段、名称、表达式和引用都按对应规则检查。
+            base_dir (Path | str | None): 相对来源路径的解释基准；默认None，
+                使用当前工作目录。传入Path或文本时转换为绝对路径。
+        返回:
+            AnalysisPlan: 保存经过静态检查的来源、信号及计算节点。
+                raw_config和metadata是独立的只读快照；创建计划不读取分析数据。
+        异常:
+            PlanValidationError: 字段或版本不合法，名称冲突、表达式或引用错误，
+                输入模型不合规，或配置请求尚未接入的能力；错误保留配置位置。
+            OSError: 获取当前工作目录或转换路径时发生系统错误，可原样传播。
+        处理流程:
+            1. 检查顶层字段、复制JSON结构，并核对当前配置结构版本。
+            2. 解析来源、会话范围和信号声明，建立本计划的名称与来源关系。
+            3. 检查全部派生表达式、规则、窗口、指标及执行和输出选项。
+            4. 计算声明哈希并返回计划；此阶段不打开来源文件或执行分析。
+        """
+        # 先检查顶层必填项和允许项；附加信息只能放在metadata中。
+        if type(config) is dict and 'imports' in config:
+            raise PlanValidationError('$.imports','from_dict不读取公共定义文件','unresolved_imports',
+                                      hint='使用load_analysis_plan加载配置文件，或传入config resolve展开后的字典')
+        root = object_at(config, '$', ('config_version', 'dataset', 'sources', 'signals'),
+                         ('derived', 'rules', 'windows', 'calculations', 'presets', 'message_calculations', 'sequences', 'execution', 'outputs', 'metadata', 'intervals', 'diagnostics'))
+        # 复制并冻结配置，拒绝非JSON值、非有限数和非文本键。
+        # 先保留原JSON类型及循环诊断，再冻结，避免tuple被隐式转为合法数组。
+        require_json_value(root, '$')
+        frozen = metadata_at(root, '$')
+        # 用副本继续解析，避免调用者之后修改原配置影响本次检查。
+        root = json_value(frozen)
+        from .config_groups import normalize_configuration
+        root = normalize_configuration(root)
+        # 当前唯一结构采用记录间隔和按需输出默认值。
+        version = choice_at(root['config_version'], (3,), '$.config_version')
+        # 只接受Path或文本路径；这里不读取目标或解析符号链接。
+        if base_dir is not None and not isinstance(base_dir, (Path, str)):
+            # 拒绝其他对象，避免配置触发自定义路径转换代码。
+            raise PlanValidationError('$', 'base_dir必须为Path或文本')
+        # 省略base_dir时使用当前工作目录，否则将基准转为绝对路径。
+        base = Path.cwd() if base_dir is None else Path(base_dir).absolute()
+        # 解析来源配置，保存定位和格式声明；此时仍不打开CSV。
+        sources = parse_sources(root['sources'], base)
+        # 以首个来源声明的时钟作为分析基准，多源关系在依赖检查时核对。
+        timebase = sources[0].config.timebase
+        # dataset只接受规定的单对象、单会话和时间范围字段。
+        raw_dataset = object_at(root['dataset'], '$.dataset', ('name',), ('entity', 'session', 'domain', 'metadata'))
+        # 检查数据集名称，避免把路径或表达式当作标识。
+        dataset_id = text_at(raw_dataset['name'], '$.dataset.name', identifier=True)
+        # 普通单任务沿用数据集名；对象与会话仍由本次计划实例隔离，不共享状态。
+        entity = text_at(raw_dataset.get('entity', dataset_id), '$.dataset.entity', identifier=True)
+        session = text_at(raw_dataset.get('session', dataset_id), '$.dataset.session', identifier=True)
+        # 省略domain是真正的无时间筛选声明，不制造假端点或实际观测范围。
+        domain_explicit = 'domain' in raw_dataset
+        domain = None
+        if domain_explicit:
+            # 只有用户显式请求时间域才解析坐标；显式null仍是配置错误。
+            raw_domain = object_at(raw_dataset['domain'], '$.dataset.domain', ('start', 'end'))
+            tz = timezone_at(sources[0].timezone_text, '$.dataset.domain.timezone')
+            start = coordinate_at(raw_domain['start'], '$.dataset.domain.start', absolute=timebase.time_type is TimeType.ABSOLUTE, tz=tz)
+            end = coordinate_at(raw_domain['end'], '$.dataset.domain.end', absolute=timebase.time_type is TimeType.ABSOLUTE, tz=tz)
+            domain = model_at(Interval, '$.dataset.domain', start, end)
+        # 保存对象、会话、范围和只读元数据，供后续引用。
+        dataset = DatasetPlan(dataset_id, entity, session, domain, timebase,
+            metadata_at(raw_dataset.get('metadata', {}), '$.dataset.metadata'), domain_explicit)
+        # 检查每个信号的原字段、类型、单位转换、有效期和来源定位。
+        signals = parse_signals(root['signals'], sources)
+        # 延迟导入避免公开预设直接导入时产生模块循环；只对局部副本展开，无来源I/O。
+        from ..presets import expand_presets
+        presets, preset_bindings = expand_presets(root, tuple(item.definition for item in signals))
+        # 派生项按名称组织；类型由表达式推导，不单独指定有效期。
+        raw_derived = root.get('derived', {})
+        # 派生项必须是名称到配置的字典，不能由数组位置猜名称。
+        if type(raw_derived) is not dict:
+            # 在建立依赖图之前拒绝错误的派生配置结构。
+            raise PlanValidationError('$.derived', 'derived必须为别名对象')
+        # 保持用户声明顺序，收集已经检查的派生项。
+        derived = []
+        # 逐项检查字段与元数据；收集完成后再检查整个表达式依赖图。
+        for name, item in raw_derived.items():
+            # 记录当前派生项的配置位置，供错误信息定位。
+            path = f'$.derived.{name}'
+            # 先检查名称是否合法；表达式别名不能包含属性访问语法。
+            text_at(name, path, identifier=True)
+            # 只接受规定的表达式、单位和可选语义字段，拒绝未知字段。
+            item = object_at(item, path, ('expr',), ('unit', 'semantic_id', 'semantic_contract_version', 'sign_convention', 'measurement_location', 'metadata'))
+            # 建立派生声明，由核心检查表达式文本和单位是否有效。
+            unit = text_at(item['unit'], path + '.unit') if 'unit' in item else None
+            definition = model_at(DerivedDefinition, path, name, item['expr'], unit)
+            # 保存可选语义信息；名称相同不能证明测量含义一致。
+            annotations = tuple(text_at(item[key], path + '.' + key) if key in item else None for key in ('semantic_id', 'semantic_contract_version', 'sign_convention', 'measurement_location'))
+            # 保存只读元数据；表达式不能通过对象属性访问这些信息。
+            derived.append(DerivedPlan(definition, *annotations, metadata_at(item.get('metadata', {}), path + '.metadata')))
+        # 将来源名称、时钟、定位声明和偏移组合为检查用对象。
+        declared_sources = tuple(DeclaredSource(item.name, item.config.timebase, item.input_identity, item.config.offset_ns) for item in sources)
+        # 在当前会话内统一检查来源、信号和派生名称，建立声明关系。
+        bindings = model_at(DeclarationBindings, '$.signals/derived', session, timebase, domain, declared_sources,
+                            tuple(item.definition for item in signals), tuple(item.definition.name for item in derived))
+        # 检查所有派生定义，包括未被引用的项，拒绝未知名称或循环依赖。
+        definitions = tuple(item.definition for item in derived)
+        # 保存已经检查的表达式结构，不把配置文本当作Python代码执行。
+        expressions = tuple(expression_at(item.name, f'$.derived.{item.name}.expr', bindings, definitions, unit=item.unit) for item in definitions)
+        # 逐项检查执行选项及默认值；资源预算由实际执行器落实。
+        raw_execution = object_at(root.get('execution', {}), '$.execution', (), ('backend', 'batch_rows', 'memory_budget_bytes', 'result_buffer_rows', 'partial_policy', 'on_budget_exceeded', 'spool_quota_bytes'))
+        # 只允许'numpy'或'reference'，不为未知实现名称自动回退。
+        backend = choice_at(raw_execution.get('backend', 'numpy'), ('numpy', 'reference'), '$.execution.backend')
+        # 分批行数、内存预算和结果缓冲行数必须为正整数，不能是布尔值。
+        limits = tuple(number_at(raw_execution.get(key, default), '$.execution.' + key, integer=True, minimum=1) for key, default in (('batch_rows', 65536), ('memory_budget_bytes', 268435456), ('result_buffer_rows', 4096)))
+        # 检查数据覆盖不完整时采用'report'还是'strict'策略。
+        partial = choice_at(raw_execution.get('partial_policy', 'report'), ('report', 'strict'), '$.execution.partial_policy')
+        # 超出资源预算的处理只接受'error'，不允许静默丢数据。
+        choice_at(raw_execution.get('on_budget_exceeded', 'error'), ('error',), '$.execution.on_budget_exceeded')
+        # 磁盘配额若给出则必须为正整数；None表示没有配置该配额。
+        quota = number_at(raw_execution['spool_quota_bytes'], '$.execution.spool_quota_bytes', integer=True, minimum=1) if raw_execution.get('spool_quota_bytes') is not None else None
+        # 保存检查后的执行选项，包含本次实际采用的默认值。
+        execution = ExecutionPlan(backend, *limits, partial, quota)
+        # 规则、窗口和指标共用标识集合，避免同一计划出现重复ID。
+        ids = set()
+        # 先检查条件和规则，供窗口按当前规则名称建立引用。
+        rules = parse_rules(root.get('rules', []), bindings, definitions, ids)
+        # 检查活动合并或固定窗口的边界与引用关系。
+        windows = parse_windows(root.get('windows', []), rules, ids)
+        # 检查指标所用值、条件、统计范围、联合来源依赖和单位。
+        calculations = parse_calculations(root.get('calculations', []), bindings, definitions, rules, windows, execution, ids)
+        # 新消息模式在同一ID空间解析；不向原配置副本补默认，旧plan身份recipe保持。
+        message_calculations = parse_message_calculations(root.get('message_calculations', []), sources, bindings, ids)
+        sequences = parse_sequences(root.get('sequences', []), rules, bindings, ids)
+        # 检查结果输出配置，此处仅保存格式，不创建输出文件。
+        raw_outputs = object_at(root.get('outputs', {}), '$.outputs', (), ('tables', 'manifest', 'contributions','signal_csv','can_frames'))
+        # 结果表只接受CSV或JSONL，清单只接受JSON。
+        outputs = OutputPlan(choice_at(raw_outputs.get('tables', 'readable_csv'), ('readable_csv', 'csv', 'jsonl'), '$.outputs.tables'), choice_at(raw_outputs.get('manifest', 'json'), ('json',), '$.outputs.manifest'),
+            choice_at(raw_outputs.get('contributions', 'none'), ('none', 'full'), '$.outputs.contributions'))
+        # 新导出默认关闭；解析只核引用和时间政策，不创建原始读取器或加载DBC。
+        from dataclasses import replace
+        from .export_options import parse_signal_output,parse_frame_output
+        outputs=replace(outputs,signal_csv=parse_signal_output(raw_outputs.get('signal_csv'),signals,windows,sources=sources),
+            can_frames=parse_frame_output(raw_outputs.get('can_frames'),sources,windows))
+        # 对配置副本和来源定位声明计算哈希，不读取文件内容。
+        identity = sha256(canonical({'plan_version': 'config3-static-v1', 'config': frozen, 'sources': [item.input_identity for item in sources]}).encode('utf-8')).hexdigest()
+        # 返回完整计划；原配置和附加元数据均保存为独立的只读副本。
+        plan = cls(version, dataset, sources, signals, tuple(derived), rules, windows, calculations, presets, preset_bindings, execution, outputs,
+                   bindings, expressions, metadata_at(root.get('metadata', {}), '$.metadata'), frozen, base, identity,
+                   message_calculations=message_calculations, sequences=sequences)
+        # 在全部消费者已确定后解析有限间隔选择，DBC实际周期留运行初始化。
+        from .intervals import parse_intervals, parse_diagnostics
+        plan = replace(plan, intervals=parse_intervals(root.get('intervals', {}), plan),
+                       diagnostics=parse_diagnostics(root.get('diagnostics', {})))
+        # 省略范围由同一次读取的实际观测确定，不提前扫描或补造时间端点。
+        # 来源策略依赖最终输出与全部节点；完整计划确定后再拒绝不支持的requested组合。
+        require_can_decode_scope(plan)
+        return plan
+
+
+
+def load_analysis_plan(path: Path | str) -> AnalysisPlan:
+    """读取JSON/YAML配置及一层公共定义，按各自声明目录解释相对来源路径。
+
+    参数:
+        path (Path | str): 配置文件路径；不接受目录扫描或任意路径对象。
+            配置按UTF-8读取，允许文件开头带BOM。
+    返回:
+        AnalysisPlan: 经过from_dict静态检查的计划。只读取主配置和显式公共定义文件，
+            不打开其中声明的日志、CSV或DBC。
+    异常:
+        PlanValidationError: 路径类型错误、文件读取或编码错误、JSON/YAML语法错误、
+            重复键、非有限常量或配置声明错误。加载错误带配置文件定位，
+            通过原异常链保留更详细的原因。
+    副作用:
+        打开指定配置文件，正常或异常退出时均关闭句柄；不写文件。
+    """
+    # 与from_dict一致，只接受Path或文本配置路径。
+    if not isinstance(path, (Path, str)):
+        # 类型错误直接定位到配置路径参数。
+        raise PlanValidationError('$', '配置路径必须为Path或文本')
+    # 转为绝对路径，用于打开指定配置及关联错误位置。
+    target = Path(path).absolute()
+    # 将文件读取、编码、语法和配置检查错误统一关联到该文件。
+    try:
+        document = load_configuration(target)
+        from ..configuration.imports import expand_document_imports
+        document = expand_document_imports(document)
+        # 配置文件的词法父目录继续作为相对来源定位基准，不读取来源。
+        return AnalysisPlan.from_dict(document.data, base_dir=target.parent)
+    except ConfigurationError as error:
+        raise configuration_error(error) from error
+    except PlanValidationError as error:
+        raise locate_error(error,document)
+    # 包装读取与配置检查异常，并保留原异常链。
+    except (OSError, UnicodeError, ValueError, TypeError) as error:
+        # 已有配置错误保留错误码，其他加载错误使用'load_error'。
+        raise PlanValidationError('$',str(error),'load_error',source=str(target)) from error

chronaxis/planning/preset_models.py

@@ -0,0 +1,211 @@
+"""保存预设v1的公开不可变声明、角色契约及可序列化计划片段。
+
+输入JSON参数及类型化信号引用，输出冻结spec、角色追溯和公共节点声明。
+先校验spec结构并深复制参数，再由外部构建器检查工程契约；本模块不运行I/O或分析。
+声明模型独立于构建器/AnalysisPlan，两个入口共用真实类型，避免循环导入及不可解析注解。
+候选语义名仅是领域预设v1本地协议；不建立核心目录，不伪造时钟/来源/工程结论。
+序列化产生独立JSON副本，节点仍须由正常公共编译器检查依赖与单位。
+"""
+
+# 不可变模型及结构校验不依赖预设算法或公开计划。
+from collections.abc import Mapping
+from dataclasses import dataclass
+from ..core.binding import SignalDefinition
+from ..core.expression import DerivedDefinition
+from ..core.types import SignalDType as D
+from ..core.windows import WindowSpec
+from .checks import (PlanValidationError, choice_at, json_value, metadata_at,
+                     object_at, require_json_value, text_at)
+from .sequences import SequencePlan
+
+
+@dataclass(frozen=True)
+class RoleContract:
+    """公开本预设版本的角色类型、单位、语义候选、方向与位置要求。
+
+    有效期必须由SignalDefinition明确提供且正；基础质量使用其固定九位禁用策略。
+    semantic_id/version仅用于自动查找，显式绑定仍逐字段检查，不能只凭版本宣称符合。
+    """
+
+    role: str  # mode/current/voltage/alarm；不注册全量领域名称。
+    dtypes: tuple[D, ...]  # 转换后的可接受逻辑类型。
+    unit: str  # 精确目标单位，关系须verified。
+    semantic_id: str  # 本模块v1候选标识，大小写敏感。
+    sign_convention: str | None = None  # 需要时为明确转换后方向。
+    measurement_location: str | None = None  # 需要时为明确测量位置。
+    version: str = '1'  # 本公开候选契约版本。
+    forbidden_quality: int = 511  # 核心已定义九位基础质量全部禁止。
+
+
+# 每个角色仅声明预设实际需要的内容；无通用汽车/电池本体。
+CHARGE_ROLES = (
+    RoleContract('mode', (D.INT64, D.UINT64), '1', 'battery.mode'),
+    RoleContract('current', (D.FLOAT64,), 'A', 'battery.current', 'positive_is_charge', 'pack_terminal'),
+    RoleContract('voltage', (D.FLOAT64,), 'V', 'battery.voltage', measurement_location='pack_terminal'),
+)
+FAULT_ROLES = (RoleContract('alarm', (D.BOOL,), '1', 'fault.alarm'),)
+COMMAND_ROLES = (RoleContract('request', (D.BOOL,), '1', 'command.request'),
+                 RoleContract('response', (D.BOOL,), '1', 'command.response'))
+
+
+@dataclass(frozen=True)
+class PresetSpec:
+    """冻结预设ID、preset_type/version、角色别名及工程参数的独立JSON快照。
+
+    id只用简单标识；role_bindings值只引用当前计划简单别名，不能写领域属性路径。
+    parameters不保留调用者可变对象，实际preset_type参数在build_preset中统一校验。
+    """
+
+    id: str  # 生成节点的明确前缀，不自动加后缀解冲突。
+    preset_type: str  # charge_session、fault_context、command_response或threshold_excursion。
+    version: str  # 当前仅'1'。
+    role_bindings: Mapping  # 只读角色→简单别名。
+    parameters: Mapping  # 深冻结JSON工程声明。
+
+    def __post_init__(self):
+        """检查公开spec结构并复制冻结，不运行数据计算。
+
+        参数: 无；读取构造字段。
+        返回: None，字段保存独立只读副本。
+        异常: PlanValidationError为名称、版本、JSON结构或角色别名错误。
+        """
+        # 公共入口与JSON路径使用同一严格名称/版本检查。
+        text_at(self.id, '$.preset.name', identifier=True)
+        choice_at(self.preset_type, ('charge_session', 'fault_context', 'command_response', 'threshold_excursion'), '$.preset.preset_type')
+        choice_at(self.version, ('1',), '$.preset.version')
+        # Mapping只用于冻结后再构建；不接受数组或任意对象作声明。
+        if not isinstance(self.role_bindings, Mapping) or not isinstance(self.parameters, Mapping):
+            raise PlanValidationError('$.preset', 'role_bindings/parameters必须为对象')
+        roles = dict(self.role_bindings)
+        parameters = dict(self.parameters) if type(self.parameters) is dict else json_value(self.parameters)
+        require_json_value(roles, '$.preset.role_bindings')
+        require_json_value(parameters, '$.preset.parameters')
+        for role, alias in roles.items():
+            text_at(role, '$.preset.role_bindings', identifier=True)
+            text_at(alias, '$.preset.role_bindings.' + role, identifier=True)
+        object.__setattr__(self, 'role_bindings', metadata_at(roles, '$.preset.role_bindings'))
+        object.__setattr__(self, 'parameters', metadata_at(parameters, '$.preset.parameters'))
+
+    @classmethod
+    def from_dict(cls, value):
+        """从当前配置的预设对象构造公开不可变声明。
+
+        参数: value为原生JSON对象，必填name/preset_type/parameters，可选version/role_bindings。
+        返回: PresetSpec，role_bindings缺省为空。
+        异常: PlanValidationError为未知键、缺项或构造协议错误。
+        """
+        # 自由元数据不能借预设参数绕过契约。
+        raw = object_at(value, '$.preset', ('name', 'preset_type', 'parameters'), ('version', 'role_bindings'))
+        return cls(raw['name'], raw['preset_type'], raw.get('version', '1'), raw.get('role_bindings', {}), raw['parameters'])
+
+
+@dataclass(frozen=True)
+class RoleBinding:
+    """保存已通过字段契约的角色及其原信号定义，供调用者追溯转换与来源。
+
+    自动/显式查找方式不同，但definition保留完整来源、单位、方向转换和质量身份。
+    不保存样本值，也不伪称元数据的物理事实已由系统测量核实。
+    """
+
+    contract: RoleContract  # 本次实际校验的v1角色。
+    definition: SignalDefinition  # 原不可变完整绑定，包含转换证据。
+    resolution: str  # explicit或semantic_unique。
+
+
+@dataclass(frozen=True)
+class PresetRule:
+    """保存生成的持续、rising_edge或迟滞声明，尚未绑定来源时钟或执行状态。
+
+    condition是由合法简单别名/原生有限常量生成的受限DSL；正常计划编译仍检查类型和依赖。
+    selection_origin仅持续规则为onset，point没有持续选择；实例不产生事件。
+    """
+
+    id: str  # 生成节点ID。
+    rule_type: str  # condition_duration、rising_edge或hysteresis。
+    condition: str | None  # 公共DSL；迟滞改用两个明确条件。
+    minimum_duration_ns: int | None = None  # condition_duration门槛，单位ns。
+    selection_origin: str | None = None  # condition_duration为onset。
+    emit_initial: bool = False  # rising_edge首次初始化政策。
+    enter_condition: str | None = None  # 迟滞进入条件，普通规则不使用。
+    exit_condition: str | None = None  # 迟滞退出条件。
+    enter_delay_ns: int = 0  # 进入确认等待，纳秒。
+    exit_delay_ns: int = 0  # 退出确认等待，纳秒。
+
+
+@dataclass(frozen=True)
+class PresetCalculation:
+    """保存按原活动范围计算的积分或时长声明及独立覆盖/部分结果政策。
+
+    积分signal是公共信号或派生别名，unit为Wh/Ah；condition_duration用明确BOOL条件和秒。
+    partial_policy=None表示继承execution，不是默认强制strict；覆盖质量由既有CalculationDefinition判断。
+    """
+
+    id: str  # 生成指标ID。
+    scope: str  # event:生成活动ID。
+    signal: str | None  # 简单别名；condition-only duration不提供。
+    unit: str  # 明确积分输出单位。
+    minimum_coverage: int | float = 0  # 0—1，只影响覆盖质量判断。
+    partial_policy: str | None = None  # 未提供则由完整计划执行选项继承。
+    operation: str = 'integral'  # integral或按实际事件区间计算duration。
+    condition: str | None = None  # duration可用恒真条件计整个已知活动区间。
+
+
+@dataclass(frozen=True)
+class PlanFragment:
+    """保存预设生成的公共节点，不含来源、执行器或真实样本。
+
+    derived/rules/windows/calculations/sequences为类型化不可变tuple；序列化只是声明副本。
+    ID不隐式改变，合入完整计划时继续检查用户节点及其他预设冲突。
+    """
+
+    derived: tuple[DerivedDefinition, ...] = ()
+    rules: tuple[PresetRule, ...] = ()
+    windows: tuple[WindowSpec, ...] = ()
+    calculations: tuple[PresetCalculation, ...] = ()
+    sequences: tuple[SequencePlan, ...] = ()  # 可选点事件配对声明；空值不输出sequences键。
+
+    def to_dict(self):
+        """将类型化片段序列化为当前配置节点副本；没有配对时省略空sequences键。
+
+        参数: 无；读取生成的不可变声明。
+        返回: dict，可合入AnalysisPlan.from_dict；不含伪造来源或执行结果。
+        异常: 无主动异常；实例由build_preset构造。
+        """
+        # 派生元数据不伪造领域意义，公共名称与表达式保持。
+        derived = {item.name: {'expr': item.expr, 'unit': item.unit} for item in self.derived}
+        rules, windows, calculations = [], [], []
+        for item in self.rules:
+            row = {'name': item.id, 'rule_type': item.rule_type}
+            if item.rule_type == 'hysteresis':
+                row.update(enter_condition=item.enter_condition, exit_condition=item.exit_condition,
+                    enter_delay=f'{item.enter_delay_ns}ns', exit_delay=f'{item.exit_delay_ns}ns')
+                rules.append(row)
+                continue
+            row['condition'] = item.condition
+            if item.rule_type == 'condition_duration':
+                row.update(minimum_duration=f'{item.minimum_duration_ns}ns', selection_origin=item.selection_origin)
+            else:
+                row['emit_initial'] = item.emit_initial
+            rules.append(row)
+        for item in self.windows:
+            windows.append({'name': item.window_id, 'rule': item.event_rule_id, 'anchor': item.anchor,
+                            'pre': f'{item.pre_ns}ns', 'post': f'{item.post_ns}ns', 'merge': item.merge})
+        for item in self.calculations:
+            row = {'name': item.id, 'scope': item.scope, 'operation': item.operation, 'unit': item.unit,
+                   'minimum_coverage': item.minimum_coverage}
+            if item.signal is not None:
+                row['expr'] = item.signal
+            if item.condition is not None:
+                row['condition'] = item.condition
+            if item.operation == 'integral':
+                row['method'] = 'zoh'
+            if item.partial_policy is not None:
+                row['partial_policy'] = item.partial_policy
+            calculations.append(row)
+        result = {'derived': derived, 'rules': rules, 'windows': windows, 'calculations': calculations}
+        if self.sequences:
+            result['sequences'] = [dict(name=item.sequence_id, start=item.start_rule, response=item.response_rule,
+                min_delay=f'{item.min_delay_ns}ns', max_delay=f'{item.max_delay_ns}ns', max_pending=item.max_pending)
+                for item in self.sequences]
+        from .config_groups import public_configuration
+        return public_configuration(result)

chronaxis/planning/record_execution.py

@@ -0,0 +1,76 @@
+"""声明新记录流当前可执行范围；静态报告与实际会话共用同一检查。
+
+这里只检查有限配置，不读取来源，不把尚未接线的能力报为已支持。
+"""
+
+
+def is_event_duration(request):
+    """识别事件总时长的静态声明，不导入执行层。参数: 指标请求。返回: bool。异常: 无。"""
+    return (request.scope.startswith('event:') and request.operation=='duration' and request.signal is None
+            and request.condition is not None and request.condition.root.operator=='const'
+            and request.condition.root.value is True)
+
+
+def record_execution_errors(plan):
+    """检查会话时间指标的已接线路径。
+
+    参数: 已编译计划。返回: 错误tuple，空值表示当前组合可执行。
+    异常: 非法typed对象属性错误传播；不访问文件或修改计划。
+    """
+    errors = []
+    # typed计划也不能让无DBC来源携带未确定的有效期；不靠读取数据猜周期。
+    sources = {source.name: source for source in plan.sources}
+    for signal in plan.signals:
+        definition = signal.definition
+        source = sources.get(definition.source)
+        if definition.valid_for_ns is None and (source is None or
+                source.source_type not in ('can_blf', 'can_asc', 'asc_or_blf', 'raw_can_csv')):
+            errors.append(definition.name + '没有DBC周期依据；请填写本信号period或valid_for')
+    if not (plan.calculations or plan.message_calculations or plan.rules or plan.outputs.can_frames or plan.outputs.signal_csv) or any((item.scope != 'session' and not item.scope.startswith(('event:','segment:'))) or item.operation not in
+            ('integral', 'duration', 'min_time', 'max_time', 'time_weighted_mean','sample_minimum','sample_maximum','sample_mean','select') for item in plan.calculations):
+        errors.append('当前配置当前接入会话积分及时间统计')
+    choices = dict(plan.intervals.resolved)
+    if any(item.calculation_id not in choices for item in plan.calculations if item.operation not in ('sample_minimum','sample_maximum','sample_mean','select')):
+        errors.append('当前配置指标缺少已解析间隔选择')
+    names, value_names = set(), set()
+    for request in plan.rules:
+        names.update(request.dependencies)
+        value_names.update(request.dependencies)
+        choice=choices.get(request.rule_id)
+        if choice is None and request.rule_type not in ('rising_edge','falling_edge'):
+            errors.append('当前配置规则缺少已解析间隔选择')
+        elif choice is not None and choice.driver is not None:
+            names.add(choice.driver)
+    for calculation in plan.calculations:
+        for expression in (calculation.signal, calculation.condition):
+            if expression is not None:
+                names.update(expression.dependencies)
+                value_names.update(expression.dependencies)
+        choice = choices.get(calculation.calculation_id)
+        if choice is not None and choice.driver is not None:
+            names.add(choice.driver)
+    for request in plan.sequences:
+        choice=choices.get(request.sequence_id)
+        if choice is None:
+            errors.append('当前配置配对缺少已解析间隔选择')
+        elif choice.driver is not None:
+            names.add(choice.driver)
+    for window in plan.windows:
+        choice=choices.get(window.window_id)
+        if choice is not None and choice.driver is not None:
+            names.add(choice.driver)
+    if plan.outputs.signal_csv is not None:
+        names.update(plan.outputs.signal_csv.spec.signals)
+    needed = {item.definition.source for item in plan.signals if item.definition.name in names}
+    needed.update(item.source for item in plan.message_calculations)
+    if plan.outputs.can_frames is not None:
+        needed.add(plan.outputs.can_frames.source)
+    if any(not rule.dependencies and (choices.get(rule.rule_id) is None or
+           choices[rule.rule_id].driver is None) for rule in plan.rules) or any(
+            calculation.scope=='session' and (choices.get(calculation.calculation_id) is None or choices[calculation.calculation_id].driver is None)
+            and not any(e.dependencies for e in (calculation.signal,calculation.condition) if e is not None) for calculation in plan.calculations):
+        needed.update(source.name for source in plan.sources)
+    if not needed or any(item.source_type not in ('can_blf', 'can_asc', 'asc_or_blf', 'raw_can_csv', 'memory', 'signal_csv')
+                              for item in plan.sources if item.name in needed):
+        errors.append('当前配置需要已声明且支持的观测来源')
+    return tuple(errors)