pyattacker 0.3.1__tar.gz → 0.3.2__tar.gz

{pyattacker-0.3.1 → pyattacker-0.3.2}/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.2] — 2026-09-21
+
+### Changed
+
+* **Handoffs and forward/backward jumps are supported public features.** `Handoff.to`,
+  `Handoff.end`, `Handoff.rewind`, `Handoff.retry_all` and their `control` declarations now
+  follow the project's regular versioning policy, without a separate experimental tier.
+  Code documentation and both language editions use this status consistently, including
+  the companion payload-history guide. Explicit declarations, finite backward budgets,
+  atomic store capabilities, execution semantics and persisted identities remain unchanged.
+  Documentation links use the new headings; legacy anchors preserve published bookmarks.
+  Earlier release entries below describe their status at the time of release.
+
+### Added
+
+* **Experiment suites** (#68): reference existing configurations and schedule their inputs
+  round-robin through one Runner with shared global concurrency and explicit local pool bindings.
+  Stable Suite/member identities preserve original local keys and isolate checkpoints and metrics.
+* Optional `by_experiment` output directories alongside default `combined` storage, with a
+  persistent catalog, source-exhaustion state, selective resume and bounded child connections.
+  Directory-aware report/watch/serve/export provide cumulative and durable invocation views,
+  preserving historical failures, skips and execution timing after resume. Recovery finalizes
+  abandoned catalog runs as interrupted, freezing their elapsed time. Unselected member
+  databases remain untouched. Pool environment placeholders allow credential rotation;
+  reopening validates the persisted artifact backend.
+* `export --rows results`, `--by-experiment`, member-scoped reported metrics, and task context
+  experiment/output-directory fields. Split export filenames follow the selected row kind.
+  Single-store exports atomically replace completed files; admitted specs repair migrated repeats.
+* English and Chinese Suite guides and a runnable JSON example. Existing standalone path/ID
+  semantics remain unchanged; Suite mode explicitly rejects independent process shards/custom stores.
+
 ## [0.3.1] — 2026-09-19
 
 ### Added
@@ -45,7 +78,7 @@ All notable changes to this project are documented here. The format follows
   keeps the append-only history, and a store that has committed its first revisit records a `base` → `visits-v1`
   feature level (`store.feature_level()`, `StoreFeatureUnsupported`) so lineage-unaware writers are refused
   rather than silently mutating the wrong occurrence. See
-  [reference → advanced: backward traversal](docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits).
+  [reference → advanced: backward traversal](docs/reference.md#backward-traversal-rewind-retry-all-visits).
 
 * **Advanced feature: handoffs — a task can skip ahead, on the record (opt-in, experimental).** A task may
   return `Handoff.to(target, value)` to continue at a declared later station, or `Handoff.end(value)` to
@@ -68,9 +101,9 @@ All notable changes to this project are documented here. The format follows
   commit them atomically; both built-in backends can, and a store that cannot is refused up front with a
   `ConfigError` rather than silently writing a non-durable jump. Marked *experimental until 1.0*;
   the forward declaration excludes backward targets; joins and cross-pipeline jumps are not included. See
-  [`docs/design.md` §4.8](docs/design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental),
-  the [API reference](docs/reference.md#advanced-handoffs-opt-in) and
-  [tutorial step 15](docs/tutorial.md#step-15--advanced-skipping-stations-handoffs).
+  [`docs/design.md` §4.8](docs/design.md#48-handoffs--declared-forward-jumps-opt-in),
+  the [API reference](docs/reference.md#handoffs-opt-in) and
+  [tutorial step 15](docs/tutorial.md#step-15--skipping-stations-handoffs).
 
 ### Fixed
 
@@ -206,9 +239,9 @@ All notable changes to this project are documented here. The format follows
 
 * **The backward-traversal guide is merged into the tutorial and the reference.** `docs/backward.md` was a
   seventh document that a reader had to find before they could use the feature; its usage now lives where
-  the rest of the API does. [Tutorial step 16](docs/tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all)
+  the rest of the API does. [Tutorial step 16](docs/tutorial.md#step-16--regenerating-with-rewind-and-retry-all)
   keeps the rewind/retry-all walkthrough and a new step 17 builds an optional `HistoryArtifact` payload,
-  while [reference → advanced: backward traversal](docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits)
+  while [reference → advanced: backward traversal](docs/reference.md#backward-traversal-rewind-retry-all-visits)
   gains the `Handoff.rewind`/`Handoff.retry_all` signatures, the backward `control` keys, the visit and
   occurrence model, the budget and recovery rules, and the inspection surface; `HistoryArtifact` is
   documented next to the codecs it belongs to, and the store capability and compatibility/backup rules moved

{pyattacker-0.3.1 → pyattacker-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyattacker
-Version: 0.3.1
+Version: 0.3.2
 Summary: Artifact-centric, resumable async task orchestration: pipeline / task / resource pool.
 Project-URL: Homepage, https://github.com/Hazer-BJTU/pyattacker
 Project-URL: Repository, https://github.com/Hazer-BJTU/pyattacker
@@ -93,7 +93,7 @@ Five concepts, and that is the whole vocabulary:
 | Concept | Meaning | In one line |
 |---|---|---|
 | **artifact** | the persisted state of a task | content-addressed, **persisted as soon as it is produced** → checkpoint granularity = task |
-| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([advanced](#advanced-handoffs-opt-in)) |
+| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([handoffs](#handoffs-opt-in)) |
 | **pipeline** | the unit of completion | `fetch \| ask \| judge \| metrics` chained linearly, semantically independent of each other |
 | **resource** | a leasable external capability | one endpoint / one key; once pooled, it can be published and subscribed to concurrency-safely |
 | **algorithm** | the policy for acquiring resources | `wait`, `backoff`, `least_busy`, `failover`, `sticky`, `quota_aware`, `immediate` — orthogonal to "retry on failure" |
@@ -202,7 +202,7 @@ runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.y
 * Failed pipelines → continue from **the first task that produced no artifact**: **if task C died, only task C
   reruns when task B's checkpoint is durable**;
 * The seed artifact is persisted too → recovery **does not depend on the original dataset file**;
-* A pipeline that **handed off** ([advanced](#advanced-handoffs-opt-in)) resumes at the station it jumped to,
+* A pipeline that **handed off** ([handoffs](#handoffs-opt-in)) resumes at the station it jumped to,
   with the entry state the ledger recorded — the task that handed off is not re-run;
 * Changed a task's source code (`spec_digest` includes source digests) → treated as a new pipeline, so old
   results are not incorrectly reused. Factory parameters, fanout children, retry/algorithm policies and
@@ -213,10 +213,13 @@ rerun and old explicit keys conflict. Finish old runs with the old package, then
 [resume identity and idempotency reference](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#resume-identity)
 for migration guidance, dynamic functions and external configuration.
 
-## Advanced: Handoffs (Opt-In)
+<a id="advanced-handoffs-opt-in"></a>
 
-**Advanced tier: opt-in, changes the execution model, not needed for ordinary pipelines, experimental until
-1.0.** A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
+## Handoffs (Opt-In)
+
+**Handoffs, forward jumps and rewinds are supported control-flow features, enabled explicitly through `control`.**
+
+A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
 failure or hiding the branch inside one step. It **returns** a directive — `Handoff.to(target, value)` to
 continue at a declared later station, `Handoff.end(value)` to finish the pipeline right there:
 
@@ -296,16 +299,16 @@ with Runner(store=":memory:", concurrency=4) as runner:
   payloads provide explicit snapshots and restoration; ordinary dictionaries remain author-controlled.
   Visits and exact artifact occurrences retain history and make recovery safe. The APIs, budgets and
   recovery boundaries are in
-  [reference → advanced: backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits),
+  [reference → backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#backward-traversal-rewind-retry-all-visits),
   with working programs in
-  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all).
+  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--regenerating-with-rewind-and-retry-all).
 
-The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-handoffs-opt-in)),
+The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#handoffs-opt-in)),
 one declaration — `control={"edges": {...}}` for forward jumps, `control.rewind` / `control.retry_all` /
 `control.max_handoffs` for backward traversal — and one optional store capability; a custom store that cannot
 commit a handoff atomically is refused up front instead of writing a jump that would not survive a crash.
-Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--advanced-skipping-stations-handoffs).
-Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental).
+Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--skipping-stations-handoffs).
+Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-handoffs--declared-forward-jumps-opt-in).
 
 When a pipeline restarts from the seed, previous task rows and chain artifacts are reset atomically with the cursor/watermark;
 previous handoffs stay in its history but no longer act as
@@ -476,8 +479,8 @@ what they do not say.
 
 | Document | What is in it |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation and the advanced handoff/backward tiers — rewinds, retry-all and payload history included; each one executed by the test suite |
-| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including the advanced backward-traversal tier and `HistoryArtifact` |
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation, handoffs and backward traversal — rewinds, retry-all and payload history included; each one executed by the test suite |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including backward traversal and `HistoryArtifact` |
 | [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/cli.md) | every subcommand, every flag, exit codes, config reference |
 | [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md) | conceptual model, the six invariants, the lease contract, data model, tradeoffs |
 | [`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/benchmark.md) | the algorithm benchmark: what the scenarios assume, what the metrics mean, how to read the table |
@@ -510,7 +513,7 @@ These are design decisions, not missing features:
 * **Semantic reduction** — accuracy, pass@k, F1 and any cross-pipeline aggregation. Export the artifacts and
   compute it outside, or write a sink pipeline out of the primitives.
 * **DAG orchestration** — a pipeline is a linear chain; branch inside a task with `fanout`. The one
-  qualification is the opt-in [handoff](#advanced-handoffs-opt-in): it changes the traversal of
+  qualification is the opt-in [handoff](#handoffs-opt-in): it changes the traversal of
   the chain along declared edges, never its topology (no joins, no second entry point, no cross-pipeline
   jumps).
 * **A serving gateway** — the only HTTP surface is the read-only debug endpoint above.
@@ -521,16 +524,25 @@ every known tradeoff with its reason.
 
 ## Status
 
+**0.3.2 — experiment suites and supported control flow.** Independent experiments can share resource
+pools and global concurrency, with unified run/resume/report commands and optional per-experiment output
+directories. Durable run histories preserve earlier outcomes after resume. Handoffs, forward jumps,
+rewinds and retry-all are supported public features, enabled through explicit `control` declarations.
+See the [Suite guide](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/suites.md) and
+[release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21).
+
 **0.3.1 — application-reported live metrics.** Applications can publish values such as accuracy to the
 read-only monitoring dashboard through `Runner.report_metric()` or `TaskContext.report_metric()`. A completion
 callback receives committed pipeline results; the application owns the calculation. The dashboard and
 `watch` now follow one run consistently by default. See [`examples/live_metrics.py`](examples/live_metrics.py).
 
-**0.3.0 — advanced control flow (opt-in), and the documentation in Chinese.** Tasks can now
-[hand off](#advanced-handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
+**0.3.0 — control flow (opt-in), and the documentation in Chinese.** Tasks can now
+[hand off](#handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
 early, recorded in a durable ledger that recovery resumes from. It is opt-in and inert — a pipeline without a
-`control` block writes no new rows and keeps a byte-identical `spec_digest` — and marked experimental until
-1.0. Backward traversal now adds declared rewind and retry-all with visits and optional payload history. The
+`control` block writes no new rows and keeps a byte-identical `spec_digest`. Handoffs and backward traversal
+were experimental in 0.3.0 and became supported features in 0.3.2
+(see [0.3.2 release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)). Backward traversal adds declared rewind and retry-all with visits
+and optional payload history. The
 whole documentation set also ships in Simplified Chinese ([`README.zh-CN.md`](README.zh-CN.md),
 [`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)), kept in sync by CI. One
 rename to know about when upgrading: `MergedReport.events_total` is now `source_events_total`, because that
@@ -586,3 +598,7 @@ extracted and executed by `tests/test_tutorial.py`, so documentation that rots f
 ## License
 
 MIT — see [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE).
+
+## Experiment suites
+
+Combine existing configuration files under one Runner with shared resource pools and total concurrency. Optional per-experiment directories separate checkpoints, results and file artifacts. Suite reports include prior successes across resumes. See the [Suite guide](docs/suites.md) and [runnable configuration](examples/suites/suite.json).

{pyattacker-0.3.1 → pyattacker-0.3.2}/README.md

@@ -68,7 +68,7 @@ Five concepts, and that is the whole vocabulary:
 | Concept | Meaning | In one line |
 |---|---|---|
 | **artifact** | the persisted state of a task | content-addressed, **persisted as soon as it is produced** → checkpoint granularity = task |
-| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([advanced](#advanced-handoffs-opt-in)) |
+| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async — or `-> artifact \| Handoff`, to skip ahead ([handoffs](#handoffs-opt-in)) |
 | **pipeline** | the unit of completion | `fetch \| ask \| judge \| metrics` chained linearly, semantically independent of each other |
 | **resource** | a leasable external capability | one endpoint / one key; once pooled, it can be published and subscribed to concurrency-safely |
 | **algorithm** | the policy for acquiring resources | `wait`, `backoff`, `least_busy`, `failover`, `sticky`, `quota_aware`, `immediate` — orthogonal to "retry on failure" |
@@ -177,7 +177,7 @@ runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.y
 * Failed pipelines → continue from **the first task that produced no artifact**: **if task C died, only task C
   reruns when task B's checkpoint is durable**;
 * The seed artifact is persisted too → recovery **does not depend on the original dataset file**;
-* A pipeline that **handed off** ([advanced](#advanced-handoffs-opt-in)) resumes at the station it jumped to,
+* A pipeline that **handed off** ([handoffs](#handoffs-opt-in)) resumes at the station it jumped to,
   with the entry state the ledger recorded — the task that handed off is not re-run;
 * Changed a task's source code (`spec_digest` includes source digests) → treated as a new pipeline, so old
   results are not incorrectly reused. Factory parameters, fanout children, retry/algorithm policies and
@@ -188,10 +188,13 @@ rerun and old explicit keys conflict. Finish old runs with the old package, then
 [resume identity and idempotency reference](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#resume-identity)
 for migration guidance, dynamic functions and external configuration.
 
-## Advanced: Handoffs (Opt-In)
+<a id="advanced-handoffs-opt-in"></a>
 
-**Advanced tier: opt-in, changes the execution model, not needed for ordinary pipelines, experimental until
-1.0.** A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
+## Handoffs (Opt-In)
+
+**Handoffs, forward jumps and rewinds are supported control-flow features, enabled explicitly through `control`.**
+
+A task can decide that the rest of the chain no longer needs to run, and *say so* instead of inventing a
 failure or hiding the branch inside one step. It **returns** a directive — `Handoff.to(target, value)` to
 continue at a declared later station, `Handoff.end(value)` to finish the pipeline right there:
 
@@ -271,16 +274,16 @@ with Runner(store=":memory:", concurrency=4) as runner:
   payloads provide explicit snapshots and restoration; ordinary dictionaries remain author-controlled.
   Visits and exact artifact occurrences retain history and make recovery safe. The APIs, budgets and
   recovery boundaries are in
-  [reference → advanced: backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-backward-traversal-rewind-retry-all-visits),
+  [reference → backward traversal](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#backward-traversal-rewind-retry-all-visits),
   with working programs in
-  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all).
+  [tutorial steps 16–17](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-16--regenerating-with-rewind-and-retry-all).
 
-The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-handoffs-opt-in)),
+The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#handoffs-opt-in)),
 one declaration — `control={"edges": {...}}` for forward jumps, `control.rewind` / `control.retry_all` /
 `control.max_handoffs` for backward traversal — and one optional store capability; a custom store that cannot
 commit a handoff atomically is refused up front instead of writing a jump that would not survive a crash.
-Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--advanced-skipping-stations-handoffs).
-Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental).
+Walkthrough: [tutorial step 15](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md#step-15--skipping-stations-handoffs).
+Model and rules: [design §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md#48-handoffs--declared-forward-jumps-opt-in).
 
 When a pipeline restarts from the seed, previous task rows and chain artifacts are reset atomically with the cursor/watermark;
 previous handoffs stay in its history but no longer act as
@@ -451,8 +454,8 @@ what they do not say.
 
 | Document | What is in it |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation and the advanced handoff/backward tiers — rewinds, retry-all and payload history included; each one executed by the test suite |
-| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including the advanced backward-traversal tier and `HistoryArtifact` |
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | seventeen runnable steps, from "one task" to sharded evaluation, handoffs and backward traversal — rewinds, retry-all and payload history included; each one executed by the test suite |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples — including backward traversal and `HistoryArtifact` |
 | [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/cli.md) | every subcommand, every flag, exit codes, config reference |
 | [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md) | conceptual model, the six invariants, the lease contract, data model, tradeoffs |
 | [`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/benchmark.md) | the algorithm benchmark: what the scenarios assume, what the metrics mean, how to read the table |
@@ -485,7 +488,7 @@ These are design decisions, not missing features:
 * **Semantic reduction** — accuracy, pass@k, F1 and any cross-pipeline aggregation. Export the artifacts and
   compute it outside, or write a sink pipeline out of the primitives.
 * **DAG orchestration** — a pipeline is a linear chain; branch inside a task with `fanout`. The one
-  qualification is the opt-in [handoff](#advanced-handoffs-opt-in): it changes the traversal of
+  qualification is the opt-in [handoff](#handoffs-opt-in): it changes the traversal of
   the chain along declared edges, never its topology (no joins, no second entry point, no cross-pipeline
   jumps).
 * **A serving gateway** — the only HTTP surface is the read-only debug endpoint above.
@@ -496,16 +499,25 @@ every known tradeoff with its reason.
 
 ## Status
 
+**0.3.2 — experiment suites and supported control flow.** Independent experiments can share resource
+pools and global concurrency, with unified run/resume/report commands and optional per-experiment output
+directories. Durable run histories preserve earlier outcomes after resume. Handoffs, forward jumps,
+rewinds and retry-all are supported public features, enabled through explicit `control` declarations.
+See the [Suite guide](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/suites.md) and
+[release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21).
+
 **0.3.1 — application-reported live metrics.** Applications can publish values such as accuracy to the
 read-only monitoring dashboard through `Runner.report_metric()` or `TaskContext.report_metric()`. A completion
 callback receives committed pipeline results; the application owns the calculation. The dashboard and
 `watch` now follow one run consistently by default. See [`examples/live_metrics.py`](examples/live_metrics.py).
 
-**0.3.0 — advanced control flow (opt-in), and the documentation in Chinese.** Tasks can now
-[hand off](#advanced-handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
+**0.3.0 — control flow (opt-in), and the documentation in Chinese.** Tasks can now
+[hand off](#handoffs-opt-in): return a `Handoff` to skip declared stations or finish the pipeline
 early, recorded in a durable ledger that recovery resumes from. It is opt-in and inert — a pipeline without a
-`control` block writes no new rows and keeps a byte-identical `spec_digest` — and marked experimental until
-1.0. Backward traversal now adds declared rewind and retry-all with visits and optional payload history. The
+`control` block writes no new rows and keeps a byte-identical `spec_digest`. Handoffs and backward traversal
+were experimental in 0.3.0 and became supported features in 0.3.2
+(see [0.3.2 release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)). Backward traversal adds declared rewind and retry-all with visits
+and optional payload history. The
 whole documentation set also ships in Simplified Chinese ([`README.zh-CN.md`](README.zh-CN.md),
 [`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)), kept in sync by CI. One
 rename to know about when upgrading: `MergedReport.events_total` is now `source_events_total`, because that
@@ -561,3 +573,7 @@ extracted and executed by `tests/test_tutorial.py`, so documentation that rots f
 ## License
 
 MIT — see [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE).
+
+## Experiment suites
+
+Combine existing configuration files under one Runner with shared resource pools and total concurrency. Optional per-experiment directories separate checkpoints, results and file artifacts. Suite reports include prior successes across resumes. See the [Suite guide](docs/suites.md) and [runnable configuration](examples/suites/suite.json).

{pyattacker-0.3.1 → pyattacker-0.3.2}/README.zh-CN.md

@@ -51,7 +51,7 @@ uv run pyattacker demo       # zero-config smoke test: 50 simulated pipelines, r
 | 概念 | 含义 | 一句话 |
 |---|---|---|
 | **artifact（产物）** | 任务持久化后的状态 | 内容寻址，**一产生就落盘** → 检查点粒度 = 任务 |
-| **task（任务）** | 调度的最小单位 | 一个一元函数 `(artifact) -> artifact`，同步异步都行——也可以 `-> artifact \| Handoff` 来跳过后续步骤（[进阶](README.zh-CN.md#进阶交接可选启用)） |
+| **task（任务）** | 调度的最小单位 | 一个一元函数 `(artifact) -> artifact`，同步异步都行——也可以 `-> artifact \| Handoff` 来跳过后续步骤（[交接](README.zh-CN.md#交接可选启用)） |
 | **pipeline（流水线）** | 完成和恢复的单位 | `fetch \| ask \| judge \| metrics` 线性串起来，各步语义独立 |
 | **resource（资源）** | 可租用的外部能力 | 一个端点 / 一把 key；放进资源池后可以并发安全地发布和订阅 |
 | **algorithm（算法）** | 获取资源的策略 | `wait`、`backoff`、`least_busy`、`failover`、`sticky`、`quota_aware`、`immediate`——和"失败了怎么重试"是两回事 |
@@ -147,14 +147,16 @@ runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.y
 * 任务和输入都没变、已经成功的流水线 → 直接跳过。
 * 失败的流水线 → 从**第一个没产出 artifact 的任务**接着跑：任务 C 挂了，只要 B 的检查点已经落盘，就只重跑 C。
 * 种子数据也持久化了 → 续跑**不需要原始数据集文件**。
-* 走过交接的流水线（[进阶](README.zh-CN.md#进阶交接可选启用)）会在跳转目标处恢复，用账本里记好的入口状态——发起跳转的那个任务不重跑。
+* 走过交接的流水线（[交接](README.zh-CN.md#交接可选启用)）会在跳转目标处恢复，用账本里记好的入口状态——发起跳转的那个任务不重跑。
 * 改了任务源码（`spec_digest` 包含源码摘要）→ 视为全新流水线，不会拿旧结果瞎复用。工厂参数、fanout 子任务、重试/算法策略、显式的 `config`/`version` 都算在内。手动指定 key 的话，定义或输入变了会直接拒绝。
 
 **升级已有存储：** fingerprint v2 改了默认 ID 和分片分配方式。旧任务可能会重跑，旧的手动 key 会冲突。建议用旧版本把手上的跑完，再换新存储。迁移指引、动态函数和外部配置详见 [恢复同一性与幂等性参考](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#恢复同一性)。
 
-## 进阶：交接（可选启用）
+<a id="进阶交接可选启用"></a>
 
-**这是进阶功能：需要手动开启，会改变执行模型，普通流水线用不上，1.0 之前算实验性。**
+## 交接（可选启用）
+
+**交接、正向跳转和回退都是正式的控制流特性，通过 `control` 显式声明后启用。**
 
 任务可以判断"后面的步骤不用跑了"，然后*明确说出来*，而不是硬编一个失败或者把分支藏在某一步里面。它**返回**一条指令——`Handoff.to(target, value)` 表示跳到指定的后续步骤继续跑，`Handoff.end(value)` 表示直接收尾：
 
@@ -217,11 +219,11 @@ with Runner(store=":memory:", concurrency=4) as runner:
 * **交接是一种处置结果，不是失败。** 它是个返回值，所以重试策略根本看不到它，任务里写的 `except Exception:` 也吞不掉它。租约的归还和成功时完全一样，被取消或超时的尝试压根走不到返回这一步。
 * **它是持久化的检查点。** 跳转是原子提交的（源任务、尝试、入口产物、账本记录、游标一起提交），进程被杀了会在目标步骤恢复，带着记录好的入口状态，不会重跑源任务。开了控制流的流水线里，`n_tasks_done` 是个*位置*，不是进度计数——被跳过的步骤没有任务记录。`watch` 默认统计选定运行的提交数（`--run-id all` 查看全部历史）；`/pipelines.handoffs` 统计活跃执行记录，`handoffs_historical` 统计全部账本记录。续跑时可以用之前某次运行的活跃交接，同时不记录新的交接。导出的流水线数据里会带上账本身份和水位标记，用来区分这些范围。
 * **不开就完全没影响。** 没有 `control` 块的流水线，一行数据、一个计数器、`spec_digest` 的一个字节都不会变。
-* **往回跳需要单独声明。** `Handoff.rewind(target, value)` 把作者指定的状态送回更早的步骤；`Handoff.retry_all()` 从最初的种子重新开始。需要声明 `control.rewind` / `control.retry_all`，还要设一个有限的 `control.max_handoffs`。可选的 `HistoryArtifact` 载荷可以做显式快照和恢复；普通字典的控制权完全在作者手里。访问记录（visits）和精确的产物出现记录会保留历史，保证恢复安全。API、预算和恢复边界见 [reference → 进阶：反向遍历](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#进阶反向遍历rewindretry-allvisits)，可运行的示例见 [tutorial 第 16–17 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-16-步--高级用回退和全部重试重新生成)。
+* **往回跳需要单独声明。** `Handoff.rewind(target, value)` 把作者指定的状态送回更早的步骤；`Handoff.retry_all()` 从最初的种子重新开始。需要声明 `control.rewind` / `control.retry_all`，还要设一个有限的 `control.max_handoffs`。可选的 `HistoryArtifact` 载荷可以做显式快照和恢复；普通字典的控制权完全在作者手里。访问记录（visits）和精确的产物出现记录会保留历史，保证恢复安全。API、预算和恢复边界见 [reference → 反向遍历](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#反向遍历rewindretry-allvisits)，可运行的示例见 [tutorial 第 16–17 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-16-步--用回退和全部重试重新生成)。
 
-API 就是一个类（[`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#进阶交接可选启用)）、一条声明——正向跳转用 `control={"edges": {...}}`，反向遍历用 `control.rewind` / `control.retry_all` / `control.max_handoffs`——再加一项可选的存储能力。无法原子提交交接的自定义存储会直接被拒绝，不会让你写一个崩了就丢的跳转。
+API 就是一个类（[`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md#交接可选启用)）、一条声明——正向跳转用 `control={"edges": {...}}`，反向遍历用 `control.rewind` / `control.retry_all` / `control.max_handoffs`——再加一项可选的存储能力。无法原子提交交接的自定义存储会直接被拒绝，不会让你写一个崩了就丢的跳转。
 
-上手示例：[教程第 15 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-15-步--高级跳过站点交接)。模型和规则：[设计 §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/design.md#48-进阶交接--声明式正向跳转可选启用实验性)。
+上手示例：[教程第 15 步](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md#第-15-步--跳过站点交接)。模型和规则：[设计 §4.8](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/design.md#48-交接--声明式正向跳转可选启用)。
 
 流水线从种子重新开始时，之前的任务记录和链上产物会和游标/水位一起原子重置。之前的交接还留在历史里，但不再当检查点用。之后的续跑只看当前这轮执行的交接，完成时选一个最终产物。支持交接的自定义存储必须把持久化的 `handoff_floor` 水位和游标一起存，还要实现原子的 `reset_pipeline(record)`。详见 [恢复契约](docs/zh-CN/reference.md#表与读取器)。
 
@@ -351,8 +353,8 @@ uv run pyattacker bench --algorithms wait,backoff --seeds 5 --json runs/bench.js
 
 | 文档 | 内容 |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md) | 17 个可运行步骤，从"一个任务"到分片评测和高级交接/反向遍历——回退、全量重试、载荷历史都有；每个步骤都有测试执行 |
-| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md) | 所有公开类和函数：签名、参数、示例——包括高级反向遍历和 `HistoryArtifact` |
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/tutorial.md) | 17 个可运行步骤，从"一个任务"到分片评测、交接和反向遍历——回退、全量重试、载荷历史都有；每个步骤都有测试执行 |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/reference.md) | 所有公开类和函数：签名、参数、示例——包括反向遍历和 `HistoryArtifact` |
 | [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/cli.md) | 每个子命令、每个参数、退出码、配置参考 |
 | [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/design.md) | 概念模型、六条不变量、租约契约、数据模型、设计权衡 |
 | [`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/benchmark.md) | 算法基准测试：场景假设了什么、指标怎么看、表格怎么读 |
@@ -383,7 +385,7 @@ uv run pyattacker run -c examples/qa_eval.yaml --limit 40
 
 * **网络请求**——openai/anthropic 的调用你自己写。内核从不碰 socket。
 * **指标计算**——准确率、pass@k、F1，以及任何跨流水线的汇总计算。把产物导出来在外面算，或者用原语自己拼一条汇总流水线。
-* **DAG 编排**——流水线就是一条直线链，要分支就在任务内部用 `fanout`。唯一例外是可选的[交接](README.zh-CN.md#进阶交接可选启用)：它只是沿着声明的边改变链的遍历方式，拓扑不变（没有汇合节点、没有第二个入口、没有跨流水线跳转）。
+* **DAG 编排**——流水线就是一条直线链，要分支就在任务内部用 `fanout`。唯一例外是可选的[交接](README.zh-CN.md#交接可选启用)：它只是沿着声明的边改变链的遍历方式，拓扑不变（没有汇合节点、没有第二个入口、没有跨流水线跳转）。
 * **服务网关**——唯一的 HTTP 接口就是上面那个只读调试面板。
 * **分布式调度**——横向扩展用 `--shard`，多进程就是上限。
 
@@ -391,11 +393,17 @@ uv run pyattacker run -c examples/qa_eval.yaml --limit 40
 
 ## 当前状态
 
+**0.3.2——组合实验与正式控制流特性。** 独立子实验可共享资源池和总并发，统一运行、恢复和查看结果，
+并可按实验分目录存储。持久化的运行历史在恢复后仍保留此前的结果。交接、正向跳转、回退和全量重试
+作为正式公共特性维护，通过 `control` 显式声明后启用。
+详见 [Suite 指南](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/suites.md) 和
+[发布说明](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)。
+
 **0.3.1——应用汇报的实时指标。** 应用可用 `Runner.report_metric()` 或 `TaskContext.report_metric()`
 把准确率等数值汇报到只读监控面板。完成回调提供已提交的流水线结果，指标计算仍由应用负责。
 面板和 `watch` 默认统一跟随同一个运行。参见 [`examples/live_metrics.py`](examples/live_metrics.py)。
 
-**0.3.0——高级控制流（可选），以及中文文档。** 任务现在可以做[交接](README.zh-CN.md#进阶交接可选启用)：返回一个 `Handoff` 跳过声明的后续步骤或提前收尾，记录在持久化账本里，续跑时从账本接着走。需要手动开启，不开完全没影响——没有 `control` 块的流水线不写新数据，`spec_digest` 逐字节不变。1.0 之前标记为实验性。反向遍历现在支持声明式回退和全量重试，带 visits 和可选的载荷历史。整套文档也提供了简体中文版（[`README.zh-CN.md`](README.zh-CN.md)、[`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)），由 CI 保持同步。升级时有一个改名要知道：`MergedReport.events_total` 现在叫 `source_events_total`，因为它是合并报告里**唯一**不去重、按源库原始累加的计数（旧名字仍可作为废弃别名使用）。
+**0.3.0——控制流（可选），以及中文文档。** 任务现在可以做[交接](README.zh-CN.md#交接可选启用)：返回一个 `Handoff` 跳过声明的后续步骤或提前收尾，记录在持久化账本里，续跑时从账本接着走。需要手动开启，不开完全没影响——没有 `control` 块的流水线不写新数据，`spec_digest` 逐字节不变。交接与反向遍历在 0.3.0 发布时属于实验性特性，在 0.3.2 中提升为正式特性（见 [0.3.2 发布说明](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#032--2026-09-21)）。反向遍历现在支持声明式回退和全量重试，带 visits 和可选的载荷历史。整套文档也提供了简体中文版（[`README.zh-CN.md`](README.zh-CN.md)、[`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN)），由 CI 保持同步。升级时有一个改名要知道：`MergedReport.events_total` 现在叫 `source_events_total`，因为它是合并报告里**唯一**不去重、按源库原始累加的计数（旧名字仍可作为废弃别名使用）。
 
 **0.2.0——基准测试、更严格的身份校验、三处正确性修复。** 新增 `pyattacker bench`：一个模拟接口方的世界，用一组指标对比各获取算法，而不是一个加权分数（[`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/zh-CN/benchmark.md)）。新增 `Retrying.decide`：把重试决策暴露为策略上的方法。新增分页的整类读取（`pyattacker.store.iter_*`，由可选的 `PagedStore` 扩展提供），导出大存储不再需要全量加载。0.1.x 已经实现了 M0–M4 计划的全部内容：内核、持久化和任务级恢复、重试和错误分类、带 7 种获取算法的资源池、延迟延续和 write-behind 批处理、分片和合并报告、三种格式五种导出形状、入口点插件、外部产物后端、fan-out 辅助函数、HTTP 监控端点。
 
@@ -421,3 +429,7 @@ uv build                     # sdist + wheel
 ## 许可证
 
 MIT——见 [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE)。
+
+## 实验集合
+
+把已有配置文件组合到同一个 Runner，共享资源池和总并发。可选的按子实验分目录布局分别保存检查点、结果和文件产物；Suite 报告包含恢复前已完成的结果。参见 [Suite 指南](docs/zh-CN/suites.md) 和 [可运行配置](examples/suites/suite.json)。

{pyattacker-0.3.1 → pyattacker-0.3.2}/docs/cli.md

@@ -152,7 +152,7 @@ over the stores you passed, duplicates included, because an event is not part of
 `--errors N` prints the first N failures with their error class. `--json` gives you the same numbers as an
 object. A run that recorded handoffs says so in its summary line (`... attempts: total=12 handoffs=2`), and
 `--rows pipelines` on `export` carries the ledger itself (see
-[advanced: handoffs](reference.md#advanced-handoffs-opt-in)).
+[handoffs](reference.md#handoffs-opt-in)).
 
 If the store contains failed terminal repair attempts, the report lists them separately
 (`Terminal repair failures: N pipeline(s)`), each with the pipeline id and failure phase. This is a
@@ -188,6 +188,7 @@ pyattacker export STORE [STORE ...] OUTPUT [--rows SHAPE] [--format FMT] [--run-
 | `attempts` | attempt, including each retry `decision` |
 | `events` | structured event |
 | `artifacts` | artifact, intermediate ones included |
+| `results` | pipeline final result, status, error and experiment identity |
 
 `--format` is `jsonl` (default), `json` or `csv`. CSV takes its header from the first rows and folds later
 keys into an `extra` column, so memory stays flat and no field is silently dropped.
@@ -331,10 +332,12 @@ the entry does not mention keeps whatever the target declares (its own `resource
 `${VAR}` is expanded from the environment (see `--strict-env`). `source.kind` is `jsonl` or `range`;
 `repeats: k` is pass@k — k independent pipelines per seed. CLI flags override the `run:` block.
 
-### `pipeline.control` — advanced, opt-in handoffs
+<a id="pipelinecontrol--advanced-opt-in-handoffs"></a>
+
+### `pipeline.control` — explicitly declared handoffs
 
 A config may also declare which task is allowed to **hand off** (skip ahead) by returning a
-[`Handoff`](reference.md#advanced-handoffs-opt-in), so the same pipeline can be expressed declaratively:
+[`Handoff`](reference.md#handoffs-opt-in), so the same pipeline can be expressed declaratively:
 
 ```yaml
 pipeline:
@@ -357,7 +360,7 @@ path — `pipeline.control.edges['judge'][0]: destination 'fetch' (seq 0) is not
 'judge' (seq 2); v1 handoffs are forward-only` — under `validate` (exit 2) as well as `run`, because both go
 through the same validation entry. Within an `edges` block there is no other key and no `mode` in this
 version; backward traversal declares its own `rewind` / `retry_all` / `max_handoffs` keys instead (see
-[Advanced backward control declarations](#advanced-backward-control-declarations)).
+[Backward control declarations](#backward-control-declarations)).
 
 Numeric source keys work across YAML, JSON and TOML: JSON/TOML spell seq 0 as the key `"0"`
 (e.g. `"edges": {"0": [2]}`). An exact task name takes precedence over a numeric string. Numeric
@@ -365,26 +368,28 @@ destinations remain integers. Declaring the same source twice through a name and
 rather than silently replacing one list. Effective configuration uses numeric seqs for repeated or
 reserved (`end`) names instead of inventing a `name#N` syntax.
 
-The feature is **advanced**: it changes the execution model, so it is opt-in, marked experimental until 1.0,
-and needs a store that can commit a handoff atomically (both built-in backends can). Pipelines without the
+Handoffs are a **supported control-flow feature**. They require an explicit `control` declaration
+and a store that can commit a handoff atomically (both built-in backends can). Pipelines without the
 block are unaffected in every respect. See
-[reference → advanced: handoffs](reference.md#advanced-handoffs-opt-in) for the API and
-[design §4.8](design.md#48-advanced-handoffs--declared-forward-jumps-opt-in-experimental) for the model.
+[reference → handoffs](reference.md#handoffs-opt-in) for the API and
+[design §4.8](design.md#48-handoffs--declared-forward-jumps-opt-in) for the model.
 
 The declarative layer describes **composition and resources only**; the logic stays in Python behind `use:`.
 Anything it cannot express is a reason to use the SDK, not a reason to add YAML — see
 [`docs/tutorial.md`](tutorial.md) step 11 for where the line falls.
 
-### Advanced backward control declarations
+<a id="advanced-backward-control-declarations"></a>
+
+### Backward control declarations
 
 `pipeline.control` also accepts `rewind: {source: [earlier_targets]}`, `retry_all: [sources]` and
 required positive `max_handoffs` for backward traversal. `edges` is optional for backward-only plans;
 existing forward-only declarations stay unchanged. `run.max_handoffs` sets the runtime ceiling (default
 1000). Validation shares Python's name/seq resolution and reports configuration field paths. Rewind payloads
 are chosen by task code, not config. See
-[reference → advanced: backward traversal](reference.md#advanced-backward-traversal-rewind-retry-all-visits)
+[reference → backward traversal](reference.md#backward-traversal-rewind-retry-all-visits)
 for the syntax, the visit model, the budget lifecycle and missing-payload recovery, and
-[tutorial steps 16–17](tutorial.md#step-16--advanced-regenerating-with-rewind-and-retry-all) for working
+[tutorial steps 16–17](tutorial.md#step-16--regenerating-with-rewind-and-retry-all) for working
 Python examples, `HistoryArtifact` included.
 
 ## See also
@@ -393,3 +398,9 @@ Python examples, `HistoryArtifact` included.
 * [`docs/reference.md`](reference.md) — every class and function the SDK exposes
 * [`docs/design.md`](design.md) — why the CLI has these commands and no others
 * [`README.md`](../README.md) — the compact tour
+
+## Suite commands
+
+Suite configurations reuse `run`, `resume` and `validate`. `run/resume` accept repeatable `--experiment ID` and `--output-root`; `report/watch/export/serve` accept a Suite directory and `--experiment ID`. `export --rows results` writes lightweight final results; `--by-experiment` writes OUTPUT/ID/ROWS.FORMAT. Suite `--store`, `run.store` and sharding flags are rejected. Directory reads default to cumulative results; `--run-id` selects invocation admissions and history.
+
+[Full guide and examples](suites.md).