chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/api/TimeConversion.md

@@ -0,0 +1,29 @@
+# TimeConversion
+
+推荐导入：`from chronaxis import TimeConversion`
+
+<a id="api-TimeConversion"></a>
+## `TimeConversion`
+
+保存规范时间及来源精度，避免跨任务修改转换诊断。
+
+time_ns经入口校验为int64；quantized表示实际纳秒舍入发生，浮点限制
+与量化分别记录。input_text保留转换所见表示，不证明上游原始精度。
+source_timezone仅记录日期采用的时区，不替代多源同步依据。
+
+```python
+TimeConversion(time_ns: int, input_representation: str, input_unit: str, input_text: str, quantized: bool, precision_limited: bool = False, rounding: str = 'round_half_even', source_timezone: str | None = None) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`time_ns`|int|是|无|核心坐标或时长，单位纳秒，有符号64位范围。|
+|`input_representation`|str|是|无|integer/decimal_text/decimal/binary_float/ISO8601等实际来源。|
+|`input_unit`|str|是|无|明确声明的s/ms/us/ns，日期入口使用ISO8601。|
+|`input_text`|str|是|无|当前入口所见文本；不记录用户日志或假设更高源精度。|
+|`quantized`|bool|是|无|原精确表示不能整纳秒表示时为True，包括舍为0。|
+|`precision_limited`|bool|否|False|标记输入是否为已有二进制float：True表示不能恢复转为float之前的精度；1.0也为True，即使quantized=False。整数/十进制文本/Decimal为False；False不表示多个时钟已同步。|
+|`rounding`|str|否|'round_half_even'|最终纳秒固定采用最近偶数舍入。|
+|`source_timezone`|str &#124; None|否|None|日期实际采用的tzinfo说明，纯数值不猜。|

chronaxis/guide/api/TimeOverflowError.md

@@ -0,0 +1,17 @@
+# TimeOverflowError
+
+推荐导入：`from chronaxis import TimeOverflowError`
+
+<a id="api-TimeOverflowError"></a>
+## `TimeOverflowError`
+
+时间坐标、偏移后坐标或非负跨度超出int64时拒绝运算。
+
+异常不携带可被误用的回绕结果；失败由调用者记录为任务校验错误。
+本类型没有可变状态，不打开资源或把失败当正常零时长。
+
+```python
+class TimeOverflowError(OverflowError)
+```
+
+继承关系：OverflowError。下表列本类声明的字段；基类字段及其约束见对应类型链接。

chronaxis/guide/api/build_preset.md

@@ -0,0 +1,36 @@
+# build_preset
+
+推荐导入：`from chronaxis import build_preset`
+
+<a id="api-build_preset"></a>
+## `build_preset`
+
+校验v1预设并展开公共声明，不执行I/O或数值分析。
+
+```python
+build_preset(spec: PresetSpec, signals: tuple[SignalDefinition, ...]) -> PlanFragment
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`spec`|PresetSpec|是|无|位置或关键字。提供PresetSpec预设声明，可用PresetSpec.from_dict({...})从必填name、preset_type、parameters，以及可选version、role_bindings的Python字典建立；完整可运行调用见预设API示例。|
+|`signals`|tuple[SignalDefinition, ...]|是|无|位置或关键字。提供本计划的SignalDefinition元组，例如tuple(item.definition for item in plan.signals)，其中plan由load_analysis_plan取得；角色引用这些定义的name，不直接填CSV列名。|
+
+### 返回说明
+
+PlanFragment，生成请求的功率/Wh/Ah、报警、阈值迟滞/逐段时长或响应配对。
+
+### 异常说明
+
+PlanValidationError为参数/角色契约、模式编码范围及生成ID与信号冲突。
+
+- PlanValidationError：模式编码超出已声明dtype/valid_range。
+
+### 流程说明
+
+检查角色→生成简单别名DSL→构造类型化节点→拒绝当前可见ID冲突。
+    用户其他节点/多个预设的冲突由AnalysisPlan合入时继续检查。
+
+返回类型：PlanFragment。

chronaxis/guide/api/checked_add_ns.md

