chronaxis 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

chronaxis-0.1.0.dev2/Docs/AI/README.md

@@ -0,0 +1,88 @@
+# 用 AI 编写 Chronaxis 分析
+
+[English guide](en/README.md)
+
+从这份README开始，再按[任务索引](tasks.json)选择相关示例，只读任务需要的说明。阅读源码中的指南无需先安装Chronaxis、生成文件或导出ZIP；保留仓库目录结构即可。独立资料ZIP使用同一正文，解压时保留完整目录结构。
+
+先向AI提供本README和[资料版本信息](../Current/documentation.json)，再按需提供示例、接口或字段说明。未另行注明的相对命令以本README所在目录为起点；已安装环境使用下方工作目录示例；配置内部的ASC、DBC路径相对配置文件所在目录。运行分析需要安装匹配版本的Chronaxis，可用 `python -c "from importlib.metadata import version; print(version('chronaxis'))"` 核对。安装包已经附带普通指南文件，`python -m chronaxis guide`只显示中文README的路径，`--language en`选择英文，不写入或解压资料。源码指南同样直接阅读。资料版本与合成示例不代表私人日志已通过验证。
+
+### 在已安装环境中直接使用
+
+从自己的工作目录执行下列PowerShell命令。它直接读取安装目录的指南和示例，结果写到当前工作目录，不复制或修改安装资料：
+
+```powershell
+$guide = Split-Path (python -m chronaxis guide)
+python "$guide/lookup.py" task CONDITION_ENERGY
+python "$guide/run_analysis.py" "$guide/examples/conditional-energy.yaml" result-energy
+```
+
+下文的相对命令展示源码/独立指南目录用法；在安装环境执行时，也可像上面一样使用完整输入路径和自己的输出目录。
+
+## 安装Chronaxis及默认运行依赖
+
+普通安装会自动安装完整运行依赖，支持 BLF、ASC、原始报文 CSV、DBC 解码、已解码信号 CSV 和内存任务。下面在 Windows PowerShell 中创建环境，并安装与本指南对应的 0.1.0.dev2：
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install "chronaxis==0.1.0.dev2"
+.\.venv\Scripts\python.exe -m pip check
+```
+
+若使用本地安装包，将安装参数 `"chronaxis==0.1.0.dev2"` 替换为 `".\chronaxis-0.1.0.dev2-py3-none-any.whl"`。
+
+在后续命令中用同一个 `.venv\Scripts\python.exe`；无需激活环境。该版本声明并已验证的 CAN 依赖为 `python-can==4.6.1`、`cantools==39.4.3`、`natsort==8.4.0`，由 wheel 的默认依赖统一安装。不要为了消除缺模块错误单独安装任意最新版，也不要更改信号、阈值或 DBC。其他依赖版本不代表已验证支持；实际发布物以其安装元数据为准。按用户指定的发布版本或wheel安装，不把其他版本的行为当成本指南依据。离线安装须事先备齐依赖。
+
+`dependency_missing` 表示运行环境缺少 CAN 依赖，不是信号绑定内容错误；按错误中的本地 wheel 安装命令修复。即使全部信号元数据已经手填、静态校验通过，实际运行仍需要相应读取/解码依赖。
+
+## 我该读哪几份文件？
+
+第一次使用时先读[从输入到结果](workflow.md)，决定走单次计划、预设还是批量。
+
+查询任务后，先阅读返回记录中`references`列出的资料，再按`example`找到完整配置。引用相对于本语言README所在目录；JSON地址中`#`后的部分是规范节点路径，需同时查看该节点。
+
+先按计算含义选任务，不只匹配“能量”一词：
+
+|用户要的结果|任务与入口|
+|---|---|
+|自定义分析算子|`HOST_EXTENSION`；[注册接口](../Current/public-api/ExtensionRegistry.md)及任务对应的宿主脚本。|
+|聚合计算结果、配对延迟或统计事件/片段数量|`POWER_STATISTICS`；[统计与分组示例](../Current/examples/power-statistics.yaml)。|
+|一维标定查表|`CALIBRATION`；[查表配置示例](../Current/examples/lookup-power.yaml)。|
+|使用通用分析逐消息累计，包括需要贡献明细的任务|`MESSAGE_ENERGY`，使用通用`run`；[最小完整配置](../Current/examples/message-minimal.yaml)。|
+|条件持续超过门槛后，对整个合格区间积分|`CONDITION_ENERGY`，使用通用`run`或`run_analysis.py`。|
+|独立ASC/BLF中，每条目标帧用当帧全部输入计算固定周期贡献|高性能积分器（同帧逐报文累计）的`FAST_MESSAGE_ENERGY`，使用`fast validate/explain/run`。|
+|上一类独立文件按同模板并行，并求可比指标的总量|`FAST_TEMPLATE_TOTAL`，使用`fast batch --total`；[完整批量配置](../Current/examples/fast/batch.yaml)。|
+
+`run_analysis.py`运行通用分析，不会自动切换到fast。fast任务须采用各自索引中的命令；批量配置的根版本是`batch_version: 1`，其引用的分析配置另有`config_version`。
+
+1. 从 [任务索引](tasks.json) 找中文需求，只读命中条目的范例、适用条件和相关字段。先用 BLF/ASC＋DBC 场景；已解码信号表用 CSV，不需要 DBC。不要把别的发布版的配置或内部函数混进来。
+2. 写分析配置，使用 YAML 或 JSON，分析使用整数 `config_version: 4`。范例是完整文件；保留 ../Current/examples/data 相对位置。示例工程数值只适用于合成输入。缺真实时间基准、工程阈值、编码、单位或方向依据时，指出哪项缺失以及它会改变什么结果。
+3. 写 Python，查 [公开 API 索引](../Current/public-api.json)，再读对应单个 API 文件。文件用 load_analysis_plan，已展开字典用 AnalysisPlan.from_dict。预设构建得到 PlanFragment，不能直接交给 run。批量返回时逐任务核对状态。
+4. 配置加载 → 检查声明 → 查看依赖 → 运行 → 写出结果。可用命令见下方；Python方式见 [完整调用](run_analysis.py)。报告实际输入、单位、边界、质量和未验证项。计算返回不代表发布完成。
+
+## 一个从输入到结果的任务
+
+需要具体参数时，用标准 Python 在本README所在目录查询，不用读取整份规范：
+
+```text
+python lookup.py task 持续
+python lookup.py api AnalysisRunner
+python lookup.py field valid_for --schema analysis
+python lookup.py field source_type --schema analysis --branch can_asc
+```
+
+字段表给出原规范位置及分支。参见[高风险语义与真实诊断](semantics.md)及[完整字段参考](../Current/reference/configuration-schema.md)。条件必填、引用、时间单位和工程契约以完整规范及运行校验为准，不应把独立分片用作验证器。没有匹配项返回退出码1；先查正确的版本、名称或分支，不自动猜同义字段。
+
+在这份资料的目录运行（Windows/Python 3.12，已安装项目默认运行依赖）：
+
+```text
+python -m chronaxis config init --list
+python -m chronaxis validate ../Current/examples/conditional-energy.yaml --format json
+python -m chronaxis explain ../Current/examples/conditional-energy.yaml --format json
+python run_analysis.py ../Current/examples/conditional-energy.yaml result-energy
+```
+
+这个例子连续读取两卷ASC，用DBC解码状态、电流和电压，要求`state == 0x2 and current >= 10`连续严格超过60秒，再对整个合格事件积分。恰好60秒的第一段被排除；第二段跨越分卷，实际区间为[61,122)秒，结果4000×61/3600000＝0.06777777777777777kWh。默认从条件开始时刻积分，包括最初60秒；`confirmed_ns=121000000001`表示严格超过60秒的确认时刻，不是积分起点。完整配置位于任务`CONDITION_ENERGY`；预设`CHARGE`采用不同电流比较时，不能替代这个任务。
+
+结果目录可以重复使用；本次结果文件统一增加时间后缀。默认readable_csv在`事件结果_<本次时间>.csv`同一行给出精确秒起止和energy_kwh（kWh），先检查每项指标的状态和说明；从CLI返回的manifest或API返回的manifest_path读取清单，再从outputs找到本次实际文件。原程序交换格式须显式设置outputs.tables为csv或jsonl，才按parent_id关联原表；CLI与清单中的`analysis_outcome`区分无观测、未知、条件未成立、时长不足和已有事件。没有事件不等于能量为0。换成自己的数据时按实际DBC替换路径、ID、信号和条件；已解码信号表仍可选`CSV`任务，不应用合成阈值替用户决定生产参数。[查看教学示例的实际结果表](../Current/examples/results/conditional-energy-yaml/事件结果.csv)。
+
+分析命令和配置解释只证明声明和执行路径；加载按需可读 DBC 元数据、展开来源目录，不扫描业务记录。真实运行、输出和关闭完成后才报告成功。独立样例不能证明其他设备具有相同含义。

