patchcraft 0.5.0__tar.gz → 0.5.2__tar.gz

{patchcraft-0.5.0 → patchcraft-0.5.2}/.gitignore

@@ -3,6 +3,10 @@ __pycache__/
 *.py[cod]
 *$py.class
 *.so
+# Built in place by an editable install (setuptools-rust).
+src/patchcraft/_accel_native*
+# Generated at build time by setuptools-scm.
+src/patchcraft/_version.py
 
 # Distribution / packaging
 build/

{patchcraft-0.5.0 → patchcraft-0.5.2}/CHANGELOG.md

@@ -6,6 +6,200 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-09-03
+
+### Fixed
+
+- **`stitch(weight="hann")` corrupted the corner band of every patch of 99 or
+  more.** The denominator was floored by an absolute `clamp(min=1e-6)` whose
+  comment called it a defensive no-op. It was not: the 2-D hann corner weight
+  is `(pi/(n+1))**4`, which crosses below `1e-6` at patch 99, so the corner
+  band was divided by the floor rather than by the real weight. Measured at
+  640x640, patch 256, stride 128: maximum error 0.94 on data in [0, 1] and 960
+  wrong pixels, identical in float64 because the constant and not the precision
+  was the cause. The floor is now `finfo(dtype).tiny`, the model already used
+  in `metrics.py`, which never reaches a legitimate weight: the smallest 2-D
+  hann corner even at patch 1024 is 8.8e-11. THEORY 9.9 claimed no covered
+  pixel is zeroed by the window, which was true of the window and false of the
+  result.
+- **`reconstruct` returned a view aliasing the caller's patches on a
+  single-patch grid.** Writing to the patches afterwards changed an image the
+  function had already returned, measured as 0.744 becoming 99.0. `extract`
+  guards the mirror image of this case and `reconstruct` did not.
+- **`resize(..., backend="pil")` raised a raw `RuntimeError` on `int8`.** The
+  inbound `clamp(0, 255)` was applied in the input dtype, where the bound 255
+  is unrepresentable, so torch raised `value cannot be converted to type
+  int8_t without overflow` before clamping anything. Every integer dtype now
+  works on both backends, and THEORY 9.4 gained the row for integer tensors on
+  the PIL backend, which it had never specified.
+
+
+### Removed
+
+- The agentic workflow's leftovers. `.superpowers/` at the repository root
+  held 62 files of review diffs and task-progress notes, hidden from
+  `git status` by a nested `.gitignore` containing `*`, so it sat in the tree
+  unseen and reached the 0.5.0 sdist. The three implementation plans under
+  `docs/superpowers/plans/` were 4527 lines of checkbox task lists addressed
+  "For agentic workers", and they shipped to PyPI inside every sdist.
+
+### Added
+
+- `docs/ADR/0004-precision-and-effort-parameters.md`, in `Proposed` status: names the
+  precision policy the library already applies in five places, and designs an `effort=`
+  preset under the constraint that it may change speed and memory but never a returned
+  value. Nothing is implemented; the ADR records the design, the effort per step and the
+  order. It amends ADR 0003 on one measured point, that the exactness predicate is a
+  property of the geometry and the accumulator rather than of the geometry alone.
+- `outreach/`, material for presenting the project publicly, in the shape the
+  sibling projects use: a dated news source at the root and one subfolder per
+  channel, with the rule that no channel text changes before the source does.
+  It publishes no new measurement, and it is pruned from the sdist.
+
+### Changed
+
+- The three design specs that were under `docs/superpowers/specs/` moved to
+  `docs/design/`. They are the record of what was measured before each phase
+  was built, including the spike table that rejected `conv_transpose2d` and
+  `index_add_` before the Rust kernel was written, and Amendment A, which
+  `tests/test_exactness.py` cites for the per-pixel error bound.
+- The sdist is 264 KiB where it was 316 KiB.
+- Nothing ephemeral is kept in the project folder any more. `accel/target`
+  had reached 269 MiB of Rust build output, and `dist/`, `.pytest_cache` and
+  `src/patchcraft.egg-info` were accumulating alongside it. The caches are
+  now redirected by user-level environment variables, joining the ones this
+  machine already had for uv, ruff, mypy, pip and `__pycache__`, and
+  `CONTRIBUTING.md` records the convention and why it is not committed here.
+- `.vscode/settings.json` stays tracked and is pruned from the sdist instead.
+- **The versioning rule was self-contradictory and is corrected.** One row said
+  an output value change is a `0.Y.0`, the next said a fix is a `0.y.Z`, and a
+  bug fix satisfies both, so the table made every fix a minor and left patch
+  releases unable to fix anything. It also contradicted the project's own
+  history: `0.2.1` changed `stitch(weight="hann")` output for every geometry
+  and shipped as a patch. The rule now turns on whether the contract moved or
+  the implementation stopped violating it, which sorts `0.2.1`, `0.3.0`,
+  `0.5.0` and `0.5.2` correctly. `CONTRIBUTING.md` carries the rule with those
+  four worked, and GUIDE section 8 item 6 no longer cites a patch release as
+  an example of what only a minor may do.
+  Its `${workspaceFolder}/.venv` path is not broken: `.venv` is a directory
+  junction to the real environment outside the tree, so the setting resolves
+  and is portable to any checkout following the same convention.
+
+## [0.5.1] - 2026-09-02
+
+> Numbered `0.6.0` while it was being built. Corrected before release: the
+> middle digit is the compatibility boundary, and this release changes no
+> signature, no name and no output value. See the versioning policy and its
+> errata in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+### Changed
+
+- **The native accelerator ships inside this wheel.** It was going to be a
+  second PyPI project, `patchcraft-accel`, reached through
+  `pip install patchcraft[accel]`. That project was never published and now
+  never will be. A release produces one sdist and six wheels for the single
+  `patchcraft` project: five tagged `cp312-abi3-<platform>` with the Rust
+  kernel compiled in as `patchcraft._accel_native`, and one `py3-none-any`
+  for every other platform. Installers prefer the most specific compatible
+  tag, so `pip install patchcraft` picks up the accelerator where one exists
+  and the pure wheel everywhere else, with no extra to remember. The pattern
+  and its universal fallback follow `coverage`, which publishes the same two
+  shapes for one version.
+- The `accel` extra is removed. Nothing depended on it, because it never
+  reached the index.
+- The accelerator is now on by default where a wheel carries it, rather than
+  opt-in. The two paths are bit-identical by test, and `PATCHCRAFT_ACCEL=0`
+  still forces the pure one at runtime.
+- Build backend moves from hatchling to setuptools with setuptools-rust, which
+  is what makes one project able to emit both shapes of wheel. `setup.py`
+  holds the single decision, driven by `PATCHCRAFT_PURE_PYTHON` and
+  `PATCHCRAFT_REQUIRE_EXTENSION`; everything else stays declarative in
+  `pyproject.toml`. Installing from the sdist compiles the extension when a
+  Rust toolchain is present and degrades to a pure install when it is not.
+- License metadata follows PEP 639: the SPDX expression `MIT` with
+  `license-files`, and the superseded `License :: OSI Approved` classifier is
+  gone. setuptools rejects carrying both.
+
+### Added
+
+- **The version comes from the git tag.** `setuptools-scm` derives it at build
+  time, so no file in the source states a version, the release procedure loses
+  its bump step, and a tag and a release can no longer disagree.
+  `patchcraft.__version__` still works: the build writes a generated
+  `_version.py` that `__init__.py` imports, which costs nothing at import time,
+  with `importlib.metadata` as a fallback for a tree that was never built.
+  Measured before choosing: `importlib.metadata` alone was the wrong default,
+  because it took 56 ms on first call and reported a stale version in an
+  editable install.
+- `docs/PERFORMANCE.md`, which is where the accelerator's measurements live.
+  It carries the test machine, the versions, the date, the reproduction
+  command and what the numbers do not say, and its table is pasted from
+  `tools/benchmark.py --markdown` rather than retyped.
+- The Rust kernel is now always built in release mode, including in an
+  editable install. It was following the build command, so a development
+  checkout compiled a debug kernel: measured here, that turned a 14x speedup
+  into 2.1x, which made local benchmarks meaningless and made the accelerated
+  CI job exercise code no user runs.
+- `patchcraft.__version__` is re-exported explicitly, so `mypy --strict` in a
+  consuming project still accepts it. Moving it out of a literal and into an
+  import had quietly made it an implicit re-export, which strict mode rejects.
+- `tools/benchmark.py` measures the accelerated fold against the pure one and
+  refuses to report a timing unless the two results are bit-identical. The
+  numbers in the documentation come from it, and it is the reproduction
+  command they cite.
+- Every build checkout uses `fetch-depth: 0`. The default shallow clone hides
+  the tags, and setuptools-scm's fallback for that is a silent
+  `0.1.dev1+g<sha>`, a version that walks backwards rather than an error.
+- `tools/check_dist.py` grew `--expect-version` and `--require-universal`, and
+  it now rejects any artifact carrying a local version segment. PyPI refuses
+  those on upload, so this turns a late and confusing server-side rejection
+  into an early local one. It also fixes a bug in the job that checks the
+  native wheels, which demanded a universal wheel that job never has.
+- Linux aarch64 wheels, which the previous four-target matrix did not cover.
+- `tools/check_dist.py`, run before every upload. It fails the release if a
+  platform wheel lost its extension, which `optional=True` would otherwise
+  let through as a silently slow wheel, or if the universal wheel gained one.
+- The versioning policy now names the resolver rule it follows, which is that
+  `0.y` is the compatibility boundary in Cargo, npm and PEP 440 alike, and it
+  carries an errata for the two releases numbered before the rule was written.
+- Version numbers are gone from the documentation surface. The three cover
+  pages carry none at all, since the PyPI badge already shows the current
+  release, and the manual keeps only the one the citation entry needs. The
+  release archaeology those pages used to recite lives here, and the rest is
+  in the git history.
+- `MANIFEST.in`, which puts `accel/` in the sdist so the source path can build
+  the extension, and keeps `lab/`, `.superpowers/` and cargo's `target/` out.
+
+- **Corrected: the hand-rolled and library tile-and-blend results are not
+  bit-identical.** The three cover pages and GUIDE section 1 claimed they were,
+  and the GUIDE block asserted it. Re-measured: they agree to 1.17e-05 on a
+  value in [0, 1], differing on 24500 of 49152 elements. The cause is the 0.3.0
+  separable denominator, where `stitch` sums two 1-D window folds while the
+  hand-rolled twin folds a replicated 2-D kernel. `stitch(weight="uniform")`
+  is still bit-identical to `reconstruct`. Nothing about the round-trip
+  contract changed; the documentation was simply asserting more than the code
+  delivered.
+- Documentation corrections found by auditing every page against the code:
+  the changelog's reference links did not define the two most recent versions;
+  `docs/AUXILIARY.md` listed wheel contents that predate three releases;
+  `docs/SCOPE.md` still promised "pure-Python single-threaded", which the
+  rayon-parallel kernel contradicts; `docs/ROADMAP.md` still named hatchling;
+  GUIDE said the library "is not faster", that the no-zstandard branch is
+  untested, and that CI is six cells; the cover pages pointed at `USAGE.md` as
+  a walkthrough of 20 symbols when it covers 18 and says so. `CONTRIBUTING.md`
+  told a contributor to run `pytest` after a `uv sync` that does not install it.
+
+### Notes
+
+- No signature, no name and no output value changed. The public surface is the
+  same 20 names, still pinned by `tests/test_public_api.py`.
+- Measured on torch 2.14, CPU, mean over the dev machine: `reconstruct` at
+  3x512x512 p=32 s=16 goes 11.4 ms to 2.5 ms (4.5x), at 3x2048x2048 p=64 s=32
+  477.9 ms to 31.8 ms (15.0x); `stitch[hann]` 21.6 ms to 7.0 ms (3.1x) and
+  488.7 ms to 38.8 ms (12.6x). The gain is algorithmic rather than a thread
+  count: the pure `F.fold` measured between 365 and 465 ms on that largest
+  case at 4, 8, 16 and 36 torch threads.
+
 ## [0.5.0] - 2026-09-02
 
 ### Added
