chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/en/api/RunMetadata.md

@@ -0,0 +1,100 @@
+# RunMetadata
+
+Import: `from chronaxis import RunMetadata`
+
+<a id="api-RunMetadata"></a>
+## `RunMetadata`
+
+Stores run identity, actual backend, time interpretation, and diagnostic summaries. Normally read it from an open AnalysisResult.metadata rather than constructing it yourself. Detailed source models are optional and have content only when a caller supplies actual reading details. The public AnalysisRunner currently leaves can_sources and text_can_sources empty; this neither means no CAN files were read nor proves a DBC was validated. See to_dict below for summary and detailed serialization.
+
+```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
+```
+
+### Properties and data fields
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`run_id`|str|Yes|None|Unique run identity associated with published manifests and resource records.|
+|`input_identity`|str &#124; None|Yes|None|Trace summary for actual input reading. None means no such summary was supplied, not that content was verified.|
+|`plan_hash`|str|Yes|None|SHA-256 identity of plan declarations. Actual backend overrides are recorded separately.|
+|`backend`|str|Yes|None|Actual backend: reference or numpy. Recorded from effective runner settings; callers normally do not construct this result field.|
+|`config_version`|int|Yes|None|Actual analysis structure version: native integer 3, not preset or software version. Version 1 and Boolean values are rejected.|
+|`source_time_interpretation`|str|Yes|None|Description of source time coordinates, units, and conversion conventions.|
+|`session_boundaries`|tuple[tuple[str, int, int], ...]|Yes|None|Actual (session_id, start_ns, end_ns) tuples. Times are integer nanoseconds with half-open ranges. An empty tuple means boundaries were not established, not an observed zero-duration session.|
+|`started_at`|str|Yes|None|Runner-generated timezone-aware ISO 8601 run start, e.g. 2026-10-27T19:00:00+08:00. This is not the first sample timestamp.|
+|`mapping_hashes`|tuple[str, ...]|No|()|Recorded mapping-identity digests; empty when not applicable. Empty does not mean verified.|
+|`dbc_hashes`|tuple[str, ...]|No|()|Recorded DBC digests; empty when not applicable.|
+|`parsing_policy`|str|No|'decoded-results'|Name of the parsing/access policy used.|
+|`worker_config`|str|No|'single-thread'|Description of worker settings. A single-thread label is not a performance guarantee.|
+|`dependency_versions`|tuple[tuple[str, str], ...]|No|()|Recorded (name, version) dependency tuples.|
+|`limitations`|tuple[str, ...]|No|()|Known limitations for this run, retained in published metadata.|
+|`software_version`|str|No|'0.1.0.dev0'|Software version, separate from design and configuration versions.|
+|`device_label`|str|No|'pending'|Actual content-origin device label; do not infer home/work from a file path.|
+|`signal_bindings`|tuple[SignalDefinition, ...]|No|()|Complete signal definitions for the run, without samples or input rows.|
+|`preset_bindings`|tuple[PresetBindingMetadata, ...]|No|()|Original preset versions and resolved roles.|
+|`can_sources`|tuple[CANSourceMetadata, ...]|No|()|Tuple of CANSourceMetadata. Each item can describe sclicer-functions-v1 single-BLF source name, original/DBC paths, channel, frame count, endpoints, and unit checks. Supplied explicitly by a RunMetadata caller; public AnalysisRunner does not populate it. Default () means details were not supplied, not that CAN input was absent. Check nonempty before reading metadata.can_sources[0].source or .frame_count.|
+|`session_ids`|tuple[str, ...]|No|()|Explicit session identities when no time range was requested; does not fabricate boundaries.|
+|`text_can_sources`|tuple[TextCANSourceMetadata, ...]|No|()|Tuple of TextCANSourceMetadata, describing can-text-v1 source, inputs (path, parser, offset_ns), DBC digests, record counts, and observation times. Explicitly caller-supplied; public AnalysisRunner does not populate it. Default () means details were not supplied. Check nonempty before reading metadata.text_can_sources[0].inputs or .record_count; an empty tuple does not establish empty input.|
+|`threshold_durations`|tuple[SummaryThresholdDuration, ...]|No|()|Threshold-preset duration summaries. Each SummaryThresholdDuration has preset_id, rule_id, value, unit, and status. A partial value counts only known seconds, not a complete total. Empty when no such preset applies.|
+|`detailed_diagnostics`|bool|No|False|Whether extra detailed fields are serialized in the manifest: True includes applicable detail, False uses summaries. This result-model field cannot be edited to retroactively perform missing analysis.|
+|`retain_work`|bool|No|False|Explicit request to retain work files; false by default.|
+|`input_diagnostics`|tuple[InputDiagnostic, ...]|No|()|Requested information about inputs needed in this run.|
+|`trace_requested`|bool|No|False|Whether diagnostics.trace was enabled. Actual rows are read through the result trace iterator.|
+|`integrity_diagnostics`|bool|No|False|Whether diagnostics.integrity requested input-integrity summaries. Independent of row tracing.|
+|`frame_format_notices`|tupletuple[str, [CANFrameFormatNotice], ...]|No|()|Verified frame-format differences are always reported, independently of optional diagnostics.|
+|`analysis_outcome`|AnalysisOutcome &#124; None|No|None|AnalysisOutcome accumulated during this run, or None. Reports events, unmet conditions/durations, no observations, or insufficient data per rule, and counts complete/partial/indeterminate calculation rows. None means this path did not supply a summary, not no events; completed means execution finished. No second scan or row trace is performed.|
+
+
+<a id="api-RunMetadata-estimated_bytes"></a>
+### `RunMetadata.estimated_bytes`
+
+Estimates metadata and temporary-object cost before asdict/JSON copying.
+
+```python
+RunMetadata.estimated_bytes() -> int
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Conservative byte estimate.
+
+#### Raises
+
+None expected; types have already been validated.
+
+Return type: int。
+
+
+<a id="api-RunMetadata-to_dict"></a>
+### `RunMetadata.to_dict`
+
+Returns independent JSON-compatible metadata. The caller must reserve estimated_bytes before copying.
+
+```python
+RunMetadata.to_dict() -> dict
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Independent JSON-compatible dict. Default detailed_diagnostics=False emits the run summary and applicable optional summaries. Nonempty signal_bindings/preset_bindings/can_sources do not cause those detailed keys to appear. True expands detailed models, still omitting empty optional details according to their rules. See Run metadata for both modes and key examples.
+
+#### Raises
+
+No expected exception; the caller must account for estimated_bytes before copying.
+
+Return type: dict。

