chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/api/time_deltas_reference.md

@@ -0,0 +1,37 @@
+# time_deltas_reference
+
+推荐导入：`from chronaxis import time_deltas_reference`
+
+<a id="api-time_deltas_reference"></a>
+## `time_deltas_reference`
+
+计算非递减整数时间的相邻跨度，允许同时间不同样本。
+
+```python
+time_deltas_reference(times: Sequence[int]) -> tuple[int, ...]
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`times`|Sequence[int]|是|无|位置或关键字。来源顺序的int64纳秒，允许重复坐标。|
+
+### 返回说明
+
+tuple[int,...]: 长度max(N-1,0)的非负int64跨度。
+
+### 异常说明
+
+TypeError/ValueError: 非整数或来源内时间回退。
+    TimeOverflowError: 输入或跨度超界，即使两端各自合法。
+
+本函数直接报告的具体错误：
+
+- `ValueError`：时间序列必须非递减。
+
+### 副作用说明
+
+无；Python整数参考不调用NumPy内核，也不排序或去重。
+
+返回类型：tuple[int, ...]。

chronaxis/guide/api/validate_analysis_plan.md

@@ -0,0 +1,38 @@
+# validate_analysis_plan
+
+推荐导入：`from chronaxis import validate_analysis_plan`
+
+<a id="api-validate_analysis_plan"></a>
+## `validate_analysis_plan`
+
+报告静态配置有效性及当前读取、执行和发布能力限制。
+
+```python
+validate_analysis_plan(plan: AnalysisPlan) -> ValidationReport
+```
+
+### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|是|无|位置或关键字。提供已校验的AnalysisPlan，通过load_analysis_plan("analysis.yaml")取得，或用AnalysisPlan.from_dict(config)从Python字典建立；这里不接收YAML文件名字符串。|
+
+### 返回说明
+
+ValidationReport。合法已接入计划valid为True且errors为空；warnings保留尚未核实的
+    字段、观测范围和单位状态，capability_status记录当前接入情况。
+    execution_ready随静态能力错误为False或True，不表示已读取或保证实际RAM。
+
+### 异常说明
+
+TypeError: 输入不是AnalysisPlan；配置构建错误应由构建入口先报告。
+
+本函数直接报告的具体错误：
+
+- `TypeError`：validate_analysis_plan需要AnalysisPlan。
+
+### 副作用说明
+
+无来源读取，不重新核实CSV、BLF/DBC、实际字段或物理测量含义。
+
+返回类型：ValidationReport。

chronaxis/guide/en/README.md

@@ -0,0 +1,74 @@
+<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](../manifest.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
+
+Installing the local wheel installs the runtime dependencies for BLF, ASC, raw-message CSV, DBC decoding, decoded-signal CSV, and memory tasks. No `[can]` suffix is required. On Windows PowerShell, replace the wheel path with the actual file:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install ".\chronaxis-0.1.0.dev0-py3-none-any.whl"
+.\.venv\Scripts\python.exe -m pip check
+```
+
+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.
+
+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: 3`. Examples are complete files; preserve the layout under `../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](api/index.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](fields/index.json). 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 ../examples/conditional-energy.yaml --format json
+python -m chronaxis explain ../examples/conditional-energy.yaml --format json
+python ../run_analysis.py ../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 must be new. Default `readable_csv` output places exact-second boundaries and `energy_kwh（kWh）` on the same row in `事件结果.csv` (event results). Check each metric's status and explanation. Discover actual file paths through `run_manifest.json.outputs`. 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.
+
+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/guide/en/api/AnalysisError.md

@@ -0,0 +1,14 @@
+# AnalysisError
+
+Import: `from chronaxis import AnalysisError`
+
+<a id="api-AnalysisError"></a>
+## `AnalysisError`
+
+Indicates analysis or result-publication failure. The exception itself does not promise that existing output was rolled back.
+
+```python
+class AnalysisError(RuntimeError)
+```
+
+Base class: `RuntimeError`. No additional fields are declared by this class.

chronaxis/guide/en/api/AnalysisPlan.md

