chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/api/BatchJobResult.md

@@ -0,0 +1,61 @@
+# BatchJobResult
+
+推荐导入：`from chronaxis import BatchJobResult`
+
+<a id="api-BatchJobResult"></a>
+## `BatchJobResult`
+
+保存一个任务的最终状态；发布后关闭失败仍为failed，并保留已发布路径。
+
+```python
+BatchJobResult(job_id: str, status: str, plan_path: str | None = None, plan_identity: str | None = None, dataset_id: str | None = None, entity_id: str | None = None, session_id: str | None = None, input_identity: str | None = None, run_id: str | None = None, output_dir: pathlib.Path | None = None, error_type: str | None = None, error_message: str | None = None, error_chain: tuple[str, ...] = (), elapsed_seconds: float = 0.0, memory_budget_bytes: int | None = None, worker_pid: int | None = None, recovery: chronaxis.batch.models.CleanupHandle | None = None) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`job_id`|str|是|无|原任务身份。|
+|`status`|str|是|无|`completed`：分析、结果发布和资源关闭均成功；`failed`：任一步骤失败，查看error_type/error_message等诊断；`cancelled`：取消或fail_fast使该任务没有继续执行。失败与取消不是同一状态。|
+|`plan_path`|str &#124; None|否|None|原任务使用文件路径时保存其绝对路径；直接传AnalysisPlan的正常任务为None。|
+|`plan_identity`|str &#124; None|否|None|已取得计划的声明身份；文件计划未加载或加载失败时为None，不能当作输入文件内容摘要。|
+|`dataset_id`|str &#124; None|否|None|已取得计划的dataset.name；未加载或加载失败时为None。结果属性仍名为dataset_id。|
+|`entity_id`|str &#124; None|否|None|已取得计划的对象标识：取可选dataset.entity，省略则沿用dataset.name；未加载或加载失败时为None。|
+|`session_id`|str &#124; None|否|None|已取得计划的会话标识：取可选dataset.session，省略则沿用dataset.name；未加载或加载失败时为None。|
+|`input_identity`|str &#124; None|否|None|AnalysisRunner返回的输入摘要身份；没有返回结果或未请求该摘要时为None，正常运行也可能为None。|
+|`run_id`|str &#124; None|否|None|AnalysisRunner已返回结果时记录运行ID；尚未返回结果就失败或取消时为None。|
+|`output_dir`|Path &#124; None|否|None|发布成功后记录的正式目录；尚未发布成功为None。发布后关闭失败仍保留该路径，任务状态为failed。|
+|`error_type`|str &#124; None|否|None|失败异常类名或未启动取消标识not_started；正常完成时为None。结合status和error_chain查看。|
+|`error_message`|str &#124; None|否|None|失败或取消的具体说明；正常完成时为None。异常cause与清理说明保存在error_chain。|
+|`error_chain`|tuple[str, ...]|否|()|cause链和清理notes，保留错误来源。|
+|`elapsed_seconds`|float|否|0.0|单任务墙钟秒，含发布及关闭，不宣称CPU耗时。|
+|`memory_budget_bytes`|int &#124; None|否|None|已取得计划的新分析层预算，单位字节；文件计划尚未加载/加载失败时为None，不表示0字节。|
+|`worker_pid`|int &#124; None|否|None|实际执行此任务的分析工作进程PID；未启动的任务为None。复用同一进程的任务可具有相同PID。|
+|`recovery`|CleanupHandle &#124; None|否|None|关闭失败后保留的CleanupHandle；调用close()重试释放资源，正常关闭时为None；不写入JSON。|
+
+
+<a id="api-BatchJobResult-to_dict"></a>
+### `BatchJobResult.to_dict`
+
+把本任务的状态、结果目录和错误信息转换为可写入报告的字典。
+
+```python
+BatchJobResult.to_dict() -> dict
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+JSON对象。
+
+#### 异常说明
+
+无；不序列化资源对象。
+
+返回类型：dict。

chronaxis/guide/api/BatchPlan.md

@@ -0,0 +1,48 @@
+# BatchPlan
+
+推荐导入：`from chronaxis import BatchPlan`
+
+<a id="api-BatchPlan"></a>
+## `BatchPlan`
+
+保存批量配置；只关联独立计划路径，不能把一个会话拆成多个时间任务。
+
+```python
+BatchPlan(jobs: tuple[chronaxis.batch.models.BatchJob, ...], process_count: int = 1, fail_fast: bool = False, backend: str | None = None) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`jobs`|tuple[BatchJob, ...]|是|无|提供BatchJob元组，例如(BatchJob("a", Path("a.yaml")),)；也可通过load_batch_plan读取YAML取得。元组顺序就是最终报告顺序。|
+|`process_count`|int|否|1|控制最多启动几个分析工作进程。填正整数，例如4；默认1。任务少于该值时按任务数启动，空批次不启动。此数量不包含调度主进程和CAN读取子进程。|
+|`fail_fast`|bool|否|False|控制某任务失败后的调度：False继续其他独立任务；True停止提交新任务，已运行任务按批量执行器的取消流程收尾。|
+|`backend`|str &#124; None|否|None|`"reference"`使用独立参考计算，`"numpy"`使用NumPy数组计算。None沿用计划的设置。|
+
+
+<a id="api-BatchPlan-from_dict"></a>
+### `BatchPlan.from_dict`
+
+检查批量配置；jobs只关联路径，template读取模板并展开文件集合。
+
+```python
+BatchPlan.from_dict(config, *, base_dir=None)
+```
+
+装饰器：`classmethod`。
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`config`|dict[str, object]|是|无|位置或关键字。批量配置：batch_version=1；jobs与template+inputs二选一。jobs每项plan必填，name省略按位置生成job_N；template有多来源时用source明确目标。可选process_count、fail_fast、backend。见独立批量任务。|
+|`base_dir`|str &#124; pathlib.Path &#124; None|否|None|仅关键字。解析计划中相对路径所用的目录；None表示使用当前工作目录。|
+
+#### 返回说明
+
+冻结BatchPlan。
+
+#### 异常说明
+
+PlanValidationError定位非法字段、重名、缺少模板输入或来源歧义。jobs可为空；jobs只保留计划路径，template会读取模板、展开文件集合并按需读取DBC元数据，不扫描业务报文。

chronaxis/guide/api/BatchReport.md

@@ -0,0 +1,108 @@
+# BatchReport
+
+推荐导入：`from chronaxis import BatchReport`
+
+<a id="api-BatchReport"></a>
+## `BatchReport`
+
+按原任务顺序汇总结果；每个任务数值表仍在各自目录，不跨口径归约。
+
+```python
+BatchReport(output_dir: pathlib.Path, jobs: tuple[chronaxis.batch.models.BatchJobResult, ...], process_count: int, fail_fast: bool, cancel_requested: bool, device_label: str, worker_process_count: int = 0, infrastructure_error: str | None = None) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`output_dir`|Path|是|无|本批新目录，已有目标不会被覆盖。|
+|`jobs`|tuple[BatchJobResult, ...]|是|无|最终结果顺序不受工作进程完成先后影响。|
+|`process_count`|int|是|无|控制最多启动几个分析工作进程。填正整数，例如4；默认1。任务少于该值时按任务数启动，空批次不启动。此数量不包含调度主进程和CAN读取子进程。|
+|`fail_fast`|bool|是|无|是否在观察到失败后停止派发。|
+|`cancel_requested`|bool|是|无|用户取消或KeyboardInterrupt是否曾被观察到。|
+|`device_label`|str|是|无|标记本次批量报告的来源设备。直接构造BatchReport时必填非空文本；run_batch或BatchRunner.run的device_label参数省略时才采用pending。不会覆盖子分析metadata.device_label。|
+|`worker_process_count`|int|否|0|本次实际启动的分析工作进程数量；可能少于process_count，空批次或开始前取消时为0。不包含CAN读取子进程。|
+|`infrastructure_error`|str &#124; None|否|None|调度/汇总基础设施异常的说明；None表示未记录这类错误，不代表每个任务成功。任务错误查看jobs中的status、error_type、error_message及error_chain。|
+
+
+<a id="api-BatchReport-status"></a>
+### `BatchReport.status`
+
+汇总失败优先状态。
+
+```python
+BatchReport.status: str
+```
+
+装饰器：`property`。
+
+读取属性，不使用调用括号。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+failed/cancelled/completed。
+
+#### 异常说明
+
+无。
+
+返回类型：str。
+
+
+<a id="api-BatchReport-to_dict"></a>
+### `BatchReport.to_dict`
+
+输出身份和计数。
+
+```python
+BatchReport.to_dict() -> dict
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+JSON对象。
+
+#### 异常说明
+
+无。不合并指标值。
+
+返回类型：dict。
+
+
+<a id="api-BatchReport-close"></a>
+### `BatchReport.close`
+
+重试所有未完清理。
+
+```python
+BatchReport.close() -> None
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+返回None，不返回额外的计算值。
+
+#### 异常说明
+
+首个关闭错误，其他项仍尝试。
+
+返回类型：None。

chronaxis/guide/api/BatchRunner.md

@@ -0,0 +1,84 @@
+# BatchRunner
+
+推荐导入：`from chronaxis import BatchRunner`
+
+<a id="api-BatchRunner"></a>
+## `BatchRunner`
+
+通过有限spawn工作进程执行独立任务；同一任务的连续文件保持原顺序。
+
+```python
+BatchRunner(process_count=1, *, fail_fast=False, backend=None)
+```
+
+
+
+<a id="api-BatchRunner-__init__"></a>
+### `BatchRunner.__init__`
+
+配置调度。
+
+```python
+BatchRunner.__init__(process_count=1, *, fail_fast=False, backend=None)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`process_count`|int|否|1|位置或关键字。控制最多启动几个分析工作进程。填正整数，例如4；默认1。任务少于该值时按任务数启动，空批次不启动。此数量不包含调度主进程和CAN读取子进程。|
+|`fail_fast`|bool|否|False|仅关键字。False时某任务失败仍继续尝试后续任务；True时发现失败后停止启动新任务，但等待已启动任务收尾。|
+|`backend`|str &#124; None|否|None|仅关键字。`"reference"`使用独立参考计算；`"numpy"`使用NumPy数组计算。None沿用计划中的选择。|
+
+#### 返回说明
+
+None。初始化调度选项；调用BatchRunner(...)才创建并取得实例。此时不启动工作进程或读取输入。
+
+#### 异常说明
+
+类型、范围或计算后端无效。构造时不读取业务数据，也不启动工作进程。
+
+本函数直接报告的具体错误：
+
+- `ValueError`：process_count需要正原生int。
+- `TypeError`：fail_fast需要bool。
+
+
+<a id="api-BatchRunner-run"></a>
+### `BatchRunner.run`
+
+运行独立任务，原声明顺序返回报告。
+
+```python
+BatchRunner.run(jobs, output_dir, *, cancel_event=None, device_label='pending') -> BatchReport
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`jobs`|tuple|是|无|位置或关键字。提供BatchJob元组，例如load_batch_plan("batch.yaml").jobs；每项含独立分析的ID与计划，顺序决定报告排列。|
+|`output_dir`|str &#124; Path|是|无|位置或关键字。新批量结果目录，每个任务按id创建子目录；目标已经存在时拒绝覆盖。|
+|`cancel_event`|threading.Event &#124; None|否|None|仅关键字。可选取消标记；None表示没有。其他线程调用set()后停止派发新任务，正在执行的任务继续收尾。|
+|`device_label`|str|否|'pending'|仅关键字。产出记录的设备标签，例如已核实的"home"或"work"；未确定时用"pending"。这是来源说明，不参与数值计算，也不根据文件路径猜测。|
+
+#### 返回说明
+
+BatchReport，close可重试子进程内失败清理。
+
+#### 异常说明
+
+声明/路径错误在创建工作进程前拒绝；工作进程调度器等基础设施错误收尾后传播。
+
+本函数直接报告的具体错误：
+
+- `TypeError`：批量任务需要BatchJob tuple。
+- `ValueError`：批量job_id不能重复，大小写冲突也拒绝。
+- `TypeError`：cancel_event需要threading.Event。
+- `ValueError`：device_label需要非空文本。
+
+#### 副作用说明
+
+启动最多process_count个工作进程，每任务独立发布；取消只阻止未派发任务。
+
+返回类型：BatchReport。

chronaxis/guide/api/OutputManifest.md