chronaxis/guide/en/api/TimeConversion.md

@@ -0,0 +1,23 @@
+# TimeConversion
+
+Import: `from chronaxis import TimeConversion`
+
+<a id="api-TimeConversion"></a>
+## `TimeConversion`
+
+Store a normalized time and source-precision diagnostics without mutable conversion state leaking across tasks. Entry points validate `time_ns` as int64. Quantization and pre-existing float limits are recorded separately. `input_text` preserves only the representation seen by conversion, not proof of upstream precision; `source_timezone` records the chosen timezone, not proof of source synchronization.
+
+```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
+```
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `time_ns` | int | Required | Core coordinate or duration in signed 64-bit nanoseconds. |
+| `input_representation` | str | Required | Actual representation, such as integer/decimal_text/decimal/binary_float/ISO8601. |
+| `input_unit` | str | Required | Explicit s/ms/us/ns; datetime entry uses ISO8601. |
+| `input_text` | str | Required | Text seen at this entry point; does not store a user log or assume greater source precision. |
+| `quantized` | bool | Required | True if the exact representation needed nanosecond rounding, including rounding to zero. |
+| `precision_limited` | bool | Optional; False | True for an existing binary float because pre-float precision cannot be recovered. Even 1.0 has True when quantized is False. Integers, decimal text, and Decimal use False; this says nothing about synchronization. |
+| `rounding` | str | Optional; `'round_half_even'` | Final nanosecond rounding is fixed to nearest, ties to even. |
+| `source_timezone` | str &#124; None | Optional; None | Description of the tzinfo actually used for a datetime; not inferred for numeric time. |

