Skip to content

release: 2.4.0 — re-measured docs, a regenerated reference dossier, and three leaks closed - #53

Merged
MuteJester merged 7 commits into
masterfrom
release/2.4.0
Nov 5, 2026
Merged

MuteJester merged 7 commits into
masterfrom
release/2.4.0

Conversation

@MuteJester

Copy link
Copy Markdown
Owner

Release preparation for 2.4.0. Six commits, one theme each.

What a user gets

DETERMINISM_VERSION is 4. A seed does not reproduce 2.3.1's output any more, which the changelog leads with and MIGRATING.md gives a procedure for. The same n_max now settles roughly three times the population it used to cap.

The documentation was re-measured, not reviewed

422 commits since 2.3.1 moved what the docs describe. Every claim touched here was checked by running it. The failures found were not all staleness:

  • Examples that could not work as written — a nucleotide string with a literal . in it and an anchor past the end of a 21-nt sequence; two species examples that raise on a quarantined catalogue entry; a paired-end example asking for a 450-nt insert on a 352–436-nt molecule; an NpBaseModelSpec given a set where a 4×4 matrix belongs.
  • Claims that were false rather than stale — productive_only() was documented as refusing TCR references, and it does not. S5F was attributed to Shapiro rather than Yaari et al. (2013), and described as concentrating in the CDRs, which its kernel has no mechanism to do. A paired-end window was said to clip to what is available, when it raises.
  • The determinism promise had no scope. It claimed platform independence with no version attached. It now states what the reproducibility goldens actually check — Linux, macOS and Windows across Python 3.10–3.13 — and names aarch64 as shipping a wheel that nothing compares.
  • 37 unwritten pages linked to a gitignored internal document, so each of those links was a 404 on the published site.

Three things that should not have been in the repository

  1. Fourteen tracked verification records embedded absolute paths from the machine that produced them. One recorded a second project's working tree as its pythonpath. The four generator sites that wrote them are fixed too, so the next run cannot write them back. No tracked file now names a path on anyone's machine.
  2. requirements-docs.txt and two Makefile comments pointed at a document that is gitignored and therefore not in the repository.
  3. .superpowers/ was ignored only by .git/info/exclude, which never travels — on a fresh clone its contents were one git add . from being committed.

The version bump failed four tests, and that was the guard working

The packaged reference dossier records the GenAIRR version that generated it, so a checkout declaring 2.4.0 beside a dossier built by 2.3.1 is a mismatch the suite refuses — and the generator refuses too, until the installed build matches what pyproject.toml declares.

This would have broken the release, not the local run. build-wheels.yml patches pyproject.toml from the tag and then runs pytest tests/ -x -q, and nothing in that workflow can regenerate a 20 MB artifact. The archive has only existed since 2026-10-27, after the v2.3.1 tag, so no release has passed through this guard before.

Of the five pinned digests, two moved — the manifest hash and the raw archive hash, both covering the recorded version. The runtime execution, catalogue and models hashes and the source lock came back byte-identical, and the archive is the same 20110025 bytes. That is the evidence that nothing about the reference build itself changed.

Verification

  • make validate-release — 5887 passed, 17 skipped, 0 failed; Rust 1602 passed; 0 failed; genairr-2.4.0-cp39-abi3-manylinux_2_34_x86_64.whl built.
  • mkdocs build --strict exits 0; the docs and meta contract tests pass 71/71.
  • The README quick start and the full clonal pipeline were re-run and every claimed value matches, including 440 records / 440 productive.
  • tools/inventory_gate.py check --since origin/master --declarations — clean.

Known, deliberately not hidden

site_docs/guides/clonal-families.md's example still raises at seed 0: 1 of 294 records reports recalled_d_call as IGHD5-18*02 where the evidence is a tie, IGHD5-18*02,IGHD5-12*01. Truth is present and first; the tied second allele is dropped. It is lineage-specific — the ordinary path at a higher mutation rate over 2000 records is clean, while the lineage path shows 1 in 2437 across 8 seeds.

The page was left raising rather than switched to a passing seed, which would have hidden a real defect in the page that teaches the feature. Fixing it moves the clonal goldens, so it is its own change.

…avels

.superpowers/ was matched only by .git/info/exclude, which is local to one
clone and is never pushed. On a fresh clone or a second checkout its contents
would have appeared as ordinary untracked files, one 'git add .' away from
being committed. The repository's other local-only directories are already
listed in the committed .gitignore; this puts .superpowers/ beside them.
…ckout

Fourteen tracked verification and benchmark records under audit-docs/ embedded
absolute paths from the machine that produced them. One went further:
assay_oracle_verification_2026_10_20.json recorded a second project's working
tree as its pythonpath and as the path of the package under test. None of this
identifies an artifact -- the sha256 recorded beside each path does that -- so
the paths are now written relative to the repository.

The four sites that produced them are fixed too, otherwise the next run of any
of these tools would write the absolute paths back: duplex_compile_benchmark,
duplex_family_benchmark and original_end_stress each recorded extension_path
from Path(_engine.__file__).resolve(). They now record it relative to the
repository root, falling back to the basename for an extension installed
outside it.