@@ -0,0 +1,93 @@
+# AnalysisPlan
+
+Import: `from chronaxis import AnalysisPlan`
+
+<a id="api-AnalysisPlan"></a>
+## `AnalysisPlan`
+
+Stores one session's analysis configuration and the objects produced by static checking.
+
+Construct through from_dict or load_analysis_plan. The plan stores input sources, signals, derived calculations, condition rules, windows, and metrics. Instance fields cannot be reassigned. Configuration and free-form metadata are independent read-only snapshots, not references to mutable caller dictionaries or lists.
+
+bindings describes which signal comes from which source; derived_expressions contains checked expression structures. Neither proves that real data has been read or that the plan is ready to execute. execution and outputs store declarations; construction does not run calculations or publish files.
+
+identity is computed from configuration and source-location declarations to distinguish plans. It does not verify CSV contents, actual columns, memory usage, or analysis results. Bindings and declarations from separate constructions are independent.
+
+```python
+AnalysisPlan(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
+```
+
+### Properties and data fields
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`config_version`|int|Yes|None|Loaded structure version, currently integer 3. Normally construct the complete plan through load_analysis_plan(path) or AnalysisPlan.from_dict(config), rather than assembling fields manually.|
+|`dataset`|DatasetPlan|Yes|None|Analysis entity, session, and requested time range.|
+|`sources`|tuple[SourcePlan, ...]|Yes|None|Parsed source configurations in declaration order.|
+|`signals`|tuple[SignalPlan, ...]|Yes|None|Original fields, signal names, types, units, and validity declarations.|
+|`derived`|tuple[DerivedPlan, ...]|Yes|None|New signals calculated from existing ones, such as power, with their metadata.|
+|`rules`|tuple[RulePlan, ...]|Yes|None|Checked Boolean conditions and temporal rules.|
+|`windows`|tuple[WindowPlan, ...]|Yes|None|Checked windows around activities or points and their referenced rules.|
+|`calculations`|tuple[CalculationPlan, ...]|Yes|None|Metrics with scope, calculation semantics, units, and missing-data policies.|
+|`presets`|tuple[PresetSpec, ...]|Yes|None|Original frozen v1 preset declarations, retaining generation parameters.|
+|`preset_bindings`|tupletuple[[RoleBinding, ...], ...]|Yes|None|Role-to-signal bindings produced at loading. The outer tuple follows plan.presets order. Each inner RoleBinding stores contract (role requirements), definition (selected original signal), and resolution (explicit or semantic_unique). With no presets this is (). Pair using zip(plan.presets, plan.preset_bindings), then read attributes such as binding.definition.name; see the example.|
+|`execution`|ExecutionPlan|Yes|None|Calculation backend, batch size, and declared resource budgets; execution has not occurred.|
+|`outputs`|OutputPlan|Yes|None|Result-table and manifest format declarations; files have not been written.|
+|`bindings`|DeclarationBindings|Yes|None|Declared name-to-source relationships, without actual signal values.|
+|`derived_expressions`|tuple[StaticExpression, ...]|Yes|None|Checked derived-expression structures, with cycles rejected.|
+|`metadata`|Mapping|Yes|None|Caller-supplied read-only notes that do not change calculation rules.|
+|`raw_config`|Mapping|Yes|None|Internal read-only snapshot from parsing, not original user text. Omitted fields are not necessarily all expanded, and fields may use internal parsed forms. Use config resolve for editable current public configuration.|
+|`base_dir`|Path|Yes|None|Absolute base directory for relative source paths.|
+|`identity`|str|Yes|None|SHA-256 identity of configuration and source-location declarations, not file contents.|
+|`message_calculations`|tuple[MessageCalculationPlan, ...]|No|()|Parsed per-message calculation tuple; () means none. Executed separately from ordinary calculations.|
+|`sequences`|tuple[SequencePlan, ...]|No|()|Parsed request/response pairing tuple; () means no pairing.|
+|`intervals`|'IntervalPlan &#124; None'|No|None|Finite interval declaration for the current record stream.|
+|`diagnostics`|'DiagnosticPlan &#124; None'|No|None|Separate requests for tracing, integrity checks, and retained work files.|
+
+### Example
+
+```python
+from chronaxis import load_analysis_plan
+
+# Run from the guide's en directory; this file defines the required sources, signals, and preset.
+plan = load_analysis_plan("../examples/preset-charge-minimal.yaml")
+for preset, bindings in zip(plan.presets, plan.preset_bindings):
+    for binding in bindings:
+        print(preset.id, binding.contract.role,
+              binding.definition.name, binding.resolution)
+# demo_preset mode mode explicit
+# demo_preset current current explicit
+```
+
+
+<a id="api-AnalysisPlan-from_dict"></a>
+### `AnalysisPlan.from_dict`
+
+Copies the configuration dictionary and checks version 3 static requirements. Execution capabilities are validated separately.
+
+```python
+AnalysisPlan.from_dict(config: dict, *, base_dir: Path | str | None=None) -> 'AnalysisPlan'
+```
+
+Decorators: `classmethod`, `public_errors`.
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`config`|dict[str, object]|Yes|None|Positional or keyword. Current public analysis dictionary including config_version=3, dataset, sources, and signals. Unexpanded imports are rejected. Directory declarations enumerate filenames and omitted CAN metadata may read DBC; business records are not read. See Configuration fields.|
+|`base_dir`|Path &#124; str &#124; None|No|None|Keyword-only. Base directory for relative source paths. None uses the current working directory; a Path or string becomes an absolute path.|
+
+#### Returns
+
+AnalysisPlan containing statically checked sources, signals, and calculation nodes. raw_config and metadata are independent read-only snapshots. Plan construction does not read analysis data.
+
+#### Raises
+
+PlanValidationError for invalid fields/versions, name conflicts, expression/reference errors, invalid input models, or requested capabilities without an execution path. The error retains the configuration location. OSError can propagate from obtaining the working directory or converting paths.
+
+#### Processing
+
+Checks the current public configuration, expands nodes, and parses sources/signals. Directory declarations enumerate filenames; missing CAN metadata is filled from the DBC. References, types, and units are then checked before constructing an independent plan. No business records are read and no analysis is run.
+
+Return type: 'AnalysisPlan'。