chronaxis/guide/en/api/TimeOverflowError.md

@@ -0,0 +1,14 @@
+# TimeOverflowError
+
+Import: `from chronaxis import TimeOverflowError`
+
+<a id="api-TimeOverflowError"></a>
+## `TimeOverflowError`
+
+Reject a coordinate, shifted coordinate, or nonnegative span outside int64. The exception carries no wrapped result that could be mistaken for valid data; callers record the failure as a task validation error. It adds no mutable state, opens no resources, and does not turn failure into zero duration.
+
+```python
+class TimeOverflowError(OverflowError)
+```
+
+Base class: `OverflowError`. No additional fields are declared by this class.

chronaxis/guide/en/api/build_preset.md

@@ -0,0 +1,23 @@
+# build_preset
+
+Import: `from chronaxis import build_preset`
+
+<a id="api-build_preset"></a>
+## `build_preset`
+
+Validate a version-1 preset and expand public declarations, without I/O or numerical analysis.
+
+```python
+build_preset(spec: PresetSpec, signals: tuple[SignalDefinition, ...]) -> PlanFragment
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `spec` | PresetSpec | Required | Positional or keyword. Create through PresetSpec.from_dict using required name/preset_type/parameters and optional version/role_bindings. See the preset API examples. |
+| `signals` | tuple[SignalDefinition, ...] | Required | Positional or keyword. Signal definitions for this plan, such as `tuple(item.definition for item in plan.signals)` after load_analysis_plan. Roles refer to definition names, not directly to CSV columns. Type link is a Chinese implementation reference. |
+
+Returns PlanFragment, generating the requested power/Wh/Ah, alarm context, threshold hysteresis/per-activity durations, or response pairing.
+
+Raises `PlanValidationError` for parameters, role contracts, mode-code ranges, or generated IDs colliding with signals. In particular, mode codes must fit declared dtype/valid_range.
+
+Processing checks roles, generates an expression using simple aliases, constructs typed nodes, and rejects visible ID conflicts. AnalysisPlan checks conflicts against other user nodes and presets when merging the fragment.

chronaxis/guide/en/api/checked_add_ns.md

@@ -0,0 +1,21 @@
+# checked_add_ns
+
+Import: `from chronaxis import checked_add_ns`
+
+<a id="api-checked_add_ns"></a>
+## `checked_add_ns`
+
+Add a fixed offset to a nanosecond coordinate, checking the int64 range.
+
+```python
+checked_add_ns(time_ns: int, offset_ns: int) -> int
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `time_ns` | int | Required | Positional or keyword. Original int64 coordinate in nanoseconds. |
+| `offset_ns` | int | Required | Positional or keyword. Int64 offset in nanoseconds. |
+
+Returns the exact new integer coordinate. Successful addition does not establish synchronization between sources.
+
+Raises `TypeError` if either argument is not a non-boolean integer. Raises `TimeOverflowError` if either argument or the sum is outside int64.

chronaxis/guide/en/api/convert_time.md