chronaxis-0.1.0.dev2/Docs/AI/en/README.md

@@ -0,0 +1,92 @@
+<a id="用-ai-编写-chronaxis-分析"></a>
+# Use AI to write a Chronaxis analysis
+
+Start with this README, select an example from the [task index](tasks.json), and read only the material needed for the task. Reading the guide in a source checkout requires no installation, generated files, or ZIP export; keep the repository layout intact. The standalone documentation ZIP uses the same text with its own complete directory layout.
+
+Give the AI this README and the [documentation version](../../Current/documentation.json), then supply examples, API descriptions, or field references as needed. Relative commands use the directory containing this README unless noted otherwise; installed users can use the working-directory example below. ASC and DBC paths inside a configuration are relative to that configuration file. Running an analysis requires the matching Chronaxis version; check it with `python -c "from importlib.metadata import version; print(version('chronaxis'))"`. The installed package includes the guide as ordinary files. `python -m chronaxis guide --language en` prints this English README path without writing or extracting anything. Open it directly; source documentation is also directly readable. Version metadata and synthetic examples do not establish that private logs have been verified.
+
+<a id="安装chronaxis及默认运行依赖"></a>
+### Use the installed guide directly
+
+Run these PowerShell commands from your own working directory. They read the installed guide and example directly and put results in your working directory, without copying or modifying the installed material:
+
+```powershell
+$guide = Split-Path (python -m chronaxis guide)
+python "$guide/lookup.py" --language en task CONDITION_ENERGY
+python "$guide/run_analysis.py" "$guide/examples/conditional-energy.yaml" result-energy
+```
+
+The relative commands below illustrate a source or standalone guide directory. For installed examples, use full input paths and your own output directory as above.
+
+## Install Chronaxis and its default dependencies
+
+A normal installation includes the runtime dependencies for BLF, ASC, raw-message CSV, DBC decoding, decoded-signal CSV, and memory tasks. These Windows PowerShell commands create an environment and install version 0.1.0.dev2, matching this guide:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install "chronaxis==0.1.0.dev2"
+.\.venv\Scripts\python.exe -m pip check
+```
+
+For a local package, replace `"chronaxis==0.1.0.dev2"` with `".\chronaxis-0.1.0.dev2-py3-none-any.whl"` in the installation command.
+
+Use the same `.venv\Scripts\python.exe` for subsequent commands; activation is optional. This version declares and has been checked with `python-can==4.6.1`, `cantools==39.4.3`, and `natsort==8.4.0`, installed through the wheel's default dependencies. Do not install an arbitrary latest version to fix a missing module, or change signals, thresholds, or the DBC. Other dependency versions are not thereby verified; use the actual distribution's installation metadata. Prepare dependency wheels in advance for offline installation.
+
+`dependency_missing` means the environment lacks required CAN dependencies, not that a signal binding is wrong. Follow the local-wheel installation command in the error. Even if every signal's metadata is supplied manually and static validation passes, execution still needs the appropriate reading and decoding dependencies.
+
+<a id="我该读哪几份文件"></a>
+## Which files should I read?
+
+First read [from input to results](workflow.md) to choose a single analysis, preset, or independent batch.
+
+After querying a task, read the materials in its `references` list, then open the complete configuration named by `example`. Paths are relative to this language’s README directory. A fragment after `#` in a JSON reference identifies the schema node to read.
+
+Select by calculation meaning, rather than matching only the word “energy”:
+
+| Requested result | Task and entry point |
+|---|---|
+| Custom analysis operators | `HOST_EXTENSION`; [registry API](../../Current/en/public-api/ExtensionRegistry.md) and the task's host script. |
+| Aggregate calculation rows, sequence delays, event counts or segment counts | `POWER_STATISTICS`; [statistics and grouping example](../../Current/examples/power-statistics.yaml). |
+| One-dimensional calibration lookup | `CALIBRATION`; [lookup configuration](../../Current/examples/lookup-power.yaml). |
+| Accumulate target-message contributions through the general runner, including contribution details | `MESSAGE_ENERGY`, using general `run`; [complete minimal configuration](../../Current/examples/message-minimal.yaml). |
+| Integrate over each entire interval whose condition lasts beyond a threshold | `CONDITION_ENERGY`, using general `run` or `run_analysis.py`. |
+| In one independent ASC/BLF, calculate each target frame's fixed-period contribution using inputs from that frame | `FAST_MESSAGE_ENERGY` in the high-performance integrator (same-frame per-message accumulation), using `fast validate/explain/run`. |
+| Process the latter independent files from one template in parallel and total comparable metrics | `FAST_TEMPLATE_TOTAL`, using `fast batch --total`; see [complete batch configuration](../../Current/examples/fast/batch.yaml). |
+
+`run_analysis.py` runs a general analysis; it does not automatically select fast. Follow the task-specific commands for fast. Batch files use root `batch_version: 1`; their referenced analysis files separately declare `config_version`.
+
+1. Search the [task index](tasks.json) for the requested task. Read that entry's example, applicability, and related fields. Start with BLF/ASC plus DBC for CAN tasks. Decoded CSV tables do not need a DBC. Do not mix configuration or internal functions from another release.
+2. Write YAML or JSON using integer `config_version: 4`. Examples are complete files; preserve the layout under `../../Current/examples/data`. Their engineering values apply only to the synthetic inputs. If the real time basis, thresholds, encoding, units, or direction are missing, explain which fact is missing and how it changes the result.
+3. For Python, consult the [public API index](../../Current/en/public-api.json), then the individual API page. Use `load_analysis_plan` for files and `AnalysisPlan.from_dict` for expanded dictionaries. Preset construction returns a `PlanFragment`, which cannot be passed directly to `run`. Inspect every task status after a batch returns.
+4. Load the configuration, validate declarations, inspect dependencies, run, and write the output. Commands are below; the [complete Python call](../run_analysis.py) provides the executable path. Report actual inputs, units, boundaries, quality, and unverified parts. Returning from calculation is not the same as publishing results.
+
+<a id="一个从输入到结果的任务"></a>
+## A complete task
+
+Query the material with standard Python from this README's directory instead of reading the whole specification:
+
+```text
+python ../lookup.py --language en task energy
+python ../lookup.py --language en api AnalysisRunner
+python ../lookup.py --language en field valid_for --schema analysis
+python ../lookup.py --language en field source_type --schema analysis --branch can_asc
+```
+
+Field tables identify their specification location and branch. See [semantics and diagnostics](semantics.md) and the [complete field reference](../../Current/en/reference/configuration-schema.md). Conditional requirements, references, time units, and engineering requirements depend on the complete specification and runtime validation. Individual field extracts are not standalone validators. A query without matches exits with code 1: check the version, name, or branch instead of inventing an equivalent field.
+
+On Windows with Python 3.12 and the package's default runtime dependencies installed:
+
+```text
+python -m chronaxis config init --list
+python -m chronaxis validate ../../Current/examples/conditional-energy.yaml --format json
+python -m chronaxis explain ../../Current/examples/conditional-energy.yaml --format json
+python ../run_analysis.py ../../Current/examples/conditional-energy.yaml result-energy
+```
+
+This example reads two continuous ASC volumes and decodes state, current, and voltage with a DBC. It requires `state == 0x2 and current >= 10` for strictly more than 60 seconds, then integrates over the entire qualifying event. The first activity lasts exactly 60 seconds and is excluded. The second crosses the file boundary, covers `[61,122)` seconds, and gives `4000 × 61 / 3600000 = 0.06777777777777777 kWh`. Integration starts at condition onset by default, including the first 60 seconds. `confirmed_ns=121000000001` is the strict-duration confirmation time, not the integration start. Use task `CONDITION_ENERGY`; `CHARGE` is not a replacement when its current comparison differs.
+
+The output directory can be reused; this publication uses a common timestamp suffix. Default `readable_csv` output places exact-second boundaries and `energy_kwh（kWh）` on the same row in `事件结果_<run timestamp>.csv` (event results). Check each metric's status and explanation. Read the manifest path returned by the CLI or API, then use its `outputs` list to find this publication's files. To consume original interchange tables linked by `parent_id`, explicitly select `outputs.tables: csv` or `jsonl`. CLI and manifest `analysis_outcome` distinguish no observation, unknown conditions, conditions not met, insufficient duration, and detected events. No event does not mean zero energy. [View the actual teaching-example result table](../../Current/examples/results/conditional-energy-yaml/事件结果.csv).
+
+For your own data, replace paths, IDs, signals, and conditions using the actual DBC. Decoded tables can use task `CSV`. Do not treat synthetic thresholds as the user's production parameters.
+
+Validation and explanation establish declaration validity and supported execution paths. Loading may read DBC metadata or enumerate directories as needed, but it does not scan business records. Report success only after actual execution, publication, and cleanup finish. An independent example does not establish that another device has the same business meaning.