chronaxis/guide/en/api/AnalysisResult.md

@@ -0,0 +1,398 @@
+# AnalysisResult
+
+Import: `from chronaxis import AnalysisResult`
+
+<a id="api-AnalysisResult"></a>
+## `AnalysisResult`
+
+Result of one successful analysis, normally returned by AnalysisRunner.run. Read rows through iter_*, publish through write, and release resources through close or with. Constructor arguments transfer internal staging ownership; ordinary application callers should not construct this object manually.
+
+```python
+AnalysisResult(spool: chronaxis.results.spool.ResultSpool, metadata: chronaxis.results.manifest.RunMetadata, table_format: str = 'csv', *, artifact_exports=None, owned_work=None)
+```
+
+
+
+<a id="api-AnalysisResult-__init__"></a>
+### `AnalysisResult.__init__`
+
+Takes ownership of finalized staging and records analysis_complete: computation is finished and results can be read. write creates the final output directory separately.
+
+```python
+AnalysisResult.__init__(spool: ResultSpool, metadata: RunMetadata, table_format: str='csv', *, artifact_exports=None, owned_work=None)
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`spool`|ResultSpool|Yes|None|Positional or keyword. Takes ownership of an internally finalized and sorted ResultSpool, then becomes responsible for releasing it. Ordinary callers obtain the result through AnalysisRunner.run(...) instead of constructing staging.|
+|`metadata`|RunMetadata|Yes|None|Positional or keyword. This run's configuration, actual input, calculation mode, and observations, written into the published manifest.|
+|`table_format`|str|No|'csv'|Positional or keyword. "readable_csv" writes Chinese readable tables; "csv" preserves exchange CSV fields; "jsonl" writes complete JSON records per line. This low-level constructor defaults to csv; AnalysisRunner follows the plan default readable_csv.|
+|`artifact_exports`|ArtifactExportStore &#124; None|No|None|Keyword-only. Optional store for signal-table and frame export files. The result owns closure after successful transfer.|
+|`owned_work`|tuple[Path, tuple] &#124; None|No|None|Keyword-only. Private root path and creation-time directory identity; must be the spool's direct parent. None transfers only the spool directory.|
+
+#### Returns
+
+None; initializes the instance.
+
+#### Raises
+
+Invalid models/table formats are rejected. Budget, staging, or internal-manifest failures can raise AnalysisError with their cause. If construction fails with cleanup pending, the exception's analysis_result_cleanup_owner provides a close retry. Ordinary callers should use AnalysisRunner.run instead of transferring spool ownership themselves.
+
+
+<a id="api-AnalysisResult-run_manifest"></a>
+### `AnalysisResult.run_manifest`
+
+Returns a snapshot of current state. See manifest_path for publication-failure diagnostics.
+
+```python
+AnalysisResult.run_manifest: dict
+```
+
+Decorators: `property`.
+
+Read this as a property, without calling parentheses.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Small independent dict.
+
+#### Raises
+
+Diagnostics remain available after close; no files are read.
+
+Return type: dict。
+
+
+<a id="api-AnalysisResult-iter_events"></a>
+### `AnalysisResult.iter_events`
+
+Creates an independent event stream without materializing every row.
+
+```python
+AnalysisResult.iter_events() -> Iterator[SummaryEventRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Closable iterator yielding SummaryEventRow. Close it in try/finally. The enclosing AnalysisResult supports with; the cursor itself does not.
+
+#### Raises
+
+ResultClosedError if the result is closed or closing, preventing cursor creation or continued reading. BudgetExceededError if a cursor budget cannot be reserved. OSError if staging reads fail at creation or iteration. ResultFormatError if a row format, type, or length is invalid. Close the cursor; do not interpret read failure as empty results.
+
+Return type: Iterator[SummaryEventRow]。
+
+
+<a id="api-AnalysisResult-iter_sequences"></a>
+### `AnalysisResult.iter_sequences`
+
+Streams pairing rows; without configured pairing, returns an empty closable cursor.
+
+```python
+AnalysisResult.iter_sequences() -> Iterator[SummarySequenceRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Closable iterator yielding SummarySequenceRow. Close it in try/finally. The enclosing AnalysisResult supports with; the cursor itself does not.
+
+#### Raises
+
+ResultClosedError if the result is closed or closing, preventing cursor creation or continued reading. BudgetExceededError if a cursor budget cannot be reserved. OSError if staging reads fail at creation or iteration. ResultFormatError if a row format, type, or length is invalid. Close the cursor; do not interpret read failure as empty results.
+
+Return type: Iterator[SummarySequenceRow]。
+
+
+<a id="api-AnalysisResult-iter_segments"></a>
+### `AnalysisResult.iter_segments`
+
+Creates an independent segment stream retaining all parent-event links.
+
+```python
+AnalysisResult.iter_segments() -> Iterator[SummarySegmentRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Closable iterator yielding SummarySegmentRow. Close it in try/finally. The enclosing AnalysisResult supports with; the cursor itself does not.
+
+#### Raises
+
+ResultClosedError if the result is closed or closing, preventing cursor creation or continued reading. BudgetExceededError if a cursor budget cannot be reserved. OSError if staging reads fail at creation or iteration. ResultFormatError if a row format, type, or length is invalid. Close the cursor; do not interpret read failure as empty results.
+
+Return type: Iterator[SummarySegmentRow]。
+
+
+<a id="api-AnalysisResult-iter_calculations"></a>
+### `AnalysisResult.iter_calculations`
+
+Streams calculation summaries. Use scope to distinguish session, event, and segment, and read value, unit, status, reason, and quality together. Read select samples through iter_selections.
+
+```python
+AnalysisResult.iter_calculations() -> Iterator[SummaryCalculationRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Closable iterator yielding SummaryCalculationRow. Applicable time calculations with minimum_coverage > 0 yield SummaryCoverageCalculationRow with coverage_status. Close the cursor in try/finally; the cursor does not support with.
+
+#### Raises
+
+ResultClosedError if the result is closed or closing, preventing cursor creation or continued reading. BudgetExceededError if a cursor budget cannot be reserved. OSError if staging reads fail at creation or iteration. ResultFormatError if a row format, type, or length is invalid. Close the cursor; do not interpret read failure as empty results.
+
+Return type: Iterator[SummaryCalculationRow]。
+
+
+<a id="api-AnalysisResult-iter_contributions"></a>
+### `AnalysisResult.iter_contributions`
+
+Streams actual contributions and skipped evaluations, retaining original sequence and evaluation sequence separately.
+
+```python
+AnalysisResult.iter_contributions() -> Iterator[SummaryContributionRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Independent budgeted cursor yielding SummaryContributionRow.
+
+#### Raises
+
+ContributionsUnavailableError if outputs.contributions did not request full; change the plan and rerun to obtain details. ResultClosedError if closed. Budget, format, or I/O failures during staged reading retain their exception chains. The input decoder is not rerun.
+
+Return type: Iterator[SummaryContributionRow]。
+
+
+<a id="api-AnalysisResult-iter_selections"></a>
+### `AnalysisResult.iter_selections`
+
+Reads explicitly requested actual sample-selection rows.
+
+```python
+AnalysisResult.iter_selections() -> Iterator[SummarySelectionRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Budgeted cursor, empty when selection was not requested.
+
+#### Raises
+
+ResultClosedError if the result is closed or closing, preventing cursor creation or continued reading. BudgetExceededError if a cursor budget cannot be reserved. OSError if staging reads fail at creation or iteration. ResultFormatError if a row format, type, or length is invalid. Close the cursor; do not interpret read failure as empty results.
+
+Return type: Iterator[SummarySelectionRow]。
+
+
+<a id="api-AnalysisResult-iter_input_trace"></a>
+### `AnalysisResult.iter_input_trace`
+
+Reads explicitly requested traces of required inputs.
+
+```python
+AnalysisResult.iter_input_trace() -> Iterator[SummaryInputRow]
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Closable cursor yielding SummaryInputRow.
+
+#### Raises
+
+ResultClosedError if closed. AnalysisError if input trace was not generated; enable diagnostics.trace and rerun. Iteration may propagate ResultFormatError, BudgetExceededError, and OSError.
+
+Return type: Iterator[SummaryInputRow]。
+
+
+<a id="api-AnalysisResult-contributions_available"></a>
+### `AnalysisResult.contributions_available`
+
+Indicates whether per-message contributions can be queried, distinguishing unavailable details from an available empty table.
+
+```python
+AnalysisResult.contributions_available: bool
+```
+
+Decorators: `property`.
+
+Read this as a property, without calling parentheses.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+bool. With no per-message metrics configured, the original empty-cursor behavior remains available by default.
+
+#### Raises
+
+None. This fixed run fact remains readable after close, but no new cursor can be created.
+
+Return type: bool。
+
+
+<a id="api-AnalysisResult-write"></a>
+### `AnalysisResult.write`
+
+Writes staged results to a new directory. After every file is complete, records completed and renames the temporary directory to the final destination. Existing targets are not overwritten.
+
+```python
+AnalysisResult.write(output_dir: str | Path) -> OutputManifest
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`output_dir`|str &#124; Path|Yes|None|Positional or keyword. New result directory as str or Path, e.g. Path("results/run_01"). Existing destinations are rejected. Returns OutputManifest on completion; the result still needs closing.|
+
+#### Returns
+
+OutputManifest after successful publication.
+
+#### Raises
+
+ResultClosedError if closed or closing. AnalysisError for an existing target, a target inside the owned work directory to be cleaned, unsupported safe publication, or budget/format/write failures. __cause__ retains the original error. Correct the destination/environment and retry to another new directory without rereading input.
+
+#### Side effects
+
+Publishes to a new output directory without overwriting an existing one. On failure, retain_work determines whether temporary publication files are retained. Inspect the exception and run_manifest for diagnostics.
+
+Return type: OutputManifest。
+
+
+<a id="api-AnalysisResult-close"></a>
+### `AnalysisResult.close`
+
+Closes cursors and releases resources. By default, removes temporary data owned by this run; retain_work=True retains it. Original inputs and published output remain.
+
+```python
+AnalysisResult.close() -> None
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+None. Repeated calls are allowed; retry any cleanup left incomplete after a failure.
+
+#### Raises
+
+Attempts to close every acquired resource. If file-handle closure, staging cleanup, or budget release fails, raises the first error with later errors as additional diagnostics. Release any obstruction and retry close. Do not merely catch the exception and discard the result object.
+
+Return type: None。
+
+
+<a id="api-AnalysisResult-__enter__"></a>
+### `AnalysisResult.__enter__`
+
+Enters the result context without rereading input.
+
+```python
+AnalysisResult.__enter__() -> 'AnalysisResult'
+```
+
+Parameters: no explicit arguments.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+Returns this same object; subsequent iteration and the with block use that object.
+
+#### Raises
+
+ResultClosedError if already closed.
+
+Return type: 'AnalysisResult'。
+
+
+<a id="api-AnalysisResult-__exit__"></a>
+### `AnalysisResult.__exit__`
+
+Releases resources on context exit while preserving the original analysis/application exception.
+
+```python
+AnalysisResult.__exit__(exc_type, exc_value, traceback)
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`exc_type`|type[BaseException] &#124; None|Yes|None|Positional or keyword. Exception type raised inside with, or None on normal exit; supplied by Python.|
+|`exc_value`|BaseException &#124; None|Yes|None|Positional or keyword. Exception object from the with block, or None on normal exit; supplied by Python.|
+|`traceback`|TracebackType &#124; None|Yes|None|Positional or keyword. Exception traceback, or None on normal exit; supplied by Python for continued propagation.|
+
+#### Returns
+
+False; exceptions continue to propagate to the caller.
+
+#### Raises
+
+On a normal with exit, close failures propagate. If the block already raised an exception, that original exception is preserved and close failures are attached as diagnostics so the primary cause is not hidden.