After this, no tracked file in the repository names a path on anyone's
machine.
requirements-docs.txt and two Makefile comments referenced
docs/docs_mkdocs_migration_plan.md. docs/ is gitignored, so that document is
not in the repository and never was: a reader following the reference finds
nothing. requirements-docs.txt also gave its own install path as
docs/requirements-docs.txt, which does not exist either; the file is at the
repository root.

The Makefile's docs comment additionally said the contributor-only markdowns
live at docs/*.md -- they are at audit-docs/ -- and that 'docs-build' should be
run in CI 'once Phase 6 cutover lands'. It already is, by
.github/workflows/deploy-docs.yml, on every docs change.
422 commits since 2.3.1 moved what the documentation describes, and the
documentation did not follow. Each claim here was checked by running it, not by
reading the code around it.

Examples that could not work as written: the README's custom RefDataConfig
block had a literal '.' in a nucleotide string and an anchor past the end of a
21-nt sequence; two species examples raise on a quarantined catalogue entry
without .allow_curatable_refdata(); a paired-end example asked for a 450-nt
insert on a molecule that is 352-436 nt; an NpBaseModelSpec example passed a
set where a 4x4 matrix belongs; a sequencing-errors block printed the previous
block's record because it never rebound its variable.

Claims that were false rather than stale: productive_only() was documented as
refusing TCR references, and it does not; S5F was attributed to Shapiro rather
than Yaari et al. (2013), and described as concentrating in the CDRs, which its
kernel has no way to do; a paired-end window was said to clip to what is
available, when it raises; sequence case was documented inverted. Quantities
were re-counted rather than adjusted: 40 names in __all__, 106 catalogue
entries of which 80 are quarantined, nine performance workloads, six
estimators, over 120 validated AIRR fields.

n_max and lambda_base are described as the engine now defines them: n_max is
the population a lineage settles at under Beverton-Holt, not a ceiling, and
lambda_base is the Poisson mean for a founder-baseline cell in an empty
germinal center rather than the mean once damping or selection applies. A
wrong-length affinity target is refused, not scored over its prefix.

The determinism promise is stated with its scope: same seed and same
determinism_version gives byte-identical output, checked by the reproducibility
goldens on Linux, macOS and Windows across Python 3.10-3.13, with aarch64
named as shipping a wheel that nothing compares. It previously promised
platform independence with no version and no scope at all.

expand_clones()'s DeprecationWarning appeared on no page; genotypes appeared
nowhere in the README. Both do now. CONTRIBUTING.md said GenAIRR ships two PyPI
packages and that a release updates setup.py; it ships one wheel and there is
no setup.py.

Thirty-seven unwritten pages carried a placeholder linking to a gitignored
internal plan, so every one of those links was a 404 on the published site.
Each now points at the page that actually covers the material.
The changelog leads with the one fact that matters to anyone holding data: a
seed does not reproduce 2.3.1's output any more. DETERMINISM_VERSION moved
through 2, 3 and 4 in this cycle, each increment moving what a seed draws, and
the entry gives a row per version so a stored dataset can be placed. A dataset
with no determinism_version column was drawn by the pre-2.4.0 model.

The breaking section also carries the lineage regulation change -- the same
n_max now settles roughly three times the population it used to cap -- the
expand_clones() deprecation, and the catalogue quarantine that makes 80 of 106
entries refuse to compile without an explicit opt-in.

MIGRATING.md gains a 2.3.1 section ahead of the 1.x guide: keep the file rather
than the seed, convert n_max by dividing by three at the default lambda_base,
and six smaller breakers including pandas no longer arriving with any extra and
summary() returning a dict. Every runnable snippet in it was executed.
The version bump alone fails four tests, which is the guard working: the
packaged reference dossier records the GenAIRR version that generated it, so a
checkout declaring 2.4.0 beside a dossier built by 2.3.1 is a mismatch the
suite refuses. The generator refuses too, until the installed build matches
what pyproject declares, so the dossier cannot be stamped with a version it was
not built by.

This would have broken the release rather than the local run:
build-wheels.yml patches pyproject.toml from the tag and then runs
'pytest tests/ -x -q', and nothing in that workflow can regenerate a 20 MB
artifact. The archive has only existed since 2026-10-27, after the v2.3.1 tag,
so no release has passed through this guard before.

Of the five pinned digests the generator names, two moved: the manifest hash
and the raw archive hash, both of which cover the recorded version. The runtime
execution, catalogue and models hashes and the source lock came back
byte-identical, and the archive is the same 20110025 bytes, which is the
evidence that nothing about the reference build itself changed.

The two retargeted pins are declared for the inventory gate, which cannot see a
constant's new value by hashing bodies.
duplex_compile_benchmark and duplex_family_benchmark import _engine inside the
functions that use it, not at module scope, because they re-enter themselves as
worker subprocesses. The helper added in the previous commit was placed at
module scope and referenced _engine from there, so ruff's F821 rejected both
files and every Python job failed on the lint step. original_end_stress imports
_engine at module scope and was unaffected, which is why only two of the three
were flagged.

The helper now takes the import locally, matching each module's own idiom.
Checked by running all three: each returns src/GenAIRR/_engine.abi3.so.

'make validate-release' does not lint, so this could not fail locally;
'ruff check tests/ src/ tools/' is the command CI runs and now passes.
@MuteJester
MuteJester merged commit 6cdf1cf into master Nov 5, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant