pyattacker 0.3.1__tar.gz → 0.3.3__tar.gz

pyattacker-0.3.3/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          python-version: '3.11'
+          cache-suffix: docs
+      - name: Install dependencies
+        run: uv sync --locked --group docs
+      - name: Build site and check links
+        run: uv run --group docs mkdocs build --strict
+      - name: Check bilingual documentation and executable examples
+        run: uv run pytest tests/test_docs_i18n.py tests/test_docs_examples.py tests/test_tutorial.py
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    name: Deploy documentation
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{pyattacker-0.3.1 → pyattacker-0.3.3}/.gitignore

@@ -15,3 +15,5 @@ runs/
 .pyattacker/
 
 .scratch/
+
+site/

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

@@ -4,6 +4,78 @@ 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.3] — 2026-09-21
+
+### Fixed
+
+* **Dashboard HTML injection** (#78): render event and card values as text rather than
+  interpolating untrusted values into HTML.
+* **Atomic write-behind batches** (#79): SQLite commits attempts and events in one transaction
+  and assigns IDs only after commit. Failed batches remain recoverable; legacy stores stop
+  accepting fact writes after an uncertain failure. Suite eviction and shutdown preserve
+  failure boundaries and close remaining resources.
+* **Suite query correctness and cost** (#80): apply experiment/run filters before handoff
+  limits, support task limits consistently across built-in stores, and select recent events
+  using timestamp indexes. Counts and grouped statistics avoid decoding full history while
+  preserving historical run outcomes. Read-only older databases remain supported.
+* Loopback HTTP tests bypass environment proxies (#76).
+
+### Added
+
+* **Bounded pipeline admission** (#81): `max_admitted` limits queued, executing and delayed
+  pipelines together, while due retries retain their admission. Configure it through Runner,
+  the run configuration or `--max-admitted`; Suite members share one Runner budget. Live
+  statistics and persisted run configuration expose the effective limit.
+* **Bilingual documentation website** (#82): tutorials, Python API and CLI references at
+  <https://hazer-bjtu.github.io/pyattacker/>, with search, strict link checks and automated
+  GitHub Pages publishing. The site tracks main and identifies itself as development documentation.
+
+### Changed
+
+* Admission is bounded by default to `4 * concurrency`; a positive `max_admitted` overrides
+  this. Long retry backoffs can now pause input consumption. This bounds scheduler state
+  counts, not payload bytes or total memory; MemoryStore still retains accumulated data.
+* `tasks(limit=0)` returns an empty list; negative and non-integer task limits are rejected.
+  Suite timestamp indexes add disk/write and first-writer migration cost. Exact duration
+  percentiles still read and sort matching pipeline durations.
+* English and Chinese export documentation now covers the `results` row type (#77), and
+  streaming-memory claims describe admission and store retention separately (#81).
+* Development and documentation lockfile downloads use official PyPI URLs for portable CI
+  installation, without changing artifact hashes or adding library runtime dependencies (#82).
+
+## [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 +117,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 +140,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 +278,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
@@ -580,6 +652,7 @@ hard limit; asyncio tasks only (wrap blocking code with `asyncio.to_thread`); on
 balance is statistical; a merged report is a union, not a sum; a pipeline is a linear chain; the HTTP endpoint
 is unauthenticated.
 
+[0.3.3]: https://github.com/Hazer-BJTU/pyattacker/releases/tag/v0.3.3
 [0.3.0]: https://github.com/Hazer-BJTU/pyattacker/releases/tag/v0.3.0
 [0.2.0]: https://github.com/Hazer-BJTU/pyattacker/releases/tag/v0.2.0
 [0.1.1]: https://github.com/Hazer-BJTU/pyattacker/releases/tag/v0.1.1

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: pyattacker
-Version: 0.3.1
+Version: 0.3.3
 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
 Project-URL: Issues, https://github.com/Hazer-BJTU/pyattacker/issues
 Project-URL: Changelog, https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md
+Project-URL: Documentation, https://hazer-bjtu.github.io/pyattacker/
 Project-URL: Design, https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md
 Author: pyattacker contributors
 License: MIT
@@ -34,6 +34,8 @@ Description-Content-Type: text/markdown
 
 **English** | [简体中文](README.zh-CN.md)
 
+[Documentation](https://hazer-bjtu.github.io/pyattacker/)
+
 > Run tens of thousands of independent tasks to completion — resumably, observably, and without
 > reimplementing endpoint pools, retries and "which rows already ran" for the fifth time.
 
@@ -93,7 +95,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" |
@@ -119,7 +121,7 @@ async def fetch(row: dict, ctx) -> dict:
 
 
 def dataset_rows():
-    """Your dataset. A generator works too: `map` streams it, so memory stays O(concurrency)."""
+    """Your dataset. `map` streams generators; max_admitted bounds unfinished pipelines."""
     return [{"q": f"question-{i}"} for i in range(4)]
 
 
@@ -135,6 +137,11 @@ with Runner(store="runs/qa.db", pools=[pool], concurrency=8) as runner:
     report.export_jsonl("runs/qa.jsonl")
 ```
 
+Streaming input uses `max_admitted` (default: `4 * concurrency`) to bound queued,
+running and retry-delayed pipelines together. This is a count limit, not a byte
+limit; task payloads, source buffers and Store retention also consume memory.
+The default `MemoryStore` retains results as data grows. See [RunConfig](docs/reference.md#runconfig).
+
 `ctx.acquire()` falls back to the task's declared `resource`, and `lease.report(ok=...)` feeds the pool's
 health and quota accounting.
 
@@ -202,7 +209,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 +220,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>
+
+## Handoffs (Opt-In)
+
+**Handoffs, forward jumps and rewinds are supported control-flow features, enabled explicitly through `control`.**
 
-**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
+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 +306,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 +486,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 +520,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 +531,30 @@ every known tradeoff with its reason.
 
 ## Status
 
+**0.3.3 — reliability, bounded admission and online documentation.** Atomic write-behind batches,
+correct and faster Suite queries, dashboard HTML injection fixes, and a configurable
+`max_admitted` limit (default: `4 * concurrency`). The bilingual documentation site is now available.
+See the [release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#033--2026-09-21).
+
+**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 +610,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.3}/README.md

@@ -9,6 +9,8 @@
 
 **English** | [简体中文](README.zh-CN.md)
 
+[Documentation](https://hazer-bjtu.github.io/pyattacker/)
+
 > Run tens of thousands of independent tasks to completion — resumably, observably, and without
 > reimplementing endpoint pools, retries and "which rows already ran" for the fifth time.
 
@@ -68,7 +70,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" |
@@ -94,7 +96,7 @@ async def fetch(row: dict, ctx) -> dict:
 
 
 def dataset_rows():
-    """Your dataset. A generator works too: `map` streams it, so memory stays O(concurrency)."""
+    """Your dataset. `map` streams generators; max_admitted bounds unfinished pipelines."""
     return [{"q": f"question-{i}"} for i in range(4)]
 
 
@@ -110,6 +112,11 @@ with Runner(store="runs/qa.db", pools=[pool], concurrency=8) as runner:
     report.export_jsonl("runs/qa.jsonl")
 ```
 
+Streaming input uses `max_admitted` (default: `4 * concurrency`) to bound queued,
+running and retry-delayed pipelines together. This is a count limit, not a byte
+limit; task payloads, source buffers and Store retention also consume memory.
+The default `MemoryStore` retains results as data grows. See [RunConfig](docs/reference.md#runconfig).
+
 `ctx.acquire()` falls back to the task's declared `resource`, and `lease.report(ok=...)` feeds the pool's
 health and quota accounting.
 
@@ -177,7 +184,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 +195,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>
+
+## Handoffs (Opt-In)
+
+**Handoffs, forward jumps and rewinds are supported control-flow features, enabled explicitly through `control`.**
 
-**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
+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 +281,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 +461,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 +495,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 +506,30 @@ every known tradeoff with its reason.
 
 ## Status
 
+**0.3.3 — reliability, bounded admission and online documentation.** Atomic write-behind batches,
+correct and faster Suite queries, dashboard HTML injection fixes, and a configurable
+`max_admitted` limit (default: `4 * concurrency`). The bilingual documentation site is now available.
+See the [release notes](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md#033--2026-09-21).
+
+**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 +585,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).