@@ -0,0 +1,25 @@
+# convert_time
+
+Import: `from chronaxis import convert_time`
+
+<a id="api-convert_time"></a>
+## `convert_time`
+
+Convert a value with an explicit unit to nanoseconds, rounding the final result to nearest, ties to even.
+
+```python
+convert_time(value: int | float | str | Decimal, unit: str) -> TimeConversion
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `value` | int &#124; float &#124; str &#124; Decimal | Required | Positional or keyword. Finite integer, decimal text, Decimal, or existing float. Negative time coordinates are allowed. |
+| `unit` | str | Required | Positional or keyword. Case-sensitive `s`, `ms`, `us`, or `ns`; no default unit. |
+
+Returns TimeConversion containing integer nanoseconds, input representation/unit, and separate diagnostics for nanosecond rounding and pre-existing floating-point precision limits.
+
+Raises `TypeError` or `ValueError` for an invalid type, text syntax, significant-digit length, or unit. Raises `TimeOverflowError` when the rounded result exceeds int64.
+
+The conversion separates sign, coefficient, and exponent, scales or divides in integer arithmetic, and rounds to integer nanoseconds. It rejects very large positive exponents early and identifies very large negative exponents as rounding to zero, avoiding unbounded allocation.
+
+No side effects: inputs, Decimal context, and time basis are unchanged.

chronaxis/guide/en/api/explain_analysis_plan.md

@@ -0,0 +1,30 @@
+# explain_analysis_plan
+
+Import: `from chronaxis import explain_analysis_plan`
+
+<a id="api-explain_analysis_plan"></a>
+## `explain_analysis_plan`
+
+List plan dependencies, node calculation methods, history requirements, and declared budgets.
+
+```python
+explain_analysis_plan(plan: AnalysisPlan) -> ExplainReport
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `plan` | AnalysisPlan | Required | Positional or keyword. A checked plan from `load_analysis_plan("analysis.yaml")` or `AnalysisPlan.from_dict(config)`, not a YAML filename string. |
+
+Returns ExplainReport (Chinese implementation reference), including the same validation limits, dependency nodes, `history_ns`, and a read-only budget mapping. Existing numeric kernels and unsupported nodes are identified separately; the whole plan should not be assumed to execute as one array operation.
+
+Raises `TypeError` if input is not an AnalysisPlan.
+
+Processing expands derived, rule, window, and calculation dependencies, including conditions in event/window scopes. It reports the larger of original-signal validity and required window pre-history; it does not change the input reading range.
+
+No execution/data-reading side effects and no measurement of peak memory.
+
+```python
+from chronaxis import load_analysis_plan, explain_analysis_plan
+plan = load_analysis_plan("../examples/analysis.yaml")
+print(explain_analysis_plan(plan))
+```

chronaxis/guide/en/api/index.json

