migec 2.2.1__tar.gz → 2.4.0__tar.gz

migec-2.4.0/.github/workflows/benchmark.yml

@@ -0,0 +1,107 @@
+name: Benchmark
+
+# A separate file rather than a job in ci.yml: adding `schedule` to ci.yml's triggers would run
+# cpp, python and lint on the schedule too, and ci.yml's `cancel-in-progress: true` would let a
+# push cancel a benchmark mid-measurement. Keeping the PR path byte-identical is the point.
+#
+# Never on push or pull_request. These are wall-clock and peak-RSS assertions and the runner is a
+# shared VM whose neighbours we do not control, so on every PR they would be a noise generator
+# attached to the merge button.
+#
+# Note: `schedule` only ever fires on the DEFAULT branch. A regression is therefore caught the
+# night after it lands on master, never on the branch that wrote it -- run this by hand from the
+# Actions tab (workflow_dispatch) on any branch that touches a hot path.
+on:
+  schedule:
+    # 04:17 UTC. Off the hour on purpose: GitHub queues scheduled runs and the round hours are the
+    # congested ones.
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    name: Benchmark and realworld tiers
+    # One OS. The assertions are absolute -- reads/s and bytes per distinct UMI -- so a second
+    # runner class with a different core count and a different RSS accounting would need a second
+    # set of thresholds to mean anything.
+    runs-on: ubuntu-latest
+    # A stage that hangs should cost half an hour of runner time, not the six-hour default.
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: |
+          uv pip install --system scikit-build-core "pybind11>=3.0.2,<4" ninja cmake
+          uv pip install --system -e ".[test]" --no-build-isolation
+
+      # -s because the tests print the measured numbers, and the number is the reason to read the
+      # log at all -- a green tick says only that nothing fell by 10x.
+      #
+      # The thresholds these assert are deliberately loose: >20,000 reads/s against a measured
+      # 1.5-2.5 M, >2x speedup on 4 threads, <48 bytes per distinct UMI. They exist to catch a 10x
+      # regression -- a transcendental back in the scoring loop, zlib level 6 back on the serial
+      # path, a hash map back in the UMI counters -- and not to police a 10% one, which on a shared
+      # runner is indistinguishable from a busy neighbour.
+      - name: Benchmark tier
+        env:
+          RUN_BENCHMARK: "1"
+        run: python -m pytest tests/benchmark -q -s
+
+      # `isalgo/umi_data` is public, so an anonymous GET on the resolve URL is the whole of it: no
+      # token, no huggingface_hub, no git-lfs client on the runner. Verified 2026-08-14 that the
+      # resolve URL 302s to the CDN for an unauthenticated client. The three files under ci/ are
+      # 1.9 MB together.
+      #
+      # Note: this and the two steps below run even when the benchmark tier above went red. A
+      # wall-clock threshold that flaked on a busy runner must not also cost the night's accuracy
+      # signal; `!cancelled()` rather than `always()` so a timeout or a cancel still stops here.
+      - name: Fetch the umi_data ci fixtures
+        id: fixtures
+        if: ${{ !cancelled() }}
+        run: |
+          base=https://huggingface.co/datasets/isalgo/umi_data/resolve/main/ci
+          mkdir -p "$RUNNER_TEMP/umi_data/ci"
+          ok=true
+          for f in SRR1763769_umi0.5pct.fq.gz SRR1763769_barcodes.txt \
+                   sc5p_v2_hs_PBMC_1k_t_cells1pct.fq.gz; do
+            curl -fsSL --retry 3 --retry-all-errors \
+              -o "$RUNNER_TEMP/umi_data/ci/$f" "$base/$f" || ok=false
+          done
+          # An LFS pointer served in place of the object, or a truncated body, both arrive with a
+          # 200 and surface four steps later as an unreadable FASTQ. `gzip -t` names it here.
+          for f in "$RUNNER_TEMP"/umi_data/ci/*.fq.gz; do gzip -t "$f" || ok=false; done
+          ls -l "$RUNNER_TEMP/umi_data/ci"
+          echo "fetched=$ok" >> "$GITHUB_OUTPUT"
+
+      - name: Realworld tier
+        if: ${{ !cancelled() && steps.fixtures.outputs.fetched == 'true' }}
+        env:
+          UMI_DATA: ${{ runner.temp }}/umi_data
+        run: |
+          set +e
+          python -m pytest tests/realworld -q
+          code=$?
+          set -e
+          # 5 is pytest's "collected nothing". tests/realworld is a tier under construction, and an
+          # empty directory has to read as an empty tier rather than as a broken job -- the day a
+          # test lands there it is guarded by this step with no change to this file.
+          if [ "$code" -eq 5 ]; then
+            echo "::warning::tests/realworld collected no tests -- the fixtures fetched and guard nothing yet"
+            exit 0
+          fi
+          exit $code
+
+      # Loudly, not silently: a realworld tier that quietly stopped running is exactly the failure
+      # this workflow exists to end. The job stays green because an HF outage is not a defect in
+      # this repo, but the annotation says on the run summary that the tier did not run.
+      - name: Report a failed fixture fetch
+        if: ${{ !cancelled() && steps.fixtures.outputs.fetched != 'true' }}
+        run: |
+          echo "::warning::could not fetch isalgo/umi_data ci/ over https -- the realworld tier did NOT run"

{migec-2.2.1 → migec-2.4.0}/.github/workflows/publish.yml

@@ -40,7 +40,12 @@ jobs:
         env:
           CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-*"
           CIBW_SKIP: "*-musllinux_* *-manylinux_i686"
-          CIBW_TEST_COMMAND: "python -c \"import migec; print(migec.__version__)\""
+          # Never: an import is not a smoke test. A wheel with a broken console script -- an
+          # entry-point typo, typer missing from `dependencies`, a `_core` symbol only touched at
+          # runtime -- imports cleanly and publishes green, and the first person to run
+          # `migec checkout` finds out. This runs the CLI and one read through the pipeline, which
+          # costs seconds and exercises the extension, the console script and the dependency list.
+          CIBW_TEST_COMMAND: "bash {project}/scripts/wheel_smoke.sh"
       - uses: actions/upload-artifact@v4
         with:
           name: python-wheels-${{ matrix.os }}

{migec-2.2.1 → migec-2.4.0}/.gitignore

@@ -6,6 +6,8 @@
 build/
 # the thread-sanitizer build; see docs/performance.rst for how to make one
 build-tsan/
+# a second ordinary build, for verifying a change without disturbing the installed extension
+build-verify/
 # setup.sh creates this
 .venv/
 # intermediate record files; regenerate with `migec checkout`
@@ -36,3 +38,5 @@ docs/_build/
 *.bam
 *.bai
 *.crai
+build-verify/
+_migec_error.log

{migec-2.2.1 → migec-2.4.0}/CHANGELOG.md

@@ -4,6 +4,308 @@ Hand-written and prose-heavy: each entry says what changed and, where it matters
 prevents. Releases before 2.0.0 are the Groovy MIGEC and are described by their git tags on the
 `legacy-v1` branch.
 
+## 2.4.0 — 2026-08-14
+
+Note: the wheel smoke test lowercased the whole barcode-sheet line, sample id included, so
+`checkout` wrote `co/s1.fq.gz` and the next command asked for `co/S1.fq.gz`. That passes on macOS,
+whose filesystem is case-insensitive, and fails on Linux — and 2.4.0 is the first release whose
+publish run executed the script at all, so it failed there and nowhere else. The adapter is
+lowercased on its own now.
+
+**Nothing in the pipeline scales with the library any more**, and the comparisons the version
+number was waiting on have started landing: MIGEC 1.2.9, UMI-tools and fgbio are all run end to
+end and scored.
+
+Note: 2.3.0 was written up but never tagged or published — the last wheel on PyPI is 2.2.1 — so
+this release carries its changes too. Its section below still describes them.
+
+### MIGEC 1.2.9, head to head
+
+`scripts/compare_migec_v1.py` runs the Groovy implementation this repo replaced and migec 2 over
+the same simulated library, same barcode dialect, same sheet, both pipelines end to end.
+**9.4-11.9x the wall clock** against an M5 gate of 3x, 3.5-3.7x less memory, and the molecule count
+is 0.09% over truth against v1's 13.6% -- 99.8-99.99% of our consensuses are exactly a template,
+against 93.9-95.1%. The over-count is barcode errors `--filter-collisions` did not catch, because
+its rule is a count ratio and a count ratio carries nothing below ~3 reads per UMI.
+
+`--min-count` is given to both: v1 defaults to 5 and migec 2 to 1, so leaving each at its own
+default would have credited us with recovering molecules v1 was told to throw away.
+`docs/validation.rst`, `assets/migec_v1.tsv`.
+
+### UMI-tools and fgbio, measured
+
+`scripts/compare_grouping.py` runs both map-first tools end to end and scores all three partitions
+against the simulator's truth with the same adjusted Rand index Calib is scored with. What it
+measures is what the alignment position is worth, because that is the only difference: they group
+on *(position, UMI)*, we group on *(sample, cell, UMI)* and align once, afterwards.
+
+On **one reference** — a single amplicon, a clonal control, a targeted ctDNA panel — the position
+carries nothing, and migec wins: ARI 0.9967 against 0.9864 (UMI-tools) and 0.9817 (fgbio), with
+0.65% of reads in clusters that mix molecules against 3.0% and 3.9%. That is 4.6x and 6x fewer
+molecules destroyed, and destroying one is the error nothing downstream can detect. Nothing
+rescues that case: two molecules that collide on one reference hold the same sequence, so neither
+the mapping position nor payload sub-clustering can tell them apart, and the barcode is the only
+evidence there is.
+
+On 200 or 20,000 distinct references they win by 0.001 ARI, and that gap is a **depth threshold**
+rather than a limit of the method. Collided molecules there carry *different* sequences, which is
+what makes them separable, and `assemble`'s linkage sub-clustering separates them from the payload
+with no aligner -- but only above the depth the 8.68 threshold fixes for itself, since the strongest
+evidence a 50/50 split can carry is `log10 C(n, n/2)` and that reaches 8.68 at n ~ 32.
+`scripts/collision_split.py` measures it: **0 of 12 collisions separated at 9.1 reads on the
+barcode, 7 of 14 at 40.9, and 10 of 10, 13 of 13, 10 of 10 at 82, 161 and 283.** The comparison
+above was scored at 5 reads per molecule, a third of what the test needs. migec is 8-48x faster
+throughout, including the alignment they cannot skip.
+
+A collision is defined on the **true** barcode, never the observed one -- two molecules whose
+observed barcodes coincide because one picked up a sequencing error are what `refine` corrects, and
+counting them makes the collision rate grow with the read count, which it cannot do.
+
+`docs/grouping.rst` has the table, `assets/grouping_tools.tsv` the numbers, `SOURCES.md` how to
+install both (fgbio needs a JDK 17+; UMI-tools needs `--no-build-isolation` on Python 3.12+). The
+simulator now writes `clones.fa`, the reference a map-first tool has to align to.
+
+### `refine`'s barcode table bounds itself
+
+The last thing in the pipeline that scaled with the library. Past 1 GB the table range-partitions
+to disk, correction follows it into the partition, and every table refine writes is streamed one
+bucket at a time. Nothing changes but the wall clock: a partitioned run and a resident one agree on
+every scalar and on every output file byte for byte.
+
+Two things this needed that `checkout`'s counters did not. The table carries the **evidence** —
+the barcode's own quality at each position and its payload draft — because a side array indexed
+against the entry list cannot survive a partition, and dropping it would leave the bucketed run
+correcting on the count ratio alone, which reports nothing at 1–3 reads per UMI. And the two passes
+**scan**; they do not merge. A barcode can have a plausible parent on each side of the partition
+boundary, and merging inside a pass takes the first candidate rather than the best: 2 barcodes in
+6,591 landed on a different parent than the resident run gave them, and every table downstream
+moved with them. Both passes now propose and one global apply decides, in the same order the
+resident walk uses.
+
+The budget is a `refine.run()` argument, never a CLI flag. Two smaller things came with it: the
+evidence pass folded into the table pass, so refine streams the reads twice rather than three
+times, and the barcode-rank curve is read off the MIG size spectrum rather than off a sorted array
+of every molecule's count — the last allocation in the stage that was one entry per barcode.
+
+### `--mate2`: both ends of the fragment are one molecule
+
+A read pair carries one barcode because it is one molecule, so `assemble` will take the other mate
+and place it:
+
+```bash
+migec assemble out/S1_R1.fq.gz --mate2 out/S1_R2.fq.gz -o cons/
+migec assemble out/S1.000.mig --merge-mates -o cons/     # the pair is already in the record
+```
+
+Mate 2 is reverse-complemented and placed against mate 1. Overlapping mates give one consensus
+spanning the insert; mates that do not reach each other give two contigs, because the bases between
+them are covered by no read. That is `--contig`'s rule rather than a second one, and the two output
+routes agree byte for byte.
+
+The offset is a property of the molecule, not of the pair, so it is voted on once per group over
+up to eight pairs instead of placing every read against every other. The first version did the
+latter and cost 11x the single-end path (119,820 record-pairs/s against 1,356,819); the vote costs
+1,288,686 against 2,115,912, which is the price of the second read's bases and nothing else.
+
+The mates are matched by position, which is what checkout's `_R1`/`_R2` output guarantees. A file
+that ends before the other is refused: pairing off what is left attaches one molecule's mate to
+another's, and the consensus that comes out looks perfectly well formed.
+
+### `--pre-amp-error auto` fits the floor instead of naming it
+
+The cap on every emitted quality is the error that was already in the molecule before
+amplification, and until now it was a named bracket: `rt` 1e-4, `medium` 1e-5, `high` 1e-6. It can
+be measured on the dataset in front of you, and `auto` does it -- X2's estimator, run on migec's
+own consensuses rather than on a bespoke one:
+
+```bash
+migec assemble out/S1.fq.gz -o cons/ --pre-amp-error auto
+```
+
+Molecules at 20 reads or more have suppressed sequencing error to nothing, so what they still get
+wrong against the library's modal sequence is what was there before the first cycle. Injected
+1e-4 comes back as 1.20e-4 [7.94e-5, 1.75e-4] and injected 1e-5 as 1.58e-5 [8.14e-6, 2.76e-5]; with
+no injected error at all the answer is the interval's upper end, 9.56e-6, because a floor of zero
+is a quality of infinity.
+
+It refuses more often than it answers, and that is the point. A diverse library has no monomorphic
+position to score, so "disagrees with the modal base" means "is a different molecule" and the
+number that would come out is the library's diversity; a shallow library has no molecule deep
+enough for the curve to have flattened. Both refuse, fall back to the named `rt` class, and say
+why -- in the report and in the new `assemble.pre_amp_error.tsv`, which carries every input the
+fit rested on next to the fit.
+
+It costs a second assembly pass, so it is opt-in: the consensus sequences do not depend on the
+floor, only the emitted quality does, so a probe assembly runs, is read back and is deleted.
+
+## 2.3.0 — 2026-08-14
+
+**The intermediate is a partition now, end to end**, and the `.mig` format is at v2 (a reader takes
+v1 and v2, so an intermediate written by 2.2.1 still reads). Nothing in `checkout` scales with the
+library any more, `refine` and `assemble` both take buckets, and an adversarial audit of all of it
+found three bugs that destroyed or invented data -- fixed, each with the test that reproduces it.
+
+Upgrading: nothing changes unless you pass `--mig`. FASTQ is still the default at every stage, the
+CLI has one new flag, and every number a 2.2.1 run produced is the number a 2.3.0 run produces.
+
+### `checkout --mig` writes the partition `assemble` was building for itself
+
+`assemble`'s first pass range-partitions the reads on the barcode into `.mig` buckets, and that
+pass is most of its wall clock. `checkout --mig` writes those buckets directly -- same key, same
+range partition, `<sample>.<bbb>.mig` -- and `assemble` reads them instead of building them:
+
+```bash
+migec checkout reads.fq.gz -b barcodes.txt -o out --mig
+migec assemble out/S1.000.mig -o asm      # one bucket names the whole partition
+```
+
+Measured on 500,000 reads over four samples at `-t 4`: **1.16 s to 0.98 s** end to end for the
+identical 124,878 molecules, and the consensus FASTQ is byte-identical after decompression (the
+gzip framing differs, because bucket boundaries are member boundaries and there are a different
+number of buckets). `checkout` pays 0.06 s of that and `assemble` saves 0.25 s.
+
+Opt-in, and FASTQ stays the default: a `.mig` file is a migec intermediate that nothing else
+reads, while every aligner and every pipeline in `docs/downstream.rst` speaks FASTQ.
+
+Never: **`-t` still changes nothing but the clock.** One writer per (sample, bucket), owned by one
+thread for the whole run, and every worker walks the chunks in input order -- so ownership decides
+who writes a record and never which file it lands in or where.
+
+Note: the open-file budget is for the RUN, not per sample. 256 buckets each on a 96-plex sheet
+would be 24,576 open writers; each sample of such a sheet also holds a 96th of the reads, so a
+couple of buckets each is proportionate rather than a compromise.
+
+Two things are refused rather than guessed at: buckets from two samples in one `assemble` (a UMI
+repeats across samples by design, so grouping them together invents molecules), and
+`--limit-read`/`--limit-umi` on an already-partitioned input (a limit is a prefix of the input, and
+a partition has no prefix -- the first records of bucket 0 are one corner of the barcode space).
+
+Never: **only buckets `assemble` wrote are deleted after they are consumed.** Pass 2 removes each
+bucket as it finishes with it, which is right for its own temporaries and catastrophic for
+checkout's output -- the first run through `--mig` ate three of the four samples' partitions, and
+a second `assemble` over an eaten one would report a smaller library with nothing to say why.
+
+### The i7 x i5 contingency table
+
+`checkout` reads the index pair out of the instrument's own read header -- the last field of
+`1:N:0:ATCACG+CGTGAT` -- for every read, matched or not, and writes
+`checkout.index_pairs.tsv`: reads per observed combination, each one's share of its own i7 and i5,
+and whether it looks ordered. Index hopping is the one contamination a per-sample yield cannot see,
+because a hopped read lands in another real sample and looks like one of its reads; the header is
+the only evidence, and it was already in the file.
+
+Never: **a single-indexed run is not estimable, and that is not zero.** With one index there are no
+combinations, so nothing can be off-diagonal.
+
+Note: it matters most where it is smallest. At 0.1% hopping a 1% variant in a deeply sequenced
+sample contaminates its neighbour at 1e-5, which is the level a rare-variant caller is asked to
+believe.
+
+### refine reads and writes buckets, and the format carries the barcode's own quality
+
+`checkout --mig` -> `refine` -> `assemble` runs on buckets end to end. refine's output is
+**re-partitioned on the corrected barcode**: a corrected barcode is a different key and a key
+decides its bucket, so copying a bucket through unchanged would stop it being a partition, and the
+reads whose barcode was corrected across a boundary would be grouped with strangers by the next
+stage. Every number matches the FASTQ route -- reads, barcodes, merges, molecules, the estimated
+error to nine digits, the barcode table byte for byte, and the consensus FASTQ byte for byte.
+
+`.mig` **v2** adds the BARCODE's own quality, one Phred per base, as two fixed-width columns. v1
+stored the minimum over the barcode, which is not what the correction posterior wants: it weighs
+the reported quality AT THE POSITION THAT DIFFERS, and a minimum says every position is as bad as
+the worst one -- overstating the error everywhere, which makes merges easier, which is the wrong
+direction. A v1 file still reads and falls back to the global rate, exactly as a FASTQ with no
+`QX:Z:` tag does.
+
+Note: the audit trail on the bucket route is `<sample>.barcodes.tsv`, every barcode with its
+parent. A `.mig` record has no room for the pre-correction barcode the way a FASTQ comment has
+`OX:Z:`, and two `u64` per READ to carry what is one row per BARCODE is the wrong trade.
+
+### Three data-integrity bugs, found by attacking the new code
+
+All three reproduced before they were fixed, and all three are in the `.mig` work above.
+
+- **refine wrote its output buckets over its input.** Same names on both sides, and `MigWriter`
+  opens `"wb"`, which truncates. Pointed at its own input directory the run destroyed the reads it
+  was halfway through reading. Refused now, on the resolved path, before a writer is opened.
+- **refine's `.mig` rewrite ignored `--limit-read`/`--limit-umi`.** It wrote reads the table was
+  never built from -- uncorrected, beside corrected ones, with nothing saying which was which.
+- **The sample id went into every output path unvalidated**, and in `assemble` and `refine` it comes
+  from the DATA (the `BC:Z:` tag of the first read), so a crafted tag wrote outside the output
+  directory. `validate_sample_id` refuses path separators, `..`, a leading `-` and control
+  characters.
+
+### ...and six more from the same audit
+
+A truncated spill file was read into an undersized buffer (a 15-byte heap overrun; trigger is a run
+killed mid-spill). A `.mig` header's `bucket_bits`/`bucket_index` went unvalidated into a shift and
+a vector index. A block's `n_records` was `memcpy`'d before it was bounded by the payload. `assemble`
+left its whole temp partition behind on the error path and leaked the per-bucket table handle on a
+throw. `fclose` was unchecked in four writers, so a disk that filled during the final flush was
+reported as a successful run. A failed thread SPAWN unwound over joinable threads, which is
+`std::terminate`.
+
+Two usability bugs went with them: a barcode **sheet** could not use the positional spellings that
+work through `--bc-pattern`, and an **empty input** printed statistics computed from no reads and
+exited 0.
+
+### Tests and docs
+
+`tests/realworld/` exists now -- it was an empty `__init__.py` -- and runs the two public CI
+fixtures through the stages they can support. `tests/unit/test_error_paths.py` covers empty,
+truncated and malformed input into every stage. Paired-end flows past `checkout` for the first time
+in a test, and the four-stage chain is asserted as one invariant. `.github/workflows/benchmark.yml`
+runs the benchmark and realworld tiers nightly and on dispatch, never on the PR path.
+
+README.md went from 809 lines to 206 -- install, where the barcode is, the five commands, what comes
+out, and a documentation table -- with every fact moved into a docs page rather than deleted, and
+`docs/assays.rst` is a new home for the per-assay settings table that was buried in a 762-line ctDNA
+page.
+
+### The UMI counters bound themselves, and correction follows them
+
+This is roadmap items 1 and 2, which turned out to be one item. `checkout`'s UMI counters were the
+last allocation in the pipeline that grew with the library rather than with the chunk: ~22 bytes per
+distinct barcode held in one piece, 8.8 GB at NovaSeq scale, with a warning past 1 GB standing in
+for a fix.
+
+They now range-partition to disk past `umi_budget_bytes` (1 GB for the whole run, divided by the
+samples, `0` to keep everything resident). The buckets go in `<out_dir>/.umi_spill` and are removed
+once the summary has been written; `umi_spilled` in the summary says whether it happened. The
+histogram, the composition, the distinct count, the distance-1 census and the correction all stream
+one bucket at a time. Not a CLI flag: 1 GB is where a counter becomes a problem on any machine, and
+nothing below it changes.
+
+Never: **a range partition on its own would have bounded the memory and silently stopped
+correcting.** The bucket is the top bits of the key, so a barcode whose error landed in the first
+few positions sits in a different bucket from its parent and the two can never meet — and a third
+of all barcode errors are in those positions. Correction therefore runs twice: once over the
+buckets as they stand, owning the positions the prefix does not touch, and once over a copy whose
+keys are rotated left by the width of the prefix, owning exactly the ones it hides. Every pair is
+weighed in one pass and only one, so `umis_merged` stays a count of barcodes rather than of
+opportunities to look at them. Checked field for field against the resident answer, on a simulated
+library with injected barcode errors and on a 500,000-read corpus: identical, including the
+estimated error rate.
+
+Never: a bucketed run reports the **scalars**. `root` and `corrected` are indexed against
+`entries()`, which is the array being bounded, so they come back empty rather than wrong, and
+`BarcodeEvidence` — indexed the same way — is refused rather than ignored. The stage that rewrites
+reads is `refine`, and `refine` does not spill.
+
+Two bugs found on the way, both by tests written to state the property rather than the number:
+
+- The **first** flush of a counter swaps the append buffer in wholesale and returned before the
+  budget check, so a counter whose whole library arrived in one buffer's worth never partitioned at
+  all — the bound switched itself off on exactly the small case, and reported a resident answer
+  that happened to be right.
+- The bucketed driver reported the census's `0.0` for a clean library where the resident path
+  reports the 1e-4 floor it actually corrects at. The rate quoted has to be the rate used; it feeds
+  the error budget, which divides by it.
+
+Cost: about 2.2x the wall clock when it fires (718,000 reads/s against 333,000 on the benchmark
+corpus), because the partition is read back four times. Nothing when it does not fire — 217,000
+reads/s single-threaded and 23.7 B per distinct UMI, both unchanged.
+
 ## 2.2.1 — 2026-08-14
 
 Documentation, pipelines and tooling. Note: **the wheel is unchanged from 2.2.0** — no command,
@@ -500,7 +802,7 @@ and the published benchmark comparisons. Install with `pip install --pre migec`.
 
 Everything below was developed before this tag.
 
-## Unreleased
+## 2.0.0a1 and earlier
 
 ### Cell barcodes, whitelists, cell calling, dual-end barcodes, and what the Phred is worth