@@ -0,0 +1,30 @@
+# checked_add_ns
+
+推荐导入：`from chronaxis import checked_add_ns`
+
+<a id="api-checked_add_ns"></a>
+## `checked_add_ns`
+
+为一个纳秒坐标添加固定偏移，并检查结果是否仍在int64范围内。
+
+```python
+checked_add_ns(time_ns: int, offset_ns: int) -> int
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`time_ns`|int|是|无|位置或关键字。已满足int64范围的原时间坐标，单位为纳秒。|
+|`offset_ns`|int|是|无|位置或关键字。已满足int64范围的固定偏移，单位为纳秒。|
+
+### 返回说明
+
+int: 精确的新坐标；成功相加不表示不同来源已经同步。
+
+### 异常说明
+
+TypeError: 任一输入不是非布尔整数。
+    TimeOverflowError: 任一输入或相加结果超出int64范围。
+
+返回类型：int。

chronaxis/guide/api/convert_time.md

@@ -0,0 +1,40 @@
+# convert_time
+
+推荐导入：`from chronaxis import convert_time`
+
+<a id="api-convert_time"></a>
+## `convert_time`
+
+按明确单位换算纳秒，并在最终结果处取最近偶数舍入。
+
+```python
+convert_time(value: int | float | str | Decimal, unit: str) -> TimeConversion
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`value`|int &#124; float &#124; str &#124; Decimal|是|无|位置或关键字。有限整数、十进制文本、Decimal或已有float，允许负时间坐标。|
+|`unit`|str|是|无|位置或关键字。大小写敏感的s、ms、us或ns；没有默认单位。|
+
+### 返回说明
+
+TimeConversion: 整数纳秒、输入表示与单位，以及是否发生纳秒舍入和
+    是否受已有浮点精度限制的诊断。
+
+### 异常说明
+
+TypeError或ValueError: 输入类型、文本语法、有效数字长度或单位不合法。
+    TimeOverflowError: 舍入后的结果超出int64范围。
+
+### 处理流程说明
+
+分离符号、系数和指数，在整数域缩放或求商余数，再舍入到整纳秒。
+    极大正指数提前拒绝；极大负指数直接判定舍为0，避免无界分配。
+
+### 副作用说明
+
+无，不修改输入、Decimal上下文或时间基准。
+
+返回类型：TimeConversion。

chronaxis/guide/api/explain_analysis_plan.md

@@ -0,0 +1,38 @@
+# explain_analysis_plan
+
+推荐导入：`from chronaxis import explain_analysis_plan`
+
+<a id="api-explain_analysis_plan"></a>
+## `explain_analysis_plan`
+
+列出计划依赖、各节点计算方式、历史需求和预算声明。
+
+```python
+explain_analysis_plan(plan: AnalysisPlan) -> ExplainReport
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|是|无|位置或关键字。提供已校验的AnalysisPlan，通过load_analysis_plan("analysis.yaml")取得，或用AnalysisPlan.from_dict(config)从Python字典建立；这里不接收YAML文件名字符串。|
+
+### 返回说明
+
+ExplainReport。包括同一校验限制、依赖节点、history_ns和budget只读映射。
+    已有数值内核与尚未接入节点分别标记，不能将整份计划当作全数组执行。
+
+### 异常说明
+
+TypeError: 输入不是AnalysisPlan。
+
+### 处理流程说明
+
+展开派生、规则、窗口和指标依赖；事件或片段范围的条件也参与依赖收集。
+    原信号有效期与所需窗口pre取较大时长，只报告需求，不修改输入读取范围。
+
+### 副作用说明
+
+不运行分析、不读取数据，也不测量内存峰值。
+
+返回类型：ExplainReport。

chronaxis/guide/api/index.json

@@ -0,0 +1,185 @@
+{
+  "device_label": "home",
+  "objects": [
+    {
+      "name": "AnalysisPlan",
+      "group": "计划加载与检查",
+      "signature": "(config_version: int, dataset: chronaxis.planning.models.DatasetPlan, sources: tuple[chronaxis.planning.models.SourcePlan, ...], signals: tuple[chronaxis.planning.models.SignalPlan, ...], derived: tuple[chronaxis.planning.models.DerivedPlan, ...], rules: tuple[chronaxis.planning.models.RulePlan, ...], windows: tuple[chronaxis.planning.models.WindowPlan, ...], calculations: tuple[chronaxis.planning.models.CalculationPlan, ...], presets: tuple[chronaxis.planning.preset_models.PresetSpec, ...], preset_bindings: tuple[tuple[chronaxis.planning.preset_models.RoleBinding, ...], ...], execution: chronaxis.planning.models.ExecutionPlan, outputs: chronaxis.planning.models.OutputPlan, bindings: chronaxis.core.declarations.DeclarationBindings, derived_expressions: tuple[chronaxis.core.expression.StaticExpression, ...], metadata: collections.abc.Mapping, raw_config: collections.abc.Mapping, base_dir: pathlib.Path, identity: str, message_calculations: tuple[chronaxis.planning.models.MessageCalculationPlan, ...] = (), sequences: tuple[chronaxis.planning.sequences.SequencePlan, ...] = (), intervals: 'IntervalPlan | None' = None, diagnostics: 'DiagnosticPlan | None' = None) -> None",
+      "file": "api/AnalysisPlan.md"
+    },
+    {
+      "name": "load_analysis_plan",
+      "group": "计划加载与检查",
+      "signature": "(path: pathlib.Path | str) -> chronaxis.planning.plan.AnalysisPlan",
+      "file": "api/load_analysis_plan.md"
+    },
+    {
+      "name": "validate_analysis_plan",
+      "group": "计划加载与检查",
+      "signature": "(plan: chronaxis.planning.plan.AnalysisPlan) -> chronaxis.planning.reports.ValidationReport",
+      "file": "api/validate_analysis_plan.md"
+    },
+    {
+      "name": "explain_analysis_plan",
+      "group": "计划加载与检查",
+      "signature": "(plan: chronaxis.planning.plan.AnalysisPlan) -> chronaxis.planning.reports.ExplainReport",
+      "file": "api/explain_analysis_plan.md"
+    },
+    {
+      "name": "PlanValidationError",
+      "group": "计划加载与检查",
+      "signature": "(path: str, message: str, code: str = 'invalid_config', *, hint=None, source=None, location=None, object_name=None, value=None)",
+      "file": "api/PlanValidationError.md"
+    },
+    {
+      "name": "AnalysisRunner",
+      "group": "执行与结果",
+      "signature": "(backend=None)",
+      "file": "api/AnalysisRunner.md"
+    },
+    {
+      "name": "AnalysisResult",
+      "group": "执行与结果",
+      "signature": "(spool: chronaxis.results.spool.ResultSpool, metadata: chronaxis.results.manifest.RunMetadata, table_format: str = 'csv', *, artifact_exports=None, owned_work=None)",
+      "file": "api/AnalysisResult.md"
+    },
+    {
+      "name": "OutputManifest",
+      "group": "执行与结果",
+      "signature": "(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",
+      "file": "api/OutputManifest.md"
+    },
+    {
+      "name": "RunMetadata",
+      "group": "执行与结果",
+      "signature": "(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",
+      "file": "api/RunMetadata.md"
+    },
+    {
+      "name": "AnalysisError",
+      "group": "执行与结果",
+      "signature": null,
+      "file": "api/AnalysisError.md"
+    },
+    {
+      "name": "ResultClosedError",
+      "group": "执行与结果",
+      "signature": null,
+      "file": "api/ResultClosedError.md"
+    },
+    {
+      "name": "BatchPlan",
+      "group": "批量任务",
+      "signature": "(jobs: tuple[chronaxis.batch.models.BatchJob, ...], process_count: int = 1, fail_fast: bool = False, backend: str | None = None) -> None",
+      "file": "api/BatchPlan.md"
+    },
+    {
+      "name": "BatchJob",
+      "group": "批量任务",
+      "signature": "(job_id: str, plan: chronaxis.planning.plan.AnalysisPlan | pathlib.Path) -> None",
+      "file": "api/BatchJob.md"
+    },
+    {
+      "name": "BatchJobResult",
+      "group": "批量任务",
+      "signature": "(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",
+      "file": "api/BatchJobResult.md"
+    },
+    {
+      "name": "BatchReport",
+      "group": "批量任务",
+      "signature": "(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",
+      "file": "api/BatchReport.md"
+    },
+    {
+      "name": "BatchRunner",
+      "group": "批量任务",
+      "signature": "(process_count=1, *, fail_fast=False, backend=None)",
+      "file": "api/BatchRunner.md"
+    },
+    {
+      "name": "load_batch_plan",
+      "group": "批量任务",
+      "signature": "(path: str | pathlib.Path) -> chronaxis.batch.models.BatchPlan",
+      "file": "api/load_batch_plan.md"
+    },
+    {
+      "name": "run_batch",
+      "group": "批量任务",
+      "signature": "(plan: chronaxis.batch.models.BatchPlan, output_dir, *, process_count: int | None = None, cancel_event=None, device_label='pending')",
+      "file": "api/run_batch.md"
+    },
+    {
+      "name": "PresetSpec",
+      "group": "业务预设",
+      "signature": "(id: str, preset_type: str, version: str, role_bindings: collections.abc.Mapping, parameters: collections.abc.Mapping) -> None",
+      "file": "api/PresetSpec.md"
+    },
+    {
+      "name": "PlanFragment",
+      "group": "业务预设",
+      "signature": "(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",
+      "file": "api/PlanFragment.md"
+    },
+    {
+      "name": "build_preset",
+      "group": "业务预设",
+      "signature": "(spec: chronaxis.planning.preset_models.PresetSpec, signals: tuple[chronaxis.core.binding.SignalDefinition, ...]) -> chronaxis.planning.preset_models.PlanFragment",
+      "file": "api/build_preset.md"
+    },
+    {
+      "name": "resolve_preset_roles",
+      "group": "业务预设",
+      "signature": "(spec: chronaxis.planning.preset_models.PresetSpec, signals: tuple[chronaxis.core.binding.SignalDefinition, ...]) -> tuple[chronaxis.planning.preset_models.RoleBinding, ...]",
+      "file": "api/resolve_preset_roles.md"
+    },
+    {
+      "name": "TimeConversion",
+      "group": "时间转换",
+      "signature": "(time_ns: int, input_representation: str, input_unit: str, input_text: str, quantized: bool, precision_limited: bool = False, rounding: str = 'round_half_even', source_timezone: str | None = None) -> None",
+      "file": "api/TimeConversion.md"
+    },
+    {
+      "name": "TimeOverflowError",
+      "group": "时间转换",
+      "signature": null,
+      "file": "api/TimeOverflowError.md"
+    },
+    {
+      "name": "checked_add_ns",
+      "group": "时间转换",
+      "signature": "(time_ns: int, offset_ns: int) -> int",
+      "file": "api/checked_add_ns.md"
+    },
+    {
+      "name": "convert_time",
+      "group": "时间转换",
+      "signature": "(value: int | float | str | decimal.Decimal, unit: str) -> chronaxis.timebase.conversion.TimeConversion",
+      "file": "api/convert_time.md"
+    },
+    {
+      "name": "parse_datetime_ns",
+      "group": "时间转换",
+      "signature": "(text: str, source_timezone: datetime.tzinfo | None = None) -> chronaxis.timebase.conversion.TimeConversion",
+      "file": "api/parse_datetime_ns.md"
+    },
+    {
+      "name": "parse_duration",
+      "group": "时间转换",
+      "signature": "(text: str) -> chronaxis.timebase.conversion.TimeConversion",
+      "file": "api/parse_duration.md"
+    },
+    {
+      "name": "shift_times_reference",
+      "group": "时间转换",
+      "signature": "(times: Sequence[int], offset_ns: int) -> tuple[int, ...]",
+      "file": "api/shift_times_reference.md"
+    },
+    {
+      "name": "time_deltas_reference",
+      "group": "时间转换",
+      "signature": "(times: Sequence[int]) -> tuple[int, ...]",
+      "file": "api/time_deltas_reference.md"
+    }
+  ]
+}

chronaxis/guide/api/load_analysis_plan.md

@@ -0,0 +1,34 @@
+# load_analysis_plan
+
+推荐导入：`from chronaxis import load_analysis_plan`
+
+<a id="api-load_analysis_plan"></a>
+## `load_analysis_plan`
+
+加载JSON/YAML及显式公共定义，应用受限覆盖并编译分析计划。目录输入会展开文件名；信号缺省类型、单位或枚举映射时按需读取DBC，不扫描业务报文。
+
+```python
+load_analysis_plan(path: Path | str) -> AnalysisPlan
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`path`|Path &#124; str|是|无|位置或关键字。配置文件路径；不接受目录扫描或任意路径对象。 配置按UTF-8读取，允许文件开头带BOM。|
+
+### 返回说明
+
+AnalysisPlan：已检查并编译的计划。加载主配置与显式公共定义，按声明展开文件集合，必要时读取DBC元数据；不读取业务报文或CSV记录。
+
+### 异常说明
+
+PlanValidationError: 路径类型错误、文件读取或编码错误、JSON/YAML语法错误、
+        重复键、非有限常量或配置声明错误。加载错误带配置文件定位，
+        通过原异常链保留更详细的原因。
+
+### 副作用说明
+
+打开指定配置及公共定义文件，按需求读取DBC或枚举目录；句柄在正常或异常返回前关闭，不创建结果文件。
+
+返回类型：AnalysisPlan。