@@ -0,0 +1,185 @@
+{
+  "language": "en",
+  "objects": [
+    {
+      "name": "AnalysisPlan",
+      "group": "Loading and checking plans",
+      "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": "Loading and checking plans",
+      "signature": "(path: pathlib.Path | str) -> chronaxis.planning.plan.AnalysisPlan",
+      "file": "api/load_analysis_plan.md"
+    },
+    {
+      "name": "validate_analysis_plan",
+      "group": "Loading and checking plans",
+      "signature": "(plan: chronaxis.planning.plan.AnalysisPlan) -> chronaxis.planning.reports.ValidationReport",
+      "file": "api/validate_analysis_plan.md"
+    },
+    {
+      "name": "explain_analysis_plan",
+      "group": "Loading and checking plans",
+      "signature": "(plan: chronaxis.planning.plan.AnalysisPlan) -> chronaxis.planning.reports.ExplainReport",
+      "file": "api/explain_analysis_plan.md"
+    },
+    {
+      "name": "PlanValidationError",
+      "group": "Loading and checking plans",
+      "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": "Execution and results",
+      "signature": "(backend=None)",
+      "file": "api/AnalysisRunner.md"
+    },
+    {
+      "name": "AnalysisResult",
+      "group": "Execution and results",
+      "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": "Execution and results",
+      "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": "Execution and results",
+      "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": "Execution and results",
+      "signature": null,
+      "file": "api/AnalysisError.md"
+    },
+    {
+      "name": "ResultClosedError",
+      "group": "Execution and results",
+      "signature": null,
+      "file": "api/ResultClosedError.md"
+    },
+    {
+      "name": "BatchPlan",
+      "group": "Batch tasks",
+      "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": "Batch tasks",
+      "signature": "(job_id: str, plan: chronaxis.planning.plan.AnalysisPlan | pathlib.Path) -> None",
+      "file": "api/BatchJob.md"
+    },
+    {
+      "name": "BatchJobResult",
+      "group": "Batch tasks",
+      "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": "Batch tasks",
+      "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": "Batch tasks",
+      "signature": "(process_count=1, *, fail_fast=False, backend=None)",
+      "file": "api/BatchRunner.md"
+    },
+    {
+      "name": "load_batch_plan",
+      "group": "Batch tasks",
+      "signature": "(path: str | pathlib.Path) -> chronaxis.batch.models.BatchPlan",
+      "file": "api/load_batch_plan.md"
+    },
+    {
+      "name": "run_batch",
+      "group": "Batch tasks",
+      "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": "Domain presets",
+      "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": "Domain presets",
+      "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": "Domain presets",
+      "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": "Domain presets",
+      "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": "Time conversion",
+      "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": "Time conversion",
+      "signature": null,
+      "file": "api/TimeOverflowError.md"
+    },
+    {
+      "name": "checked_add_ns",
+      "group": "Time conversion",
+      "signature": "(time_ns: int, offset_ns: int) -> int",
+      "file": "api/checked_add_ns.md"
+    },
+    {
+      "name": "convert_time",
+      "group": "Time conversion",
+      "signature": "(value: int | float | str | decimal.Decimal, unit: str) -> chronaxis.timebase.conversion.TimeConversion",
+      "file": "api/convert_time.md"
+    },
+    {
+      "name": "parse_datetime_ns",
+      "group": "Time conversion",
+      "signature": "(text: str, source_timezone: datetime.tzinfo | None = None) -> chronaxis.timebase.conversion.TimeConversion",
+      "file": "api/parse_datetime_ns.md"
+    },
+    {
+      "name": "parse_duration",
+      "group": "Time conversion",
+      "signature": "(text: str) -> chronaxis.timebase.conversion.TimeConversion",
+      "file": "api/parse_duration.md"
+    },
+    {
+      "name": "shift_times_reference",
+      "group": "Time conversion",
+      "signature": "(times: Sequence[int], offset_ns: int) -> tuple[int, ...]",
+      "file": "api/shift_times_reference.md"
+    },
+    {
+      "name": "time_deltas_reference",
+      "group": "Time conversion",
+      "signature": "(times: Sequence[int]) -> tuple[int, ...]",
+      "file": "api/time_deltas_reference.md"
+    }
+  ]
+}

chronaxis/guide/en/api/load_analysis_plan.md

@@ -0,0 +1,27 @@
+# load_analysis_plan
+
+Import: `from chronaxis import load_analysis_plan`
+
+<a id="api-load_analysis_plan"></a>
+## `load_analysis_plan`
+
+Load JSON/YAML and explicit shared definitions, apply supported overrides, and compile a plan. Input-directory declarations expand filenames. Missing signal type, unit, or enum choices can require DBC metadata, but business-message records are not scanned.
+
+```python
+load_analysis_plan(path: Path | str) -> AnalysisPlan
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `path` | Path &#124; str | Required | Positional or keyword. Configuration file path, not a directory to scan or an arbitrary path object. Read as UTF-8, allowing an initial BOM. |
+
+Returns a checked and compiled AnalysisPlan. It loads the main configuration/shared definitions, expands declared file sets, and reads DBC metadata as needed; it does not read business-message or CSV records.
+
+Raises `PlanValidationError` for invalid path type, file read/encoding failures, JSON/YAML syntax, duplicate keys, nonfinite constants, or invalid declarations. Load errors include configuration file location and preserve detailed causes through exception chaining.
+
+Side effects: opens configuration/shared files, reads DBCs or enumerates directories as needed, and closes handles before normal or exceptional return. Does not create result files.
+
+```python
+from chronaxis import load_analysis_plan
+plan = load_analysis_plan("../examples/analysis.yaml")
+```

chronaxis/guide/en/api/load_batch_plan.md

@@ -0,0 +1,28 @@
+# load_batch_plan
+
+Import: `from chronaxis import load_batch_plan`
+
+<a id="api-load_batch_plan"></a>
+## `load_batch_plan`
+
+Read a batch YAML/JSON file and construct its independent tasks and scheduling settings.
+
+```python
+load_batch_plan(path: str | Path) -> BatchPlan
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `path` | str &#124; Path | Required | Positional or keyword. Batch JSON/YAML path. Child plans, templates, and input paths are relative to this file. `jobs` plans load when each task starts; `template` expands and compiles independent plans during this call. |
+
+Returns an immutable BatchPlan with checked batch structure. Templates are expanded, while jobs retain paths. Neither reads business-input records at this stage.
+
+Raises `PlanValidationError` for path, syntax, batch-field, or template-expansion failures. Child-plan errors in jobs are recorded when a task starts; template compilation errors are reported before this call returns.
+
+Side effects: reads the batch file; template mode also reads the template and necessary DBCs and enumerates inputs. Creates no output directories.
+
+```python
+from chronaxis import load_batch_plan
+# Prepare batch.yaml and its child plans as described in the batch guide.
+plan = load_batch_plan("batch.yaml")
+```