@@ -0,0 +1,23 @@
+# OutputManifest
+
+推荐导入：`from chronaxis import OutputManifest`
+
+<a id="api-OutputManifest"></a>
+## `OutputManifest`
+
+保存成功发布目录、清单和固定白名单表行数；legacy只在启用时出现。
+
+```python
+OutputManifest(run_id: str, output_dir: pathlib.Path, manifest_path: pathlib.Path, output_files: tuple[pathlib.Path, ...], row_counts: tuple[tuple[str, int], ...], status: str = 'completed') -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`run_id`|str|是|无|本次运行唯一标识，与发布清单及资源事实关联。|
+|`output_dir`|Path|是|无|已经成功发布的结果目录绝对Path。|
+|`manifest_path`|Path|是|无|已发布run_manifest.json的绝对Path。|
+|`output_files`|tuple[Path, ...]|是|无|本次实际发布的文件路径元组。|
+|`row_counts`|tuple[tuple[str, int], ...]|是|无|各固定结果表的实际行数记录。|
+|`status`|str|否|'completed'|本次发布结果状态，成功为completed。|

chronaxis/guide/api/PlanFragment.md

@@ -0,0 +1,47 @@
+# PlanFragment
+
+推荐导入：`from chronaxis import PlanFragment`
+
+<a id="api-PlanFragment"></a>
+## `PlanFragment`
+
+预设生成的一组派生量、规则、窗口、指标及配对配置，合并进完整分析计划后执行。它不包含真实样本，也不会自行读取文件；生成的节点ID仍需与用户配置中的ID保持唯一。
+
+```python
+PlanFragment(derived: tuple[chronaxis.core.expression.DerivedDefinition, ...] = (), rules: tuple[chronaxis.planning.preset_models.PresetRule, ...] = (), windows: tuple[chronaxis.core.windows.WindowSpec, ...] = (), calculations: tuple[chronaxis.planning.preset_models.PresetCalculation, ...] = (), sequences: tuple[chronaxis.planning.sequences.SequencePlan, ...] = ()) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`derived`|tuple[DerivedDefinition, ...]|否|()|预设生成的派生量配置；空元组表示没有新增派生量。|
+|`rules`|tuple[PresetRule, ...]|否|()|预设生成的检测规则；空元组表示没有新增规则。|
+|`windows`|tuple[WindowSpec, ...]|否|()|预设生成的事件窗口配置；空元组表示没有新增窗口。|
+|`calculations`|tuple[PresetCalculation, ...]|否|()|预设生成的指标配置；空元组表示没有新增指标。|
+|`sequences`|tuple[SequencePlan, ...]|否|()|读取预设生成的SequencePlan元组；没有配对任务时为空。to_dict()将非空项转换为可合入完整配置的sequences列表。|
+
+
+<a id="api-PlanFragment-to_dict"></a>
+### `PlanFragment.to_dict`
+
+将类型化片段序列化为当前配置节点副本；没有配对时省略空sequences键。
+
+```python
+PlanFragment.to_dict()
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无；读取生成的不可变声明。
+
+#### 返回说明
+
+dict，可合入AnalysisPlan.from_dict；不含伪造来源或执行结果。
+
+#### 异常说明
+
+无主动异常；实例由build_preset构造。

chronaxis/guide/api/PlanValidationError.md

@@ -0,0 +1,98 @@
+# PlanValidationError
+
+推荐导入：`from chronaxis import PlanValidationError`
+
+<a id="api-PlanValidationError"></a>
+## `PlanValidationError`
+
+保存配置字段路径、原因、机器错误码及可选的原文定位和修正建议。
+
+不吞执行异常或数据读取失败；code区分无效配置与尚未接入可运行流程能力。
+
+```python
+PlanValidationError(path: str, message: str, code: str = 'invalid_config', *, hint=None, source=None, location=None, object_name=None, value=None)
+```
+
+继承关系：ValueError。下表列本类声明的字段；基类字段及其约束见对应类型链接。
+
+
+
+<a id="api-PlanValidationError-__init__"></a>
+### `PlanValidationError.__init__`
+
+建立明确路径错误，保留原异常链供load_analysis_plan诊断。
+
+```python
+PlanValidationError.__init__(path: str, message: str, code: str='invalid_config', *, hint=None, source=None, location=None, object_name=None, value=None)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`path`|str|是|无|位置或关键字。标识配置中的出错字段，例如$.signals[0].unit；由校验器根据实际声明位置生成。|
+|`message`|str|是|无|位置或关键字。解释该字段违反的要求，例如需要正整数；用于面向用户的错误正文，不应包含完整私有输入数据。|
+|`code`|str|否|'invalid_config'|位置或关键字。提供机器可识别的错误类别，默认invalid_config表示无效配置；读取异常时用code分类，不依赖中文message匹配。|
+|`hint`|str 或 None|否|None|仅关键字。可选修正提示，例如有效枚举值或可用名称；提示不会自动修改原配置。|
+|`source`|str 或 None|否|None|仅关键字。配置来源文件或显示名，与字段path分开；没有可靠来源时保留None。|
+|`location`|ConfigurationLocation 或 None|否|None|仅关键字。可证明的原始行列；缺失时只给文件与字段，不猜位置。|
+|`object_name`|str 或 None|否|None|仅关键字。错误所属的来源、信号或节点名称；只用于定位，不参与名称推断。|
+|`value`|str 或 None|否|None|仅关键字。已截短的当前值说明，大容器仅显示类型与大小，避免打印整份配置。|
+
+#### 返回说明
+
+None；异常文本含路径和原因。
+
+#### 异常说明
+
+无；参数由校验器内部构造。
+
+
+<a id="api-PlanValidationError-refresh_text"></a>
+### `PlanValidationError.refresh_text`
+
+重建人读消息。
+
+```python
+PlanValidationError.refresh_text()
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+None。
+
+#### 异常说明
+
+无；附加定位后调用。
+
+
+<a id="api-PlanValidationError-to_dict"></a>
+### `PlanValidationError.to_dict`
+
+返回稳定机器诊断。
+
+```python
+PlanValidationError.to_dict()
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+原生dict。
+
+#### 异常说明
+
+无。

