pyattacker 0.2.0__tar.gz → 0.3.0__tar.gz

{pyattacker-0.2.0 → pyattacker-0.3.0}/.github/workflows/ci.yml

@@ -55,6 +55,18 @@ jobs:
       - name: Build sdist and wheel
         run: uv build
 
+      - name: Check the sdist stays lean
+        # The cap release.yml also enforces before it uploads. Catching a 1.26 MB tarball in the pull
+        # request that added the bytes is cheaper than catching it on the tag: 0.2.0 published one.
+        run: |
+          size=$(stat -c %s dist/*.tar.gz)
+          if [ "$size" -gt 1048576 ]; then
+            echo "::error::the sdist is $size bytes, over the 1 MiB cap; see the include list in pyproject.toml"
+            tar tzvf dist/*.tar.gz | sort -k3 -n -r | head -5
+            exit 1
+          fi
+          echo "sdist is $size bytes, under the 1 MiB cap"
+
   no-extra:
     name: base install, no yaml extra
     runs-on: ubuntu-latest

{pyattacker-0.2.0 → pyattacker-0.3.0}/.github/workflows/release.yml

@@ -1,17 +1,22 @@
 name: Release
 
 # Publishing is driven by a tag, so the artifact is always traceable to an exact commit.
-# Pushing v0.2.0 builds, verifies and publishes to PyPI, then attaches the files to a GitHub
-# Release. `workflow_dispatch` runs everything except the PyPI upload, which is how you rehearse
-# a release without spending a version number: PyPI refuses a re-upload, and a version, once
-# published, can be deleted but never reused.
+# Pushing v0.2.0 verifies and builds the files, publishes them to TestPyPI, installs them back from
+# TestPyPI by name, and only then uploads them to PyPI and attaches them to a GitHub Release. The
+# scratch index is a stage rather than an optional rehearsal because it is the one place the
+# published metadata is exercised the way a user exercises it — `pip install pyattacker==X.Y.Z` —
+# and being scratch it costs nothing, while PyPI refuses a re-upload and a version, once published,
+# can be deleted but never reused.
+#
+# `workflow_dispatch` stops before both uploads unless *Publish to TestPyPI* is checked, which is
+# how you rehearse a release before spending a version number.
 on:
   push:
     tags: ["v*"]
   workflow_dispatch:
     inputs:
       publish_to_testpypi:
-        description: "Publish to TestPyPI (a dry run needs no version number)"
+        description: "Also upload to TestPyPI and install from it (otherwise the run only verifies and builds)"
         type: boolean
         default: false
 
@@ -115,6 +120,21 @@ jobs:
           fi
           echo "sdist contains no local tooling state"
 
+      # The size is a check of its own because 0.2.0 shipped 883 KB of logo PNG in a 1.26 MB sdist:
+      # `assets/` was in the include list, PNG does not compress, and nothing that unpacks an sdist
+      # needs branding. Source, tests and docs come to about 440 KB, so a 1 MiB cap leaves room for
+      # the project to grow while still failing on the next binary that does not belong in a source
+      # tree — which is cheaper to find here than in a release.
+      - name: Check the sdist stays lean
+        run: |
+          size=$(stat -c %s dist/*.tar.gz)
+          if [ "$size" -gt 1048576 ]; then
+            echo "::error::the sdist is $size bytes, over the 1 MiB cap; see the include list in pyproject.toml"
+            tar tzvf dist/*.tar.gz | sort -k3 -n -r | head -5
+            exit 1
+          fi
+          echo "sdist is $size bytes, under the 1 MiB cap"
+
       - name: Check the sdist rebuilds and passes its own tests
         run: |
           mkdir -p /tmp/sdist && tar xzf dist/*.tar.gz -C /tmp/sdist --strip-components=1
@@ -184,10 +204,13 @@ jobs:
           if-no-files-found: error
 
   # Publishing lives in its own job so the OIDC token is scoped to it alone: no test or build step
-  # ever holds a credential that can upload a release.
+  # ever holds a credential that can upload a release. That is also why the index is verified by the
+  # job below rather than by a step in this one.
   testpypi:
     name: publish to TestPyPI
-    if: github.event_name == 'workflow_dispatch' && inputs.publish_to_testpypi
+    # On a tag this is a stage of the release. On a dispatch it runs only when the input asks for it,
+    # so that a dry run stays a dry run.
+    if: startsWith(github.ref, 'refs/tags/v') || inputs.publish_to_testpypi
     needs: build
     runs-on: ubuntu-latest
     environment: testpypi
@@ -206,7 +229,10 @@ jobs:
           # caching here can only ever warn that the cache will never get invalidated.
           enable-cache: false
 
-      # --check-url lets a re-run skip files already uploaded instead of failing the job.
+      # --check-url lets a re-run skip files already uploaded instead of failing the job, which also
+      # makes a re-run of a rehearsed release idempotent: identical bytes are skipped and still
+      # verified below. Different bytes for a version TestPyPI already holds fail here on purpose —
+      # publishing those to PyPI would ship files no index has ever resolved.
       - name: Publish
         run: |
           uv publish \
@@ -215,10 +241,63 @@ jobs:
             --check-url https://test.pypi.org/simple/ \
             dist/*
 
+  # The check the rehearsal used to leave to a human, and the reason TestPyPI is a stage at all:
+  # the files are installed the way a user installs them, by name from an index, with no credential
+  # in reach. `--index-url` is what makes the install come from TestPyPI rather than PyPI, and the
+  # version being released cannot be on PyPI yet — the upload that would put it there needs this job
+  # to pass — so the `--version` assertion proves the TestPyPI files are the ones that got installed.
+  # One index is enough because the base package declares no dependencies — `tests/test_packaging.py`
+  # enforces that — while TestPyPI's own PyYAML is frozen at 3.11, so a release that grew a runtime
+  # dependency fails here rather than publishing metadata no index could resolve. The wider
+  # `--extra-index-url` form, for the `yaml` extra and for that case, is in `docs/releasing.md`.
+  testpypi_check:
+    name: install from TestPyPI
+    needs: [build, testpypi]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          # No checkout in this job, so no lockfile to key a cache on — see the note in `testpypi`.
+          enable-cache: false
+
+      - name: Install the published files by name
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          uv venv /tmp/index-check --python 3.11
+          # The simple index is a cached listing per CDN point of presence, so a file that was just
+          # uploaded can take a minute to show up in the one this job resolves through — measured at
+          # ~30-70s while this was written, on an upload uv itself had already resolved. A release
+          # waits that out rather than failing: ten attempts, 15 seconds apart.
+          for attempt in 1 2 3 4 5 6 7 8 9 10; do
+            if uv pip install --python /tmp/index-check/bin/python \
+                 --index-url https://test.pypi.org/simple/ \
+                 "pyattacker==$VERSION"; then
+              break
+            fi
+            if [ "$attempt" = 10 ]; then
+              echo "::error::pyattacker $VERSION is not installable from TestPyPI"
+              exit 1
+            fi
+            echo "attempt $attempt could not resolve pyattacker==$VERSION; retrying in 15s"
+            sleep 15
+          done
+
+      - name: The index copy is the version being released, and it runs
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          /tmp/index-check/bin/pyattacker --version | grep -qx "pyattacker $VERSION"
+          /tmp/index-check/bin/pyattacker demo --pipelines 10 --store /tmp/index-check/demo.db
+          echo "TestPyPI serves pyattacker $VERSION and the installed CLI runs"
+
   pypi:
     name: publish to PyPI
     if: startsWith(github.ref, 'refs/tags/v')
-    needs: build
+    # Gated on the index check, not just on the build: the files are published for real only after
+    # TestPyPI has served them to a clean environment and the CLI there reported this version.
+    needs: [build, testpypi_check]
     runs-on: ubuntu-latest
     environment: pypi
     permissions:

{pyattacker-0.2.0 → pyattacker-0.3.0}/CHANGELOG.md

@@ -4,7 +4,216 @@ 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.0] — 2026-09-19
+
+### Added
+
+* **Simplified Chinese documentation, kept in sync by CI.** `README.zh-CN.md` and `docs/zh-CN/` mirror the
+  README, every document in `docs/` (tutorial, reference, design, CLI, benchmark, backward traversal,
+  releasing) and the two example READMEs, and each pair carries a language switcher. The translation is
+  structural: fenced code blocks are byte-identical to the English ones — so the tests that execute the
+  English tutorial, README and CLI examples cover the Chinese documents too — and
+  `tests/test_docs_i18n.py` fails when a code block, a heading level, a language switcher or a relative
+  link drifts out of sync. Prose quality stays a review question; the machine checks the parts that rot.
+
+* **Advanced backward traversal (opt-in, experimental):** `Handoff.rewind(target, value)` uses
+  author-selected state; `Handoff.retry_all()` replays immutable bound seed bytes. Separate declarations
+  require finite control budgets. Visit-aware atomic stores retain task/attempt/artifact occurrences,
+  effective lineage and exact pending inputs across rewind and resume. Revisited RNG includes `ctx.visit`;
+  visit-0 IDs and forward-only digests stay compatible. Optional `HistoryArtifact` payloads provide
+  detached snapshots, restoration, explicit pruning and registered-subclass codec round trips. Exports
+  and `/pipelines` expose visit-aware lineage. Restarting is explicit: `RunConfig.fresh_restart` /
+  `--fresh-restart` discards a checkpoint or traversal from the bound seed, resets the control budget and
+  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).
+
+* **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
+  finish the pipeline immediately. Until now the alternatives were to run the remaining stations anyway, to
+  fold the branch into one task with `fanout` (losing per-step records), or to raise — which records the
+  pipeline as *failed*, which is a lie. A handoff says what actually happened: this row skipped stations 3–5 and
+  continued at station 6, or finished here. It is also a **durable checkpoint**: the source task lands
+  `handed_off`, its attempt keeps `outcome="handed_off"`, the entry artifact is referenced or stored, a
+  `handoffs` ledger row records from/to and why, and the cursor moves — all in **one atomic commit**, so a
+  killed process resumes *at the target* with the entry state and never re-runs the source task.
+  `Observable changes:` a new append-only `handoffs` table (`store.handoffs(...)`, nested in the `pipelines`
+  export row, counted by `stats()["handoffs_total"]`, shown by `report`/`watch`/`/pipelines`); the attempt
+  outcome `handed_off`; handoff payload artifacts at `seq >= n_tasks`, so a payload can never overwrite a
+  task slot; the `pipeline.handoff` event; `Handoff` and `HandoffRecord` in the public API; and
+  `control={"edges": {...}}` on `pipeline(...)` plus the declarative `pipeline.control`. Edges are declared
+  rather than derived, so an undeclared or backward target is a fatal error instead of a silent jump, and
+  `fanout` rejects a directive returned by one of its branches. **A pipeline without a `control` block is
+  untouched**: no new rows, no counter changes, and a byte-identical `spec_digest` (pinned by a literal test),
+  so no stored checkpoint, pipeline id or shard assignment is invalidated. Handoffs need a store that can
+  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).
+
+### Fixed
+
+* **Documentation drift that no test could see** (issue #60), and a lightweight check for the class of it.
+  The design document still opened with "Version: 0.1.0 (M0–M4 complete, M5 … in progress)" while
+  `pyproject.toml`, the changelog and the README had been on 0.2.0 since September, and M5 — forward
+  handoffs and backward traversal — had shipped; §8 still claimed "v1 only supports asyncio tasks" while the
+  first task of the tutorial is a plain `def` and the reference documents sync-task behaviour; the reference
+  still called the tutorial "fourteen runnable steps" after three more were added; and the monitoring docs
+  promised that `serve` "serves your artifact payloads" although no route returns one — what is actually
+  exposed is event `data` and stored `error_message` fields, which is a warning worth keeping, so the
+  sentence now names those instead of the wrong thing. All of it is mirrored in the Chinese documents.
+  `tests/test_docs_facts.py` now asserts the three claims that have a source of truth — the version header
+  against `pyproject.toml`, every "N runnable steps" claim against the number of `# tutorial/` blocks, and
+  every route the monitoring endpoint table advertises against the routes `StatsServer` answers — so the next
+  release cannot leave the header behind.
+
+* **`merge_reports` no longer inflates its counters when it folds a duplicate** (issue #59). Rows were
+  always de-duplicated by `pipeline_id`, but `attempts_total` and `handoffs_total` were summed over the
+  sources — before de-duplication — so `pyattacker report a.db a.db`, or one pipeline living in two shards
+  after a shard-count change, doubled them while `pipelines.total` stayed put, contradicting the documented
+  promise that merging is idempotent. Both are now recomputed from the surviving rows (attempts from the
+  row's own `attempts_total`, handoffs from the nested ledger it carries), which is also what the module
+  docstring, `docs/design.md` §9 and `docs/reference.md` already claimed. The event log genuinely cannot be
+  re-derived — an event is not part of a pipeline row — so instead of pretending, it is renamed
+  `source_events_total` and documented as a raw per-source total; `summary()` prints it as
+  `source_events=`. Regression tests cover the same store passed twice (as two paths and as two objects),
+  one pipeline present in two shards, and the run-filtered handoff count; `tutorial.md` step 12 now shows
+  the identical `attempts=` on both sides of a duplicated merge (whose printed transcript had also drifted
+  from what the program actually prints). Counting from rows strengthens what a custom store must export,
+  so the two fields it reads are now explicit: `attempts_total` is required and a row without it raises a
+  `ConfigError` naming the row and source instead of quietly counting `0`, while a row that does not nest
+  the optional `handoffs` ledger is read through the store's own `handoffs()` capability when it has one
+  (a store with neither has no jumps, which is a true `0`).
+
+* Backward-traversal follow-up: an explicit fresh start now resets a backward pipeline's control budget
+  while preserving durable visit counters and audit history (the counters were never reset — reusing visit
+  IDs would collide with historical occurrences), so a pipeline that failed *because* it spent its budget
+  can be restarted instead of replaying the same fatal error forever; the forward capability check is
+  applied to backward-enabled pipelines too, and `supports_visits` requires the v1
+  `commit_handoff`/`reset_pipeline` ledger capability the transition actually uses;
+  `MemoryStore.stats()["attempts_total"]` counts attempt rows for the run like `SqliteStore`, instead of
+  double-counting a resumed visit's consumed attempts.
+
+* Backward-traversal review follow-up. `retry_succeeded=True` no longer restarts an unfinished backward
+  pipeline: it is an eligibility switch ("also admit succeeded pipelines"), and an unfinished pipeline still
+  owns a recoverable traversal, so replaying it from the seed would repeat external side effects the durable
+  checkpoint was about to continue. The operator escape hatch is the new `RunConfig.fresh_restart` /
+  `--fresh-restart` / `run.fresh_restart`: it discards the checkpoint or traversal, restarts from the bound
+  seed, resets the control budget and invalidates the previous ledger: append-only history (attempts,
+  events, handoffs, retained payloads) survives, and a backward pipeline additionally keeps its
+  visit-qualified occurrences and counters. It is also the documented recovery for a pipeline whose
+  traversal is gone, and it settles every task row it leaves in flight as `interrupted` instead of leaving
+  it `running` forever. Reopening a
+  `running` backward pipeline is now explicit: without `resume=True` the row is skipped
+  (`pipeline.skipped`, `reason="owned_by_another_run"`) instead of silently taking over a traversal another
+  run may still own; `resume=True` reclaims it and continues the exact durable visit. A fresh run no longer
+  reports `pipeline.checkpoint_missing` for its own seed (a `journal="summary"` store drops that payload by
+  design, which used to make every first execution look like a failed checkpoint). `control.retry_all` now
+  rejects aliases that resolve to the same source, matching `control.rewind`. A store that has committed a
+  revisit records it durably (`store_meta` feature level `visits-v1`, `store.feature_level()`), refuses to
+  open an unknown (newer) level with `StoreFeatureUnsupported`, and arms a writer guard so a lineage-unaware
+  writer fails loudly instead of mutating the wrong occurrence.
+
+* Review follow-up: freeze resolved control topology; atomically reset current task/chain artifact state
+  on control-enabled seed replays while retaining history; expose handoff identity/watermark and active
+  versus historical API counts; treat unencodable handoff payloads as fatal; correct return-only
+  annotation documentation. Handoff-capable custom stores must also provide `reset_pipeline(record)`.
+
+* Handoff follow-up: isolate historical ledger rows on whole-pipeline restarts with a durable
+  `handoff_floor` watermark (including old-store migration and read-only compatibility); roll back failed
+  SQLite handoff commits; select a single final artifact after reruns; reject duplicate source aliases;
+  preserve numeric source disambiguation in JSON/TOML/YAML and effective config; restrict the annotation
+  escape to return unions containing `Handoff`.
+
+* **A worker that dies outside its own handlers no longer hangs the run.** Run completion was tracked purely
+  by pipeline counters (`pipelines_done` against `pipelines_admitted`), so a `BaseException` that is not
+  `CancelledError` — a custom subclass raised by a store or backend hook, for example — escaped the worker's
+  handler chain, ended the task, and left the run waiting forever on a condition the dead worker could no
+  longer satisfy: no error, no exit code, no terminal row and no event (only asyncio's "Task exception was
+  never retrieved" on stderr). Worker lifetime is now supervised separately from pipeline accounting, by a
+  done-callback on every worker task that also sees a death *after* the handler chain (queue or worker
+  housekeeping). The run is hard-stopped (`stop_reason == "worker_crashed"`) without manufacturing
+  `pipelines_done`; the pipeline the dead worker was holding is recorded `failed` — or `interrupted` when the
+  run was already winding down — with the escaping exception on the row, or created if the crash happened
+  before its row existed, while a pipeline that was already terminal keeps the state it earned; admission and
+  the shutdown sentinels hand items over through an abort-aware put, so a producer parked on the full queue of
+  a dead worker is released instead of hanging one step earlier; `runner.worker_crashed` records the pipeline,
+  the exception and its traceback; and `run_async` raises the new `WorkerCrashed` (original exception as
+  `__cause__`) after closing the run record as `interrupted`, with the CLI exiting 2 on a named error. If the
+  store cannot record the crash either, the existing `StoreUnavailable` fatal path is taken instead of
+  retrying a broken store. `KeyboardInterrupt`/`SystemExit` still tear the loop down, so a narrow guard inside
+  the worker records the row and the event before they continue on their way. Cancellation and the ordinary
+  internal-`Exception` recovery path are unchanged.
+* **A pipeline whose cursor already reached the end can be resumed again.** The success path advanced the
+  checkpoint cursor and wrote the terminal state as two separate store calls, so a store failure in the
+  final write (or a kill between the two) could leave a `failed`/`interrupted` row with
+  `n_tasks_done == n_tasks_total`. Every later run then raised `IndexError: tuple index out of range` inside
+  `_open_pipeline`, surfaced only as `runner.internal_error`, while overwriting the row's original failure
+  with the framework's own crash. Such a row is now settled as completed: the last artifact is verified the
+  same way an ordinary resumed checkpoint is (present, payload kept, decodable), marked final, and the
+  pipeline is recorded `succeeded` without re-running a task, with `pipeline.terminal_repaired` carrying the
+  previous state, error and run. A cursor *past* the end is not a state the Runner can create: it is recorded
+  as `CorruptCheckpoint` and reported as `pipeline.corrupt_cursor` instead of being promoted to success, and
+  the stored value is left as the evidence; an artifact that is missing, payload-less or undecodable falls
+  back to the documented restart-from-zero rule (`pipeline.checkpoint_missing` /
+  `pipeline.checkpoint_unusable`). The repair never destroys the failure it is repairing before the outcome is
+  durable — `mark_final` runs first, the terminal transition (state, cursor, owning run, cleared failure
+  fields) is a single write where the store offers the optional `settle_pipeline` capability, and a repair
+  that fails in **either** step — marking the artifact final or settling the row — leaves the row untouched
+  (original failure and owning run included) and records `pipeline.terminal_repair_failed` with the phase,
+  so the next attempt still reports the original cause instead of the repair's own error. `mark_final` is
+  now contractually idempotent and is skipped when the artifact is already final. Because such a row keeps
+  its original owner, the failed repair is counted in the new `RunReport.repair_failures` (surfaced by
+  `summary()`, `to_dict()` and the CLI exit code) instead of silently leaving the run looking successful;
+  and on the two-write fallback for stores without `settle_pipeline`, a failed metadata cleanup after a
+  durable `succeeded` is reported as `pipeline.terminal_cleanup_failed` rather than as a failed repair. The final task now also marks its artifact final **before**
+  committing the terminal state and advances the cursor in that same call, so a crash in between re-runs the
+  final task (the documented at-least-once boundary) rather than leaving a `succeeded` pipeline whose final
+  artifact was never marked — a state no later run could repair, because a succeeded pipeline is skipped
+  forever.
+
+### Changed
+
+* **`MergedReport.events_total` is renamed `source_events_total`** (issue #59). The old name sat in the same
+  report as the de-duplicated counters without saying that it was the one number which was not de-duplicated;
+  the new name states the scope, `stats()` carries it under the same key, and `summary()` labels it
+  `source_events=`. Nothing else on `MergedReport` changed name. `MergedReport.events_total` survives as a
+  deprecated read-only alias (removed at 1.0) so an attribute read keeps working, but it is deliberately not a
+  second key in `stats()`: the point is that the JSON a report emits names one scope per number. Note that
+  `store.stats()["events_total"]` is untouched and is not the asymmetry it looks like — for a single store it
+  is the same measurement as the merged report's `source_events_total`, which the new test pins.
+
+* **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)
+  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)
+  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
+  into the Stores section. Both steps and the reference examples are marked **advanced**, stay opt-in and
+  experimental until 1.0, and are executed by the test suite (`# reference/<name>.py` joins the
+  executable-document markers). The Chinese tree mirrors all of it. No API changed.
+
+* **The sdist no longer ships the branding images.** `assets/` was in the sdist include list, and PNG
+  barely compresses, so the two logo files were 883 KB of the 1.26 MB `pyattacker-0.2.0.tar.gz` that PyPI
+  serves — two thirds of the download for an archive whose purpose is to be rebuilt and tested. Nothing
+  that unpacks an sdist needs them, and the README loads its banner over an absolute
+  `raw.githubusercontent.com` URL, so the PyPI description is unaffected; the tarball is back to 439 KB.
+  Both `ci.yml` and `release.yml` now fail the build if the sdist grows past 1 MiB, and
+  `tests/test_packaging.py` fails if a README image ever points into the checkout again.
+* **A release goes through TestPyPI before it reaches PyPI.** The scratch-index upload was a rehearsal a
+  maintainer had to opt into, and the `v0.2.0` tag skipped it — so the files PyPI received were the first copy
+  of that version any index had ever served. Every tag now publishes to TestPyPI, installs those files back by
+  name into a clean environment, asserts that the installed CLI reports the version being released, and only
+  then uploads to PyPI. The check is a job of its own with no OIDC token, so the job that holds a credential
+  that can publish does nothing else, and `pypi` now depends on it. A dispatched run still rehearses when
+  *Publish to TestPyPI* is checked and stops before both uploads otherwise. `docs/releasing.md` records the
+  consequence this makes load-bearing: a filename an index has seen can never be uploaded again, so a commit
+  after a rehearsal means a new version number, not a re-run.
 
 ## [0.2.0] — 2026-09-17
 
@@ -353,7 +562,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.
 
-[Unreleased]: https://github.com/Hazer-BJTU/pyattacker/compare/v0.2.0...HEAD
+[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
 [0.1.0]: https://github.com/Hazer-BJTU/pyattacker/releases/tag/v0.1.0

{pyattacker-0.2.0 → pyattacker-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyattacker
-Version: 0.2.0
+Version: 0.3.0
 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
@@ -32,6 +32,8 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/pyattacker)](https://pypi.org/project/pyattacker/)
 [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE)
 
+**English** | [简体中文](README.zh-CN.md)
+
 > 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.
 
@@ -91,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 |
+| **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)) |
 | **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" |
@@ -200,6 +202,8 @@ 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,
+  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
   explicit task `config`/`version` are included too. Explicit keys reject changed definitions or inputs.
@@ -209,6 +213,106 @@ 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)
+
+**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
+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:
+
+```python
+# example/readme_handoff.py
+"""A gate that skips the stations it does not need, and records why."""
+
+from pyattacker import Handoff, Runner, pipeline, task
+
+
+@task("prepare")
+def prepare(seed: dict) -> dict:
+    return {"q": seed["q"], "confidence": seed["confidence"]}
+
+
+@task("ask")
+async def ask(row: dict, ctx) -> dict:
+    await ctx.clock.sleep(0.001)                       # <- your HTTP call
+    return {**row, "answer": f"answer-for:{row['q']}"}
+
+
+@task("judge")
+def judge(row: dict) -> Handoff | dict:
+    if row["confidence"] >= 0.9:
+        return Handoff.end({**row, "verdict": "confident"}, reason="already good enough")
+    if row["confidence"] >= 0.5:
+        return Handoff.to("report", {**row, "verdict": "ok"}, reason="metrics not needed")
+    return {**row, "verdict": "needs-metrics"}
+
+
+@task("metrics")
+def metrics(row: dict) -> dict:
+    return {**row, "score": round(row["confidence"] * 10, 1)}
+
+
+@task("report")
+def report(row: dict) -> dict:
+    return {**row, "reported": True}
+
+
+# Edges are declared, never derived: judge may continue at report, or end the pipeline.
+template = pipeline("qa", prepare | ask | judge | metrics | report,
+                    control={"edges": {"judge": ["report", "end"]}})
+
+with Runner(store=":memory:", concurrency=4) as runner:
+    report_obj = runner.run(template.map([
+        {"q": "2+2", "confidence": 0.95},                        # judge ends the pipeline here
+        {"q": "17*23", "confidence": 0.6},                       # judge skips metrics, continues at report
+        {"q": "prove sqrt(2) is irrational", "confidence": 0.2},  # no handoff: the whole chain runs
+    ]))
+    print(report_obj.summary())
+    store = runner.store
+    for record in store.pipelines():
+        ran = [t.name for t in store.tasks(record.pipeline_id)]
+        hops = store.handoffs(pipeline_id=record.pipeline_id)
+        print(f"{record.state}  ran={ran}  skipped={len(template.tasks) - len(ran)}  handoffs={len(hops)}")
+```
+
+* **Declared forward edges.** A `Handoff` along an undeclared edge, or from a pipeline with no
+  `control` block, is a fatal configuration error — never retried, never a silent jump. Destinations must be
+  strictly later than their source; `end` from the last task is refused because it would do nothing.
+* **A handoff is a disposition, not a failure.** It is a return value, so the retry policy never sees it and
+  a task-side `except Exception:` cannot swallow it; leases are released exactly as on success, and a
+  cancelled or timed-out attempt never reaches the return.
+* **It is a durable checkpoint.** The jump is committed atomically (source task, attempt, entry artifact,
+  ledger row and cursor together), so a killed process resumes **at the target** with the recorded entry
+  state and does not re-run the source task. On a control-enabled pipeline `n_tasks_done` is a *position*,
+  not a progress count: skipped stations have no task rows. `report`/`watch` count commits in the selected
+  scope (one run when filtered, all history otherwise); `/pipelines.handoffs` counts active execution records and `handoffs_historical` counts all ledger
+  records. A resume can use an earlier run's active handoff while recording no new handoffs. Pipeline
+  exports include ledger identity and the watermark to distinguish the scopes.
+* **Opt-in and inert.** Without the `control` block nothing changes — not one row, not one counter, and not a
+  byte of `spec_digest`.
+* **Backward traversal is separately declared.** `Handoff.rewind(target, value)` sends author-selected
+  state to an earlier task; `Handoff.retry_all()` restarts from the original bound seed. Declare
+  `control.rewind` / `control.retry_all` and a finite `control.max_handoffs`. Optional `HistoryArtifact`
+  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),
+  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).
+
+The API is one class ([`Handoff`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md#advanced-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).
+
+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
+checkpoints. A later resume follows only the current execution's handoffs, and completion selects one
+final artifact. Custom stores supporting handoffs must persist the durable `handoff_floor` watermark
+alongside the cursor and implement atomic `reset_pipeline(record)`; see the [recovery contract](docs/reference.md#tables-and-readers).
+
 ## Running It Across Processes (Sharding)
 
 SQLite takes one writer and the kernel is a single event loop, so scale means **processes with their own
@@ -230,8 +334,8 @@ uv run pyattacker export runs/qa.shard*of4.db runs/all.jsonl
 uv run pyattacker export runs/qa.shard*of4.db runs/tasks.csv --rows tasks --format csv
 ```
 
-`--rows` picks the shape: `pipelines` (nested, default), `tasks`, `attempts` (including each retry `decision`),
-`events`, `artifacts`. `--format` picks `jsonl`, `json` or `csv`.
+`--rows` picks the shape: `pipelines` (nested, default — its tasks, artifacts and handoffs included), `tasks`,
+`attempts` (including each retry `decision`), `events`, `artifacts`. `--format` picks `jsonl`, `json` or `csv`.
 
 ## Declarative (Simple Tasks)
 
@@ -281,9 +385,10 @@ Every flag of every subcommand: [`docs/cli.md`](https://github.com/Hazer-BJTU/py
 
 ## Records and Monitoring
 
-The complete story of one pipeline = five tables queried by `pipeline_id`: state and checkpoint, the final
+The complete story of one pipeline = six tables queried by `pipeline_id`: state and checkpoint, the final
 state of each task, the full attempt history (including **every retry decision**
-`{retry, reason, delay_s, error_class}`), intermediate and final artifacts, and the structured event stream.
+`{retry, reason, delay_s, error_class}`), intermediate and final artifacts, the control-flow ledger
+(`handoffs`, empty for an ordinary pipeline), and the structured event stream.
 `pyattacker report/watch` consumes these facts directly.
 
 ## Extending It
@@ -326,8 +431,9 @@ uv run pyattacker serve runs/qa.db        # http://127.0.0.1:8787
 ```
 
 It opens a fresh read-only connection per request, so it runs happily beside a live run. It has **no
-authentication** and binds to loopback: it exposes your payloads, so treat it as a debug view and do not
-put it on a public interface without your own proxy in front.
+authentication** and binds to loopback: there is no artifact route, but it does expose what your run recorded —
+event `data` and stored error messages — so treat it as a debug view over your own data and do not put it on a
+public interface without your own proxy in front.
 
 **Branching inside a step** — `fanout(a, b)` runs several tasks on the same input concurrently and
 returns `{task_name: value}`. Retry granularity becomes the group, which is the honest price of not
@@ -368,13 +474,14 @@ what they do not say.
 
 | Document | What is in it |
 |---|---|
-| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | fourteen runnable steps, from "one task" to a sharded evaluation; 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 |
+| [`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/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 |
 | [`CHANGELOG.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md) | what changed, release by release |
 | [`docs/releasing.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/releasing.md) | for maintainers: how a release is cut and published |
+| [`docs/zh-CN/`](https://github.com/Hazer-BJTU/pyattacker/tree/main/docs/zh-CN) | 简体中文: the same documents, with code blocks that `tests/test_docs_i18n.py` keeps byte-identical to these |
 
 ## Examples
 
@@ -400,7 +507,10 @@ These are design decisions, not missing features:
 * **Network requests** — you write the openai/anthropic protocols yourself. The kernel never opens a socket.
 * **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`.
+* **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
+  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.
 * **Distributed scheduling** — scale out with `--shard`; multi-process is the ceiling.
 
@@ -409,6 +519,17 @@ every known tradeoff with its reason.
 
 ## Status
 
+**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
+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
+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
+is the one counter a merged report does **not** de-duplicate (the old name still works as a deprecated
+alias).
+
 **0.2.0 — a benchmark, stricter identity, and three correctness fixes.** New: `pyattacker bench`, a
 simulated provider world that compares the acquire algorithms on a vector of metrics instead of a weighted
 score ([`docs/benchmark.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/benchmark.md));