chronaxis/guide/en/api/parse_datetime_ns.md

@@ -0,0 +1,23 @@
+# parse_datetime_ns
+
+Import: `from chronaxis import parse_datetime_ns`
+
+<a id="api-parse_datetime_ns"></a>
+## `parse_datetime_ns`
+
+Convert a complete ISO date/time to UTC integer nanoseconds, preserving sub-microsecond fractions.
+
+```python
+parse_datetime_ns(text: str, source_timezone: tzinfo | None=None) -> TimeConversion
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `text` | str | Required | Positional or keyword. `YYYY-MM-DDTHH:MM:SS[.fraction][Z/±HH:MM]`; a space separator is also allowed. |
+| `source_timezone` | tzinfo &#124; None | Optional; None | Positional or keyword. A tzinfo instance for text without an offset, such as `timezone.utc` or `timezone(timedelta(hours=8))` from datetime. YAML timezone strings are not accepted. An explicit offset in the text takes precedence. Text without an offset and a None timezone is an error. |
+
+Returns TimeConversion containing UTC epoch nanoseconds, quantization information, and the timezone actually used, never an assumed machine default.
+
+Raises `TypeError`/`ValueError` for invalid text/timezone, a naive datetime without a timezone, or ambiguous/nonexistent local time; `TimeOverflowError` for int64 overflow; and `OverflowError` when UTC conversion crosses datetime's calendar bounds.
+
+No side effects: it does not consult the system timezone, load IANA timezone names, or access files.

chronaxis/guide/en/api/parse_duration.md

@@ -0,0 +1,20 @@
+# parse_duration
+
+Import: `from chronaxis import parse_duration`
+
+<a id="api-parse_duration"></a>
+## `parse_duration`
+
+Parse a nonnegative duration with a unit, including explicit zero.
+
+```python
+parse_duration(text: str) -> TimeConversion
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `text` | str | Required | Positional or keyword. Complete value with suffix, for example `500ms`, `3s`, or `0ns`. |
+
+Returns TimeConversion with a nanosecond duration and the original unit-bearing text.
+
+Raises `TypeError` for non-text input; `ValueError` for missing units, invalid syntax, or a negative original value, even if it would round to zero; and `TimeOverflowError` for conversion/rounding outside int64.

chronaxis/guide/en/api/resolve_preset_roles.md