chronaxis/guide/api/PresetSpec.md

@@ -0,0 +1,63 @@
+# PresetSpec
+
+推荐导入：`from chronaxis import PresetSpec`
+
+<a id="api-PresetSpec"></a>
+## `PresetSpec`
+
+冻结预设ID、preset_type/version、角色别名及工程参数的独立JSON快照。
+
+id只用简单标识；role_bindings值只引用当前计划简单别名，不能写领域属性路径。
+parameters不保留调用者可变对象，实际preset_type参数在build_preset中统一校验。
+
+```python
+PresetSpec(id: str, preset_type: str, version: str, role_bindings: collections.abc.Mapping, parameters: collections.abc.Mapping) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`id`|str|是|无|设置本预设实例唯一名称，例如hot；生成规则和计算使用此前缀，须避免与已有节点重名。|
+|`preset_type`|str|是|无|选择任务：charge_session分析充电，fault_context提取故障前后文，command_response配对请求响应，threshold_excursion累计阈值报警。各类型的角色和参数见预设指南。|
+|`version`|str|是|无|选择预设模板版本，当前填写字符串"1"；不是整数1，也不是顶层config_version。|
+|`role_bindings`|Mapping|是|无|将业务角色关联到signals中已定义的分析名，例如{"signal": "temperature"}。允许角色由preset_type决定；省略角色时须符合语义声明自动查找要求。|
+|`parameters`|Mapping|是|无|提供所选预设的业务参数字典，例如阈值预设的unit、enter_threshold、exit_threshold。值来自业务阈值和设备单位；各类型字段不能互相套用，完整选项见预设指南。|
+
+
+<a id="api-PresetSpec-from_dict"></a>
+### `PresetSpec.from_dict`
+
+从当前配置的预设对象构造公开不可变声明。
+
+```python
+PresetSpec.from_dict(value)
+```
+
+装饰器：`classmethod`。
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`value`|dict[str, object]|是|无|位置或关键字。预设配置字典：name、preset_type和parameters必填；version省略为字符串1，role_bindings省略为空映射。角色映射与业务约束见业务预设。|
+
+#### 返回说明
+
+PresetSpec，role_bindings缺省为空。
+
+#### 异常说明
+
+PlanValidationError为未知键、缺项或构造协议错误。
+
+# 构造预设声明；绑定和阈值的完整语义在组装计划时继续检查。
+spec = PresetSpec.from_dict({
+    "name": "heat_alarm",
+    "preset_type": "threshold_excursion",
+    "version": "1",
+    "role_bindings": {"signal": "temperature"},
+    "parameters": {"unit": "degC", "enter_threshold": 80, "exit_threshold": 75},
+})
+print(spec.id, spec.preset_type)
+
+```

chronaxis/guide/api/ResultClosedError.md

@@ -0,0 +1,14 @@
+# ResultClosedError
+
+推荐导入：`from chronaxis import ResultClosedError`
+
+<a id="api-ResultClosedError"></a>
+## `ResultClosedError`
+
+表示结果已经关闭，不能再创建迭代器、读取或发布。
+
+```python
+class ResultClosedError(AnalysisError)
+```
+
+继承关系：AnalysisError。下表列本类声明的字段；基类字段及其约束见对应类型链接。