chronaxis-0.1.0.dev2/Docs/AI/en/semantics.md

@@ -0,0 +1,85 @@
+<a id="先决定什么能算再生成配置"></a>
+# Establish what can be calculated before generating configuration
+
+| Task | Facts to establish | How to decide |
+|---|---|---|
+| Identify inputs | BLF/ASC logs, DBC, channel, message, and signal; actual CSV headers and time units. | Joint analysis of different clocks needs a common origin, offset, or other explicit synchronization evidence. Both files starting at zero is insufficient. |
+| Bind names | Locate the original input field. `name` is its analysis name; `semantic_id` is optional business metadata. | If `BMS_I` is bound as `pack_current` with semantic ID `battery.current`, write `pack_current > 5`. A dotted semantic ID is not an object attribute. Require an explicit choice when multiple candidates match. |
+| Units and direction | Existing DBC conversion and input/target units; establish direction and measurement point when a charging/discharging interpretation needs them. | Version 4 infers conversion when both scale and offset are omitted: a DBC value of 2000 mA with unit: A becomes 2 A. Supplying either coefficient disables additional automatic conversion. sign_convention describes direction without changing values; same-unit scale=-1 is not a general sign-flip mechanism. |
+| State codes | The business meaning of each code. | Whether 2 means charging depends on the equipment. Preserve numeric types for a user-supplied comparison such as `state == 0x2`. Use Boolean/enumeration mappings only when true/false or named states are needed. Unknown mapping codes do not mean nonzero=true. Without definitions, identify the missing facts rather than claiming a production-ready charging detector. |
+| Validity | `valid_for` is a positive duration. An explicit value wins; otherwise use three times this signal's `period`, obtaining a DBC message period at runtime where applicable. Do not guess without a basis. Explicit null is not omission. | With an update at 0 and `period=100ms`, the value remains valid at 0.299 s and becomes unknown at 0.300 s. An invalid update at 0.2 s makes it unknown from 0.2 s. Validity does not set a sample rate or create records. |
+| Conditions and statistics | Requested range, observed range, selected data, and `partial_policy`. | A fully observed, known-false condition may yield zero conditional integral. Minimum/maximum/mean of an empty selection are null. No observations or all-unknown input must not become a normal zero. Explain partial values together with `status`, `reason`, and `quality`. |
+| Events and segments | Two activities can merge into one surrounding segment without making their gap an activity. | `segments.parent_event_ids` may reference several `events.event_id` values in the same run. Link calculations using `scope` and `parent_id`, not row number or rule name alone. |
+| Timing and output | Batch size changes execution chunks only. Unknown response differs from decidable timeout. Actual-time integration differs from per-message accumulation. | Inspect dependencies, intervals, output units, and requested ranges in `explain`. `coverage_status` exists only for applicable result types and thresholds; it is not a numerical coverage ratio. Do not invent a `coverage` field. |
+| Business presets | Charging, for example, needs `mode`/`current` and `voltage` when energy is requested. Direction, units, and measurement point must meet role requirements. | Missing facts or two matching candidates do not authorize choosing the first. Explicit bindings still undergo role validation. Example thresholds and codes do not transfer automatically to another vehicle. |
+
+<a id="从报告定位错误"></a>
+## Diagnose using actual reports
+
+Record the user's required signals, conditions, scope, and outputs first. Request JSON from `validate`. For a constructed plan, inspect `valid`, `execution_ready`, `errors`, `warnings`, and `capability_status`. For loading failure, iterate `errors`, even for one error; `blocked_checks` explains checks prevented by invalid dependencies. Each item provides available fields such as `code`, `source`, `path`, `line`, `column`, `message`, and `hint`. In `explain`, the validation report is under `validation`, with dependencies under `nodes` and `input_requirements`. Environment, I/O, or argument errors may produce only a nonzero exit code and stderr; missing JSON does not mean success.
+
+For example, string `config_version: "4"` is rejected. Change only that value to integer 4, preserve the calculation, and recheck. Do not remove a filter, extend validity, ignore unknown data, or reverse a sign to “fix” a diagnostic. If two correction rounds still fail, report the real error and unresolved facts rather than fabricate runnable output.
+
+```text
+python -m chronaxis config origins ../../Current/examples/analysis-imports.yaml --fields --format json
+python -m chronaxis config resolve ../../Current/examples/analysis-imports.yaml --defaults --format json
+python -m chronaxis validate ../../Current/examples/input-csv-minimal.yaml --format json
+python -m chronaxis explain ../../Current/examples/input-csv-minimal.yaml --format json
+```
+
+`origins` identifies the declaration supplying a field. `resolve` shows expanded configuration and defaults that can currently be determined; it must not invent a fixed period awaiting DBC lookup. `load_analysis_plan` resolves paths relative to the defining file; `AnalysisPlan.from_dict` takes an already expanded dictionary. Validation does not establish actual observation coverage, real units, or correct results. Deliver the version, inputs, key assumptions, checks actually performed, and unverified conditions.
+
+<a id="持续门槛与积分起点"></a>
+## Duration thresholds and integration starts
+
+For `condition_duration`, `minimum_duration: 60s` means reaching 60 seconds by default. For “more than 60 seconds,” add `duration_comparison: ">"`, not 60.1 seconds. Default `selection_origin: onset` includes the entire qualifying interval. Select `confirmed` only when the user asks to start after confirmation. An exactly 60-second activity produces an event in the default mode and no event in strict mode. Time precision is 1 ns. Actual-time strict comparison can confirm at threshold plus 1 ns; fixed/DBC mode waits for the next driving message that takes accumulated duration strictly past the threshold.
+
+<a id="资源不足时保留原任务"></a>
+## Preserve the task when resources are insufficient
+
+Sample minimum, maximum, and mean use chunked reductions within the shared memory budget; their result does not depend on chunk size. Do not add unrequested statistics for debugging. For a budget error, first inspect the named calculation, workspace, or read buffer instead of attributing every failure to machine RAM. If even the smallest statistical chunk does not fit, execution fails explicitly. Reducing read batches changes processing chunks, not conditions, validity, or retained input. Increase budgets only with an actual resource basis. Managed budget estimates and process RSS are different quantities.
+
+<a id="can通道连续文件与检查范围"></a>
+## CAN channels, continuous files, and check scope
+
+DBC mapping keys, explicit signal channels, per-message selectors, and raw-frame resampling channels all start at `1` in public configuration. DBC channel keys are positive-integer strings without leading zeros: write `"1"` for the first channel. Ordinary channel fields take the integer `1`; do not subtract one. A signal or selector can omit `channel` when its source has a single channel, which the program then selects. Keep channel values in the original log unchanged. For raw CSV, `reader.channel_origin` still describes whether the input file's channel column starts at `0` or `1`.
+
+Configuration paths are relative to the file containing that field, including shared definitions. Dictionary APIs use `base_dir`, defaulting to the current directory. `chronaxis explain PLAN --format json` shows plan information; `chronaxis config resolve PLAN --format json` shows expanded configuration. Files within one source are continuous in listed order, retaining candidate state across boundaries. Directory matching uses natural order. Sharing a folder does not prove sharing a session: use batch tasks for independent experiments, and do not invent offsets to concatenate them.
+
+ASC checks timestamp order only for required channels/IDs by default. The source's earliest and latest frame times are still collected during that same read. Required records moving backwards remain errors; full checks or raw-frame export require the whole source to be ordered. Do not add a separate full-file scan followed by automatic cleaning. A small difference of microseconds does not authorize changing the input.
+
+<a id="默认可读结果"></a>
+## Default readable results
+
+Omitting `outputs.tables` selects `readable_csv`: Chinese filenames and headers, exact seconds, and one row containing the metrics for each event or window. Use the CLI manifest path or API manifest_path, then discover actual files through the manifest outputs list; do not hard-code `events.csv` or `calculations.csv`. Explicit `outputs.tables: csv` or `jsonl` selects the original interchange format and integer nanoseconds. Only the selected table format is produced.
+
+Readable tables retain calculation names and units. Empty cells are not zero. Each metric independently reports `完整` (complete), `部分有效` (partial), or `无法确定` (indeterminate), with its reason. Inspect interval status separately from metric status. Global `has_unknown` does not invalidate a complete calculation within a known interval. For no events, inspect manifest `result_messages`; do not create a false zero-energy result. Preserve the original analysis time coordinates without inventing dates or shifting to zero. Do not duplicate seconds and nanoseconds. Python iterators such as `iter_events` and `iter_calculations` continue to return original typed rows.
+
+<a id="独立批量的进程数"></a>
+## Process count for independent batch tasks
+
+Root-level batch `process_count` is a positive integer, default 1, limiting analysis worker processes. It excludes the scheduler and CAN reader subprocesses. `run_batch(plan, output, process_count=4)` and CLI `--process-count 4` override it. Only the Python API accepts `None` to inherit the plan; configuration rejects null and Booleans. Call from a Python script inside `if __name__ == "__main__":`. Ordinary `AnalysisRunner` has no such parameter. Continuous `paths` in one session are not split into independent processes.
+
+Each task has its own budgets and output. Cancellation prevents tasks that have not started; in-flight tasks finish and close. `report.close()` can retry remote cleanup. Unstarted tasks and worker crashes are not successes. Legacy `workers`, `max_workers`, and `--workers` are rejected.
+
+<a id="迁移数值与后端核对"></a>
+## Numbers and backend comparisons
+
+Both backends must agree on event boundaries, statuses, and diagnostics. Compare floating-point metrics using their unit and agreed error tolerance, without requiring bitwise equality or attributing event/quality differences to rounding.
+
+Ordinary scalar calculations, including sample statistics, can return `coverage_status` when `minimum_coverage > 0`. It records the threshold decision, not a ratio, and does not change the equal weighting of `sample_mean`. Initial-edge `emit_initial` concerns the first known state, not an arbitrary first `True` anywhere in the analysis. A requested endpoint can produce a point event only when it is actually observed and satisfies the rule.
+
+## Choose a version 4 expression
+
+Write a unit-bearing constant as `quantity(500,'mV')` (0.5 V). Use `where` to select between branches: missing data on the unselected branch does not invalidate the result. For a calibration curve, use `lookup(voltage,'curve')` after checking both units and the points. Codes 7 and 9 can have the same label; request `enum_code(mode)` only if the distinction matters. In the calibration example, 3, 7 and 3 V map to 10, 30 and 10 W, giving a sample mean of about 16.67 W. Analysis configurations accept only integer version 4.
+
+In version 4, a signal's `unit` specifies its target unit. Raw CAN input units can come from the DBC; for a decoded table, use `conversion.input_unit` when the input unit differs. For mA input and A output, omit both `conversion.scale` and `conversion.offset` to infer the conversion. If either coefficient is supplied, the other takes its existing identity default and the complete conversion is checked; DBC scaling is not applied again. Relabelling a result without converting its value is not a valid conversion. Task `UNITS` demonstrates conversion between input and target units; do not repeat a multiplier that can be inferred.
+## Statistics: power variation and result populations
+
+Establish what counts as one observation for this question. It can be one real power update, valid time held, a load, a final segment, or an already computed row. Sample statistics weight selected valid updates equally. Time statistics weight valid duration with known-true selection. Sample variance and standard deviation accept `ddof: 0` or 1, time versions accept only 0, and RMS omits `ddof`. Object counts reference named rules or windows. A known empty set can yield zero, while unobserved periods need an explicit status. Quantile takes `q`; median omits it. Exact interior quantiles use the run's memory budget.
+
+In the bench task, P95 of five individual readings is 18 W. P95 of the two load means [10,20] W is 19.5 W. For a question about individual loads, calculate one value per activity and reference its calculation `value` from `aggregations`. For successful response delays, use `delay_ns` from the named `sequence`. Report candidates, inclusions, definition and quality exclusions, admitted partials and population discovery status. Exclude partial calculations by default. Use `include_partial: true` only if the requested population admits those values. Task ID: `POWER_STATISTICS`. [Runnable ASC/DBC example](../../Current/examples/power-statistics.yaml)
+
+## Temporal transforms and host extensions
+
+Ask for the actual timebase, TTL, output grid and clock policy. At a fixed/DBC grid tick between two real driver frames, wait for the later frame to determine fractional period weights and keep the original grid timestamp. adjacent_rate uses real value updates and actual max_gap. window_rate compares both boundary values; sample_fit_slope uses only real samples. Default strict warm-up returns unknown. Preserve partial quality in downstream results. For a registered operation ask for its host program, fixed ports, version and backend; run the host script with the same registry at plan load and execution. A YAML module path is never a registration mechanism.