@@ -472,9 +666,13 @@ First public release. Public API stable; signatures will only change in 1.x.
 - [`README.md`](README.md) covers installation, the car-vs-track metaphor,
   validation lab.
 
-[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.4.0...HEAD
-[0.4.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.4.0
-[0.3.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.3.0
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.2
+[0.5.1]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.1
+[0.5.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.0
+
+<!-- 0.4.0 and 0.3.0 are deliberately unlinked: they are source milestones that
+     were never tagged and never released, as their own entries say. -->
 [0.2.2]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.2
 [0.2.1]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.1
 [0.2.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.0

patchcraft-0.5.2/CONTRIBUTING.md

@@ -0,0 +1,326 @@
+# Contributing to PatchCraft
+
+If you've cloned this repo and want to run the test suite, understand how the project is laid out, or follow the validation conventions, this is the page. For installation and usage, see the [README](README.md).
+
+---
+
+## Run tests
+
+The test runner and the linters live in the `dev` extra, so a plain `uv sync`
+does not install them:
+
+```
+uv sync --locked --extra cache --extra dev
+```
+
+```
+pytest
+pytest -m "not gpu"        # skip GPU-requiring tests
+```
+
+CI runs the full suite on every push and PR. See [`.github/workflows/test.yml`](.github/workflows/test.yml). Matrix is `{ubuntu-latest, windows-latest} × {python 3.12, 3.13, 3.14}` for the pure path, plus a second job on both operating systems for the accelerated one. To run the same checks locally before pushing:
+
+```
+ruff check src tests
+mypy --strict src
+pytest -m "not gpu"
+```
+
+---
+
+## The two paths
+
+The overlapping fold in `reconstruct` and `stitch` has a Rust implementation
+in [`accel/`](accel/), compiled into the wheel on the platforms CI builds for.
+Everything else runs the same operation in torch. The two are bit-identical by
+test, so a contribution has to keep both green rather than pick one.
+
+Which one your checkout runs depends on whether the extension got built:
+
+```
+python -c "import patchcraft; print(patchcraft.accel_available())"
+```
+
+`uv sync --extra cache --extra dev` builds it when a Rust toolchain is on
+PATH, always in release mode. Two environment variables override that, and CI
+sets both explicitly rather than relying on what happens to be installed:
+
+| Variable | Effect |
+|---|---|
+| `PATCHCRAFT_PURE_PYTHON=1` | Skip the extension. How the universal wheel is built. |
+| `PATCHCRAFT_REQUIRE_EXTENSION=1` | Make a Rust build failure fatal instead of degrading to the pure path. |
+| `PATCHCRAFT_ACCEL=0` | Runtime only: ignore an extension that is already built. |
+
+The Rust kernel has its own tests, which need no Python at all:
+
+```
+cargo test --manifest-path accel/Cargo.toml
+```
+
+One local wrinkle worth knowing. If your checkout sits under a path with
+non-ASCII characters, `setuptools-rust` mis-decodes the artifact path that
+cargo reports and the copy step fails. Point the build at an ASCII directory
+and it works:
+
+```
+CARGO_TARGET_DIR=/tmp/pc-target uv sync --extra cache --extra dev
+```
+
+---
+
+## Nothing ephemeral lives in the project folder
+
+Caches, build output and virtual environments are kept off the tree, because
+they are large, regenerable and machine-specific. They are redirected by
+user-level environment variables rather than by anything committed here: a
+machine path in `pyproject.toml` would be wrong for every other machine and
+for CI, which is why one was removed in 0.3.0.
+
+| Variable | Sends |
+|---|---|
+| `CARGO_TARGET_DIR` | the Rust build output, which reached 269 MiB inside `accel/target` before it was redirected |
+| `PYTEST_ADDOPTS=-o cache_dir=...` | `.pytest_cache` |
+| `RUFF_CACHE_DIR`, `MYPY_CACHE_DIR` | the linter caches |
+| `UV_CACHE_DIR`, `PIP_CACHE_DIR` | downloaded wheels |
+| `PYTHONPYCACHEPREFIX` | `__pycache__` |
+
+The virtual environment lives outside the tree too; see
+[`docs/AUXILIARY.md`](docs/AUXILIARY.md).
+
+Two directories still appear during a build and are gitignored: `build/` and
+`src/patchcraft.egg-info/`, both setuptools working state. They exist only
+while you build, and redirecting them would need a machine path in a tracked
+file, which is the thing this section is avoiding.
+
+Three files are written into `src/patchcraft/` by an editable install and
+are gitignored: the compiled `_accel_native`, the generated `_version.py`, and
+`__pycache__`. Those have to be there for the package to import.
+
+---
+
+## Layout
+
+```
+PatchCraft/
+├── pyproject.toml                  package metadata, build backend, cibuildwheel targets
+├── setup.py                        the one build decision: with or without the Rust extension
+├── tools/check_dist.py             gate: extension present, versions agree, tag respected
+├── tools/benchmark.py              accelerated vs pure, and proves they agree first
+├── MANIFEST.in                     what the sdist carries
+├── README.md                       the call page, canonical, English
+├── README.pt-BR.md                 the same call page in Portuguese
+├── README.pypi.md                  the PyPI page (long_description), links absolute
+├── CONTRIBUTING.md                 this file
+├── CHANGELOG.md                    Keep-a-Changelog format
+├── LICENSE                         MIT
+├── .python-version                 3.13
+├── .gitignore                      ignores archive/, venvs, caches, outputs
+├── .github/workflows/
+│   ├── test.yml                    matrix CI on PRs/main, plus the accelerated job
+│   └── release.yml                 publishes to PyPI on vX.Y.Z tag push (Trusted Publishing)
+├── src/patchcraft/                 library core, one-image-at-a-time primitives
+│   ├── __init__.py                 re-exports the full public API and the generated version
+│   ├── extract.py                  patches via strided view or F.unfold; Patchify (ADR 0002)
+│   ├── reconstruct.py              inverse via F.fold + count map, closed-form fast path
+│   ├── stitch.py                   weighted reassembly for modified patches
+│   ├── geometry.py                 pre-flight: num_patches, tilings, scale_factor, paired_tilings
+│   ├── metrics.py                  patch_metrics, per_patch_mse, per_patch_psnr
+│   ├── pair.py                     LR↔HR pairing; PatchPair, PatchMeta
+│   ├── resize.py                   resize with PIL or torch backends
+│   ├── cache.py                    content-addressed disk cache
+│   ├── _accel.py                   bridge to the optional native accelerator, falls back silently
+│   └── _foldgeom.py                shared fold-geometry validation for reconstruct and stitch
+├── accel/                          the Rust crate compiled into this wheel (pyo3, setuptools-rust)
+│   ├── Cargo.toml                  crate metadata; the version there is internal
+│   ├── src/kernel.rs               the gather-fold kernel, pure Rust, cargo-tested
+│   ├── src/lib.rs                  pyo3 glue, exports patchcraft._accel_native
+│   └── README.md                   how to build it, and how to check it is active
+├── tests/                          pytest suite (contract tests for src/)
+│   ├── test_extract.py             extract + Patchify
+│   ├── test_reconstruct.py
+│   ├── test_stitch.py
+│   ├── test_geometry.py            num_patches + tilings + scale_factor + paired_tilings
+│   ├── test_metrics.py
+│   ├── test_pair.py
+│   ├── test_resize.py
+│   ├── test_cache.py
+│   ├── test_exactness.py           falsifies the count-map predicate over the legal space
+│   ├── test_reference.py           naive loop-based reference for the fast paths
+│   ├── test_public_api.py          freezes the 20 names, their signatures and carrier fields
+│   ├── test_accel.py               native path, skipped unless the extension was built
+│   ├── test_datasets_helper.py     label_subset
+│   ├── test_import.py
+│   ├── _rng.py                     audited round-trip helpers (data generation, bit equality)
+│   ├── test_rng.py                 tests for those helpers
+│   └── _datasets.py                dev-only fixtures (MNIST, etc), NOT public API
+├── lab/                            ephemeral experiments; see lab/README.md
+│   ├── README.md                   bench rules (tracked; the scripts themselves are not)
+│   └── .gitignore                  ignores everything else (tracked)
+├── docs/
+│   ├── GUIDE.md                    the manual, every README claim measured with its output
+│   ├── PERFORMANCE.md              what the accelerator is worth, and how to re-measure
+│   ├── USAGE.md                    REPL walkthrough of every public symbol (behind, see B4)
+│   ├── SCOPE.md                    responsibilities matrix + parallelization analysis
+│   ├── AUXILIARY.md                tests/_datasets, lab/, Z:\ conventions (NOT part of the wheel)
+│   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
+│   ├── ROADMAP.md                  milestone plan
+│   ├── FOCO-1.0.md                 what 1.0 freezes and the blockers in the way
+│   ├── ADR/                        one file per decision that shaped the API
+│   ├── STUDIES/                    background reading behind those decisions
+│   └── design/                     one spec per work phase: the alternatives measured and the decision
+├── outreach/                       material for presenting the project publicly, not shipped
+│   ├── README.md                   how it is organized and what to check before publishing
+│   ├── 2026-09-03-lancamento.md    the dated news source every channel text derives from
+│   └── linkedin/                   post (short) and artigo (long), each in PT and EN
+└── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
+```
+
+---
+
+## Validation lab
+
+The library is "one image in, one tensor out" by design, but you only know it works once you run it end-to-end on real images. That happens in two places, neither of which is part of the shipped package:
+
+- [`tests/`](tests/) holds the formal pytest suite that defines the contract from [`docs/THEORY.md`](docs/THEORY.md) §9.
+- [`lab/`](lab/) holds ephemeral scripts and notebooks for fast hypothesis-checking. See [`lab/README.md`](lab/README.md) for the bench rules; outputs go to `Z:\outputs\patchcraft\` (off-tree).
+
+Datasets used by tests/lab are downloaded lazily into `Z:\caches\datasets\<name>\` on first use; they do not ship with the package and are never bundled into the wheel.
+
+The dev framework that makes this all work (fixtures, dataset helpers, `Z:\` conventions) is documented in [`docs/AUXILIARY.md`](docs/AUXILIARY.md).
+
+---
+
+## Versioning policy
+
+The scheme is [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html),
+expressed in the [PEP 440](https://peps.python.org/pep-0440/) form that PyPI
+accepts. Two rules matter more than the arithmetic, because both were broken
+once and both cost work to undo.
+
+**The number names a published artifact, not a unit of work.** Finishing a
+phase, merging a branch and landing a refactor are not releases, and none of
+them touches `__version__`. Everything between releases accumulates under
+`[Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md), and the number is assigned
+in the release commit itself. Versions 0.3.0 and 0.4.0 came from the opposite
+habit: each internal work phase minted a minor, so three numbers existed
+before any of them reached PyPI.
+
+**A published version is frozen.** PyPI refuses a filename it has already
+seen, so a version that shipped can only be superseded, never edited. That is
+also why a failed pipeline never costs a number: `skip-existing` makes the
+upload a no-op and the same tag can be re-run.
+
+**While the project is pre-1.0, the middle digit is the compatibility
+boundary.** SemVer itself leaves `0.y.z` open, saying only that "anything MAY
+change at any time", so the meaning comes from the resolvers instead, and they
+agree: Cargo expands `^0.2.3` to `>=0.2.3, <0.3.0`, npm does the same, and
+PEP 440's `~=0.5.0` means `>=0.5.0, <0.6.0`. In every one of them a `0.y` bump
+is the announcement that something may break, and a `0.y.z` bump is the
+promise that nothing does.
+
+That fixes what each digit is for here:
+
+The question that decides it is not "did a returned value change". A bug fix
+changes returned values by definition, and if that forced a `0.Y.0` then a
+patch release could never fix anything. The question is **whether the contract
+moved, or whether the implementation stopped violating it**:
+
+| Change | Bump | Why |
+|---|---|---|
+| The documented contract moves: a signature, a name, or behaviour the documentation described as correct | `0.Y.0` | Code that was right against the old documentation can now be wrong |
+| The implementation stops violating the contract, however visibly | `0.y.Z` | The documentation always promised this; only the code was wrong |
+| New functionality that breaks nothing | `0.y.Z` | Anyone pinned to the y-series should get it |
+| Documentation, tests, CI, packaging or tooling only | `0.y.Z` | Still a release if it is published, still no break |
+| Nothing published | nothing | Accumulate under `[Unreleased]` |
+
+The project's own history sorts cleanly under that rule, and does not sort
+under any rule keyed on whether values changed:
+
+- `0.2.1` rewrote the hann window, changing `stitch(weight="hann")` output for
+  **every** geometry. THEORY §9.9 had promised no covered pixel is zeroed by
+  the window; the old window zeroed 108 of 144 pixels in one measured case. A
+  violation, so a **z**, and it shipped as one.
+- `0.5.2` floored the `stitch` denominator by the dtype's tiny instead of an
+  absolute `1e-6`, changing hann output at patch 99 and above. The same
+  promise, the same kind of violation, so also a **z**.
+- `0.3.0` moved `stitch` output by ULPs through a different summation order.
+  Nothing was wrong before, so behaviour the documentation endorsed changed.
+  A **y**.
+- `0.5.0` made `tilings` return 73 specs where it returned 100. The
+  enumeration's output set is the contract. A **y**.
+
+After 1.0 the ordinary reading applies: breaking is major, additive is minor,
+fixed is patch. What 1.0 freezes is written in
+[`docs/FOCO-1.0.md`](docs/FOCO-1.0.md).
+
+### Errata
+
+The rule above was written after the fact, and two releases predate it.
+
+`0.4.0` should have been `0.3.1`. It added `accel_available()` and nothing
+else: no signature changed, and the accelerated path was bit-exact against the
+pure one. Additive and non-breaking is a z-bump under the boundary rule, and
+minting a y announced a break that never happened.
+
+`0.5.1` was briefly numbered `0.6.0` before release. It changes only how the
+package is built and shipped, so it is a z-bump.
+
+Two others were right and are worth recording as the shape to copy. `0.3.0`
+moved `stitch` output by ULPs through a different summation order, which is an
+output change and belongs at a y boundary. `0.5.0` made `tilings` return 73
+specs where it returned 100, which is squarely a break.
+
+The accelerator in [`accel/`](accel/) has no version of its own to manage. It
+is compiled into this wheel, so it ships when `patchcraft` ships. The version
+in `accel/Cargo.toml` is internal and nothing reads it; what the Python side
+actually checks is `_ABI_VERSION` in `accel/src/lib.rs`, and a mismatch there
+means a silent fall back to the pure path rather than a crash.
+
+---
+
+## Where the version comes from
+
+The git tag, and nowhere else. `setuptools-scm` derives it at build time, so
+no file in the source states a version and there is no literal to forget.
+`v0.5.1` produces `0.5.1`; the leading `v` is stripped for you.
+
+At build time setuptools-scm writes `src/patchcraft/_version.py`, which
+`__init__.py` imports and re-exports as `patchcraft.__version__`. That file is
+generated and gitignored, so a checkout that was never built falls back to
+`importlib.metadata` and then to `0+unknown`. The fallback exists so an
+un-built tree still imports; it is not a supported way to learn the version.
+
+Anything other than a clean tree sitting exactly on a tag produces a version
+with a local segment, like `0.5.2.dev0+gb4edfd81.d20260902` from a dirty tree
+or `0.1.dev1+gb4edfd81` from a checkout whose tags were never fetched. PyPI
+refuses local segments outright, so such a build can never be published by
+accident, and `tools/check_dist.py` rejects it before the upload rather than
+letting the upload fail.
+
+That last point is why every `actions/checkout` that builds uses
+`fetch-depth: 0`. The default shallow clone hides the tags, and the failure is
+silent: a version that walks backwards rather than an error.
+
+---
+
+## Releasing (maintainer only)
+
+1. Close the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) as `[X.Y.Z] YYYY-MM-DD`.
+2. Update the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9. It is the one version string left in the documentation, because a citation needs a concrete one.
+3. Update [`docs/ROADMAP.md`](docs/ROADMAP.md) milestone checkboxes.
+4. Commit: `release: vX.Y.Z`.
+5. Tag + push: `git tag -a vX.Y.Z -m "..."` then `git push origin vX.Y.Z`.
+6. `release.yml` fires automatically: validates, builds, publishes to PyPI via Trusted Publishing, then creates the GitHub Release with every artifact attached.
+
+There is no version to bump in step 4, and no way for a tag and a release to
+disagree. The `validate` job still cross-checks that setuptools-scm derived
+exactly what the tag says, which catches a dirty or shallow checkout before
+anything is built.
+
+One release produces one sdist and six wheels: five `cp312-abi3-<platform>`
+wheels with the Rust extension inside, and one `py3-none-any` wheel for
+everywhere else. `tools/check_dist.py` runs before the upload and fails the
+release if a platform wheel lost its extension, if the universal wheel gained
+one, if the artifacts disagree about the version, or if any of them is not the
+version the tag names. Publishing is a single project, so there is nothing to
+register on PyPI beyond the publisher that already exists.

patchcraft-0.5.2/MANIFEST.in

@@ -0,0 +1,39 @@
+# The sdist is the reproducible source snapshot: the product (`src/`, `accel/`)
+# plus the track that proves it works (`tests/`, `docs/`). `accel/` has to be
+# here, because an sdist build compiles it when a Rust toolchain is present.
+#
+# The `prune` lines below are load-bearing rather than decorative, and the
+# reason changed with setuptools-scm. Its file finder offers every git-tracked
+# file to the sdist, so this file stopped being an allowlist and became a
+# blocklist over everything git knows about. Measured: with no prune for it,
+# `.vscode/settings.json` reached the sdist.
+#
+# Note that `lab/` is only *mostly* ignored: `lab/README.md` and
+# `lab/.gitignore` are tracked, so the finder offers them and the prune is what
+# stops them. The rest of `lab/` is scratch work that no commit can reproduce,
+# and patchcraft-0.2.0.tar.gz shipped three such files to PyPI.
+#
+# Adding a tracked directory to this repository ships it to PyPI by default.
+# `tools/check_dist.py` holds the matching allowlist and will fail the release
+# for anything unexpected, which is the reminder to come back here.
+
+include LICENSE
+include CHANGELOG.md CONTRIBUTING.md
+include README.md README.pt-BR.md README.pypi.md
+include pyproject.toml setup.py uv.lock .python-version
+
+recursive-include src *.py
+include src/patchcraft/py.typed
+recursive-include tests *.py
+recursive-include docs *.md
+recursive-include accel *.rs *.toml *.lock *.md
+prune accel/target
+recursive-include tools *.py
+
+prune lab
+prune archive
+prune .github
+prune .vscode
+# Presentation material, not source. It is tracked, so the file finder offers
+# it and only this line keeps it out.
+prune outreach