chronaxis/guide/api/load_batch_plan.md

@@ -0,0 +1,36 @@
+# load_batch_plan
+
+推荐导入：`from chronaxis import load_batch_plan`
+
+<a id="api-load_batch_plan"></a>
+## `load_batch_plan`
+
+读取批量YAML或JSON文件，建立独立任务及其调度设置。
+
+```python
+load_batch_plan(path: str | Path) -> BatchPlan
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`path`|str &#124; Path|是|无|位置或关键字。批量JSON/YAML路径；子计划、模板和inputs的路径以批量文件为基准。jobs在任务启动时加载，template在本调用中展开并编译各独立计划。|
+
+### 返回说明
+
+BatchPlan: 已检查批量结构的不可变计划；template已展开，jobs仍保存路径，均未读取业务输入。
+
+### 异常说明
+
+PlanValidationError表示路径、语法、批量字段或模板展开失败，按异常位置修正。jobs子计划错误在任务启动时记入报告；template编译错误在本调用返回前报告。
+
+### 副作用说明
+
+读取批量文件，template模式还读取模板与必要DBC、枚举输入集合；不创建输出目录。
+
+返回类型：BatchPlan。
+
+# 先按批量指南准备batch.yaml和它引用的子计划。
+plan = load_batch_plan("batch.yaml")
+```