@@ -0,0 +1,23 @@
+# resolve_preset_roles
+
+Import: `from chronaxis import resolve_preset_roles`
+
+<a id="api-resolve_preset_roles"></a>
+## `resolve_preset_roles`
+
+Resolve actual roles, preferring explicit mappings. Otherwise find exactly one candidate satisfying the versioned semantic requirements.
+
+```python
+resolve_preset_roles(spec: PresetSpec, signals: tuple[SignalDefinition, ...]) -> tuple[RoleBinding, ...]
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `spec` | PresetSpec | Required | Positional or keyword. Create through PresetSpec.from_dict with required name/preset_type/parameters and optional version/role_bindings. |
+| `signals` | tuple[SignalDefinition, ...] | Required | Positional or keyword. Definitions for this plan, such as `tuple(item.definition for item in plan.signals)` after load_analysis_plan. Roles refer to definition names, not CSV column names. Type link is a Chinese implementation reference. |
+
+Returns a tuple of RoleBinding (Chinese implementation reference), preserving original definitions and the `explicit` / `semantic_unique` resolution path.
+
+Raises `PlanValidationError` for wrong types, duplicate aliases, unknown/missing roles, ambiguous candidates, or contract conflicts. Specific failures include requiring PresetSpec plus a SignalDefinition tuple, duplicate signal aliases, and threshold_excursion missing its mandatory explicit signal role.
+
+Explicit aliases do not require semantic_id, but type, unit, direction, location, and quality requirements still apply. The resolver never silently picks the first candidate.

chronaxis/guide/en/api/run_batch.md

@@ -0,0 +1,39 @@
+# run_batch
+
+Import: `from chronaxis import run_batch`
+
+<a id="api-run_batch"></a>
+## `run_batch`
+
+Run independent analyses and write a batch report. Spawn workers load, analyze, publish, and clean up each job separately. In a Python script, call this inside a main guard.
+
+```python
+run_batch(plan: BatchPlan, output_dir, *, process_count: int | None=None, cancel_event=None, device_label='pending')
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `plan` | BatchPlan | Required | Positional or keyword. BatchPlan from `load_batch_plan("batch.yaml")`, not a filename or an ordinary analysis plan. |
+| `output_dir` | str &#124; Path | Required | Positional or keyword. New batch output directory with job-ID subdirectories. Existing targets cannot be overwritten. |
+| `process_count` | int &#124; None | Optional; None | Keyword-only positive worker-count override; None uses BatchPlan.process_count without modifying the original plan. |
+| `cancel_event` | threading.Event &#124; None | Optional; None | Keyword-only optional signal. set() from another thread stops new dispatch while running jobs finish cleanup. |
+| `device_label` | str | Optional; `'pending'` | Keyword-only verified device label, such as home/work, or pending when unknown. Descriptive only; not inferred from paths. |
+
+Returns BatchReport, retaining failed/cancelled statuses rather than reporting universal success.
+
+Raises `TypeError` for a non-BatchPlan or invalid cancellation type and `ValueError` for invalid concurrency, backend, or job declarations. Directory, scheduling, and report-publication failures retain their specific exception types. If a report already exists, the exception's `batch_report` stores actual progress; the caller must still close it to handle cleanup_pending. Individual job failures normally remain in report.jobs rather than failing the entire function. See errors by execution stage.
+
+```python
+from chronaxis import load_batch_plan, run_batch
+
+def main():
+    # Prepare batch.yaml first; batch-output must not already exist.
+    report = run_batch(load_batch_plan("batch.yaml"), "batch-output")
+    try:
+        print(report.to_dict())
+    finally:
+        report.close()
+
+if __name__ == "__main__":
+    main()
+```

chronaxis/guide/en/api/shift_times_reference.md

@@ -0,0 +1,21 @@
+# shift_times_reference
+
+Import: `from chronaxis import shift_times_reference`
+
+<a id="api-shift_times_reference"></a>
+## `shift_times_reference`
+
+Apply an offset independently to each coordinate as an integer reference for array kernels.
+
+```python
+shift_times_reference(times: Sequence[int], offset_ns: int) -> tuple[int, ...]
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `times` | Sequence[int] | Required | Positional or keyword. Coordinates already expressed in nanoseconds; sorting is not required. |
+| `offset_ns` | int | Required | Positional or keyword. Valid int64 offset. |
+
+Returns a new `tuple[int, ...]`; empty input returns an empty tuple. Raises `TypeError` or `TimeOverflowError` for invalid argument types or any out-of-range input/result.
+
+No side effects: it does not import or call NumPy implementations or modify the input.