chronaxis/guide/api/RunMetadata.md

@@ -0,0 +1,100 @@
+# RunMetadata
+
+推荐导入：`from chronaxis import RunMetadata`
+
+<a id="api-RunMetadata"></a>
+## `RunMetadata`
+
+保存一次运行的身份、实际计算后端、时间解释及诊断摘要。通常从仍打开的AnalysisResult.metadata读取，不需要自行构造。来源明细字段是可选模型：只有调用方提供真实读取明细时才有内容。当前AnalysisRunner没有填充can_sources和text_can_sources，两者保持空元组；这不表示没有读取CAN文件，也不表示DBC已经校验。to_dict的摘要与详细模式见下方方法说明。
+
+```python
+RunMetadata(run_id: str, input_identity: str | None, plan_hash: str, backend: str, config_version: int, source_time_interpretation: str, session_boundaries: tuple[tuple[str, int, int], ...], started_at: str, mapping_hashes: tuple[str, ...] = (), dbc_hashes: tuple[str, ...] = (), parsing_policy: str = 'decoded-results', worker_config: str = 'single-thread', dependency_versions: tuple[tuple[str, str], ...] = (), limitations: tuple[str, ...] = (), software_version: str = '0.1.0.dev0', device_label: str = 'pending', signal_bindings: tuple[chronaxis.core.binding.SignalDefinition, ...] = (), preset_bindings: tuple[chronaxis.results.binding_metadata.PresetBindingMetadata, ...] = (), can_sources: tuple[chronaxis.results.can_metadata.CANSourceMetadata, ...] = (), session_ids: tuple[str, ...] = (), text_can_sources: tuple[chronaxis.results.text_can_metadata.TextCANSourceMetadata, ...] = (), threshold_durations: tuple[chronaxis.results.threshold_metadata.SummaryThresholdDuration, ...] = (), detailed_diagnostics: bool = False, retain_work: bool = False, input_diagnostics: tuple[chronaxis.results.input_diagnostics.InputDiagnostic, ...] = (), trace_requested: bool = False, integrity_diagnostics: bool = False, frame_format_notices: tuple[tuple[str, chronaxis.results.can_metadata.CANFrameFormatNotice], ...] = (), analysis_outcome: chronaxis.results.analysis_outcome.AnalysisOutcome | None = None) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`run_id`|str|是|无|本次运行唯一标识，与发布清单及资源事实关联。|
+|`input_identity`|str &#124; None|是|无|读取实际输入的追溯摘要；None表示本运行没有提供该摘要，不能据此判断输入内容已核验。|
+|`plan_hash`|str|是|无|计划声明的SHA-256身份，实际后端覆盖另行记录。|
+|`backend`|str|是|无|读取本次实际采用的计算后端：reference为参考实现，numpy为数组实现。由Runner的有效运行设置记录，用户通常不手工构造这个结果字段。|
+|`config_version`|int|是|无|本次实际分析配置的结构版本，必须是原生整数3；不是预设version，也不是软件版本。版本1及布尔值均被拒绝。|
+|`source_time_interpretation`|str|是|无|来源时间解释文本，说明坐标、单位及转换约定。|
+|`session_boundaries`|tuple[tuple[str, int, int], ...]|是|无|记录实际会话边界，每项为(session_id,start_ns,end_ns)，时间为整数纳秒、范围左闭右开。由执行器取得，空元组表示未建立这些边界，不能当作已观测零时长。|
+|`started_at`|str|是|无|记录本次运行开始时间，由执行器生成带时区的ISO8601文本，例如2026-10-27T19:00:00+08:00；不是数据中第一条采样时间。|
+|`mapping_hashes`|tuple[str, ...]|否|()|实际映射身份摘要元组；不涉及时为空，空值不等于已验。|
+|`dbc_hashes`|tuple[str, ...]|否|()|实际DBC摘要元组；不涉及时为空。|
+|`parsing_policy`|str|否|'decoded-results'|本次采用的解析/接入政策名称。|
+|`worker_config`|str|否|'single-thread'|本次执行worker配置说明，不将单线程标签当性能保证。|
+|`dependency_versions`|tuple[tuple[str, str], ...]|否|()|实际记录的依赖(name,version)元组。|
+|`limitations`|tuple[str, ...]|否|()|本次已知限制文本元组，发布时保持可见。|
+|`software_version`|str|否|'0.1.0.dev0'|软件版本文本，与设计版本和配置版本分开。|
+|`device_label`|str|否|'pending'|实际内容来源设备标签；不能根据文件所在路径猜home/work。|
+|`signal_bindings`|tuple[SignalDefinition, ...]|否|()|本次实际完整定义，不含样本或输入行。|
+|`preset_bindings`|tuple[PresetBindingMetadata, ...]|否|()|原预设版本及最终角色。|
+|`can_sources`|tuple[CANSourceMetadata, ...]|否|()|保存CANSourceMetadata对象元组，每项描述sclicer-functions-v1单BLF读取的来源名、原文件与DBC路径、通道、帧数、首末时间和单位检查等。由构造RunMetadata的调用方显式传入，当前公开AnalysisRunner不填充，默认()表示未提供此类明细，不表示没有CAN输入。确有元素时可用metadata.can_sources[0].source和.frame_count读取；先检查元组非空。|
+|`session_ids`|tuple[str, ...]|否|()|无时间请求仍明确会话身份，绝不伪造边界。|
+|`text_can_sources`|tuple[TextCANSourceMetadata, ...]|否|()|保存TextCANSourceMetadata对象元组，每项描述can-text-v1读取的来源、inputs中的(path, parser, offset_ns)、DBC摘要、记录数和观测时间。由调用方显式提供，当前公开AnalysisRunner不填充；默认()表示未提供此类明细。确有元素时可用metadata.text_can_sources[0].inputs和.record_count读取；不能把空元组理解为输入为空。|
+|`threshold_durations`|tuple[SummaryThresholdDuration, ...]|否|()|读取阈值预设的累计时长摘要元组；每项SummaryThresholdDuration包含preset_id、rule_id、value、unit和status。partial的value是已知部分秒数，不能当作完整总时长；无此预设时为空元组。|
+|`detailed_diagnostics`|bool|否|False|记录是否在清单中序列化额外详细诊断。True包含相应明细，False使用摘要；这是结果模型字段，公开Runner返回的设置不能靠修改此字段补做分析。|
+|`retain_work`|bool|否|False|显式现场留存请求，不默认保留工作文件。|
+|`input_diagnostics`|tuple[InputDiagnostic, ...]|否|()|仅按请求记录同次所需输入范围。|
+|`trace_requested`|bool|否|False|记录本次是否请求输入逐条追溯：True对应diagnostics.trace开启，False不请求；实际记录通过结果追溯迭代器读取。|
+|`integrity_diagnostics`|bool|否|False|记录本次是否请求输入完整性摘要：True对应diagnostics.integrity开启，False不请求；它与逐条追溯开关独立。|
+|`frame_format_notices`|tupletuple[str, [CANFrameFormatNotice], ...]|否|()|同次已核差异始终提示，独立于可选诊断。|
+|`analysis_outcome`|AnalysisOutcome &#124; None|否|None|同次执行累计的AnalysisOutcome或None：逐规则说明有事件、条件未成立、未达到时长、无观测或数据不足，并分别统计complete/partial/indeterminate指标行。None表示该路径未提供概况，不能当作无事件；completed只说明执行结束。无二次输入扫描或逐条追溯。|
+
+
+<a id="api-RunMetadata-estimated_bytes"></a>
+### `RunMetadata.estimated_bytes`
+
+在asdict/JSON复制前估算元数据与其临时对象开销。
+
+```python
+RunMetadata.estimated_bytes() -> int
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+保守bytes估算。
+
+#### 异常说明
+
+无，类型已经校验。
+
+返回类型：int。
+
+
+<a id="api-RunMetadata-to_dict"></a>
+### `RunMetadata.to_dict`
+
+返回独立JSON兼容元数据，调用侧必须先预留estimated_bytes。
+
+```python
+RunMetadata.to_dict() -> dict
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+独立JSON兼容dict。默认detailed_diagnostics=False只输出运行摘要及适用的可选摘要；即使模型的signal_bindings/preset_bindings/can_sources非空，也不输出这些详细键。True时展开详细模型，空的可选明细仍按规则省略。两种模式及键示例见运行清单。
+
+#### 异常说明
+
+无预期异常；调用方须在复制前承担estimated_bytes预算。
+
+返回类型：dict。