chronaxis/guide/api/parse_datetime_ns.md

@@ -0,0 +1,35 @@
+# parse_datetime_ns
+
+推荐导入：`from chronaxis import parse_datetime_ns`
+
+<a id="api-parse_datetime_ns"></a>
+## `parse_datetime_ns`
+
+将ISO完整日期转换为UTC整数纳秒，保留亚微秒分数。
+
+```python
+parse_datetime_ns(text: str, source_timezone: tzinfo | None=None) -> TimeConversion
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`text`|str|是|无|位置或关键字。YYYY-MM-DDTHH:MM:SS[.fraction][Z/±HH:MM]，也允许空格分隔。|
+|`source_timezone`|tzinfo &#124; None|否|None|位置或关键字。为没有时区偏移的日期指定时区对象；如from datetime import timezone后传timezone.utc，或timezone(timedelta(hours=8))。必须是tzinfo实例，不能传YAML用的字符串。日期已有偏移时以日期为准；None且日期无偏移会报错。|
+
+### 返回说明
+
+TimeConversion: UTC epoch纳秒、量化与实际采用时区，非机器默认。
+
+### 异常说明
+
+TypeError/ValueError: 文本/时区非法、naive缺时区、本地时刻模糊或不存在。
+    TimeOverflowError: int64时间超界。
+    OverflowError: 转到UTC时超出datetime历法边界。
+
+### 副作用说明
+
+无；不调用系统本地时区，不加载IANA名称或访问文件。
+
+返回类型：TimeConversion。

chronaxis/guide/api/parse_duration.md

@@ -0,0 +1,30 @@
+# parse_duration
+
+推荐导入：`from chronaxis import parse_duration`
+
+<a id="api-parse_duration"></a>
+## `parse_duration`
+
+解析带单位的非负持续参数，允许显式零长度。
+
+```python
+parse_duration(text: str) -> TimeConversion
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`text`|str|是|无|位置或关键字。完整数值后缀，如500ms、3s、0ns。|
+
+### 返回说明
+
+TimeConversion: 纳秒持续时间，原带单位文本保留。
+
+### 异常说明
+
+TypeError: 非文本。
+    ValueError: 缺单位、非法语法或原数值为负，即使负小值会舍为0。
+    TimeOverflowError: 换算/舍入超int64。
+
+返回类型：TimeConversion。

chronaxis/guide/api/resolve_preset_roles.md

