pyattacker 0.2.0__tar.gz → 0.3.1__tar.gz

{pyattacker-0.2.0 → pyattacker-0.3.1}/.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.1}/.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.1}/CHANGELOG.md

@@ -4,7 +4,234 @@ 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.1] — 2026-09-19
+
+### Added
+
+* **Application-reported live metrics.** `Runner.report_metric()` and `TaskContext.report_metric()`
+  publish latest values scoped to a run or pipeline. Applications can observe committed pipeline
+  completions with `on_pipeline_finished(runner, record, artifact)` and compute their own accuracy or
+  other cross-pipeline measures. SQLite and in-memory stores persist the reports; `/metrics`, the HTML
+  dashboard, and terminal `watch` display them. See `examples/live_metrics.py` for a restart-aware
+  accuracy monitor. Metric calculation remains application-owned.
+
+### Fixed
+
+* **Consistent monitoring scope.** With no explicit run ID, the dashboard, JSON endpoints and terminal
+  `watch` all select the latest started run. The dashboard uses that same ID for statistics, metrics,
+  pipelines and events, including when only pipeline-scoped values were reported. `run_id=all` requests
+  aggregate operational statistics without mixing in a single run's application metrics.
+
+## [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 +580,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