@@ -0,0 +1,37 @@
+# resolve_preset_roles
+
+推荐导入：`from chronaxis import resolve_preset_roles`
+
+<a id="api-resolve_preset_roles"></a>
+## `resolve_preset_roles`
+
+显式优先解析本次实际角色，否则按版本化语义契约寻找唯一合格候选。
+
+```python
+resolve_preset_roles(spec: PresetSpec, signals: tuple[SignalDefinition, ...]) -> tuple[RoleBinding, ...]
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`spec`|PresetSpec|是|无|位置或关键字。提供PresetSpec预设声明，可用PresetSpec.from_dict({...})从必填name、preset_type、parameters，以及可选version、role_bindings的Python字典建立；完整可运行调用见预设API示例。|
+|`signals`|tuple[SignalDefinition, ...]|是|无|位置或关键字。提供本计划的SignalDefinition元组，例如tuple(item.definition for item in plan.signals)，其中plan由load_analysis_plan取得；角色引用这些定义的name，不直接填CSV列名。|
+
+### 返回说明
+
+RoleBinding tuple，保留原定义与explicit/semantic_unique路径。
+
+### 异常说明
+
+PlanValidationError为类型、重复别名、未知角色、缺项、候选歧义或契约冲突。
+
+- PlanValidationError：需要PresetSpec与SignalDefinition tuple。
+- PlanValidationError：signal别名重复。
+- PlanValidationError：threshold_excursion必须显式指定signal角色。
+
+### 边界说明
+
+显式别名无需semantic_id，仍检查类型/单位/方向/位置/质量；不选第一个候选。
+
+返回类型：tuple[RoleBinding, ...]。

chronaxis/guide/api/run_batch.md

@@ -0,0 +1,38 @@
+# run_batch
+
+推荐导入：`from chronaxis import run_batch`
+
+<a id="api-run_batch"></a>
+## `run_batch`
+
+执行一批独立分析并写出批量报告。使用spawn工作进程，各任务单独加载、分析、发布和清理；在Python脚本的main保护内调用。
+
+```python
+run_batch(plan: BatchPlan, output_dir, *, process_count: int | None=None, cancel_event=None, device_label='pending')
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`plan`|BatchPlan|是|无|位置或关键字。指定要执行的批量任务及调度设置。传入load_batch_plan("batch.yaml")取得的BatchPlan，不能直接传文件名或普通分析计划。|
+|`output_dir`|str &#124; Path|是|无|位置或关键字。新批量结果目录，每个任务按id创建子目录；目标已经存在时拒绝覆盖。|
+|`process_count`|int &#124; None|否|None|仅关键字。覆盖本次分析工作进程数。填正整数，例如4；None沿用BatchPlan.process_count，不修改原计划。|
+|`cancel_event`|threading.Event &#124; None|否|None|仅关键字。可选取消标记；None表示没有。其他线程调用set()后停止派发新任务，正在执行的任务继续收尾。|
+|`device_label`|str|否|'pending'|仅关键字。产出记录的设备标签，例如已核实的"home"或"work"；未确定时用"pending"。这是来源说明，不参与数值计算，也不根据文件路径猜测。|
+
+### 返回说明
+
+BatchReport；failed/cancelled保留在报告，不伪装全部成功。
+
+### 异常说明
+
+TypeError：plan不是BatchPlan或取消对象类型不合法。ValueError：并发/后端/任务声明不合法。目录创建、调度或报告发布失败按具体异常类型抛出；若已产生报告，异常batch_report保存实际进度，调用者仍须close处理cleanup_pending。单任务失败通常保存在报告jobs中，不作为整个函数抛错。见按阶段处理错误。
+
+# batch.yaml须已按批量指南准备；batch-output必须不存在。
+report = run_batch(load_batch_plan("batch.yaml"), "batch-output")
+try:
+    print(report.to_dict())
+finally:
+    report.close()
+```

chronaxis/guide/api/shift_times_reference.md

@@ -0,0 +1,33 @@
+# shift_times_reference
+
+推荐导入：`from chronaxis import shift_times_reference`
+
+<a id="api-shift_times_reference"></a>
+## `shift_times_reference`
+
+逐项独立计算固定偏移，作为数组内核的整数真值参考。
+
+```python
+shift_times_reference(times: Sequence[int], offset_ns: int) -> tuple[int, ...]
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`times`|Sequence[int]|是|无|位置或关键字。已声明纳秒坐标，不要求排序。|
+|`offset_ns`|int|是|无|位置或关键字。合法int64固定偏移。|
+
+### 返回说明
+
+tuple[int,...]: 新整数序列，空输入返回空tuple。
+
+### 异常说明
+
+TypeError/TimeOverflowError: 参数类型或任一坐标/结果超界。
+
+### 副作用说明
+
+无；不导入或调用NumPy实现，不修改输入。
+
+返回类型：tuple[int, ...]。