patchcraft 0.2.2__tar.gz → 0.5.1__tar.gz

{patchcraft-0.2.2 → patchcraft-0.5.1}/.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/
@@ -53,3 +57,6 @@ runs/
 
 # Datasets and caches live on Z:
 data/
+
+# Rust accelerator build artifacts (accel/Cargo.lock IS committed)
+accel/target/

{patchcraft-0.2.2 → patchcraft-0.5.1}/CHANGELOG.md

@@ -6,8 +6,280 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+
+- Python 3.14 is supported and declared. The classifiers list it, the CI
+  matrix runs the full suite plus `ruff check` and `mypy --strict` against it
+  on Ubuntu and Windows, and all six cells are green. The floor stays at 3.12
+  because `cache.py` uses PEP 695 generic syntax, which 3.11 cannot parse.
+
+### Changed
+
+- `tilings`/`paired_tilings` no longer emit degenerate single-patch overlap
+  specs: with one patch the stride is unobservable and the spec duplicated
+  the exact tile. `tilings((28, 28), allow_overlap=True)` now returns 73
+  specs instead of 100; `paired_tilings((14, 14), (28, 28), allow_overlap=True)`
+  returns 27 instead of 40.
+- The development lock moved to torch 2.14.0 and torchvision 0.29.0, with the
+  linters and the rest of the toolchain along with it. The full
+  126,736-geometry exactness sweep passes on torch 2.14, so the count-map
+  contract is unchanged by the upgrade. Runtime requirements are untouched and
+  stay at `torch>=2.6`.
+
 ### Fixed
 
+- **Public retraction: the documented exactness boundary was wrong.** The old
+  wording (`k_max <= 4`, "`stride == patch_size / 2`", "within ~1 ULP" outside
+  the rule) was measured false: the error grows with the pixel's coverage
+  count (up to 19 ULP at count 81 in float32). The correct contract
+  (ADR 0003): the `extract`/`reconstruct` round trip is bit-exact iff every
+  value of the overlap count map is a power of two, which is always true
+  at `stride == patch_size`, and outside the rule the per-pixel error is
+  bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count.
+  Docstrings and docs (SCOPE, THEORY, GUIDE, USAGE, READMEs) now state this
+  form; THEORY §9.1 records the extract-truncates / reconstruct-rejects
+  asymmetry.
+- Packaging: the sdist no longer carries `.superpowers/`, an untracked
+  directory of agent tooling that hatchling swept in (62 files). The same
+  class of leak as the `lab/` files that reached PyPI in 0.2.0.
+- Documentation: GUIDE section 6 still printed the pre-0.5.0 enumeration
+  output and described the single-patch duplicates as an open wart; section 7
+  asserted `__version__ == "0.4.0"`; section 8 and the BibTeX entry quoted
+  0.4.0 and its test counts. All four now match the release.
+- Prose: the em-dashes that entered the docstrings, docs and tests during
+  0.3.0 to 0.5.0 are rewritten as ordinary sentences, per the project's
+  writing rule.
+- Test suite: round-trip assertions now run on seeded full-mantissa noise
+  (integer ramps and widened-float32 data could mask ULP-level errors); a
+  falsification suite (`tests/test_exactness.py`) enumerates the 126,736
+  legal geometries, samples 256 (seeded; full sweep via
+  `PATCHCRAFT_SWEEP_FULL=1`), and pins both halves of the predicate; a naive
+  loop-based reference (`tests/test_reference.py`) cross-checks the fast
+  paths; the 20-name public surface is frozen by `tests/test_public_api.py`;
+  the no-`zstandard` cache branch is now covered.
+
+### Notes
+
+- No signature changed. The public surface is exactly the 20 names of 0.4.0,
+  now pinned by test.
+
+## [0.4.0] - 2026-09-01
+
+> Source milestone, never uploaded to PyPI. Its contents reached
+> users inside 0.5.0. See the versioning policy in
+> [`CONTRIBUTING.md`](CONTRIBUTING.md) for why the number was minted
+> early and why that no longer happens.
+
+
+### Added
+
+- Optional native accelerator `patchcraft-accel` (`pip install patchcraft[accel]`):
+  a Rust/pyo3 kernel for the overlap fold of `reconstruct`/`stitch`. Prebuilt
+  abi3 wheels (Python 3.12+) for Windows x64, Linux x86_64 (manylinux), macOS
+  arm64 and macOS x86_64; self-contained, no system dependencies, no torch
+  linkage. When it is absent, ABI-mismatched, ineligible (CUDA/integer
+  tensors), or disabled via `PATCHCRAFT_ACCEL=0`, every path falls back
+  silently to pure torch.
+- `patchcraft.accel_available()` reports whether the accelerator is active.
+
+### Performance
+
+- Overlap fold with the accelerator, mean of `lab/bench_phase2.py` on the
+  dev machine: reconstruct 3x512x512 p=32 s=16 17.727 ms -> 2.609 ms (6.80x);
+  stitch[hann] same geometry 23.714 ms -> 8.894 ms (2.67x); 3x2048x2048 p=64
+  s=32 reconstruct 469.814 ms -> 32.458 ms (14.47x). The accelerated `stitch`
+  also skips the full pre-multiply pass over the patches tensor.
+
+### Notes
+
+- Numeric equivalence accel vs pure: bit-exact (`torch.equal`) across the
+  test grid (overlap x rectangular x stride∤patch x C in {1,3,4} x f32/f64).
+- Linux validation: wheel
+  `patchcraft_accel-0.1.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl`
+  installed and the test suite passed accelerated on Ubuntu 26.04 (WSL),
+  built via the manylinux maturin container.
+
+## [0.3.0] - 2026-09-01
+
+> Source milestone, never uploaded to PyPI. Its contents reached
+> users inside 0.5.0. See the versioning policy in
+> [`CONTRIBUTING.md`](CONTRIBUTING.md) for why the number was minted
+> early and why that no longer happens.
+
+
+### Performance
+
+- `extract` uses a strided-window view (`Tensor.unfold`) for `dilation == 1`,
+  one copy instead of im2col + permute-contiguous: 13-21x faster on CPU,
+  bit-exact. `dilation > 1` still uses `F.unfold`.
+- `reconstruct` skips `F.fold` entirely on non-overlapping grids (a pure
+  rearrangement, 27x faster on CPU) and computes the overlap count map in
+  closed form O(H+W) instead of folding a tensor of ones.
+- `stitch` builds its denominator from two 1-D window folds (the kernels are
+  separable) instead of a second 2-D `F.fold`. `uniform` stays bit-exact vs
+  `reconstruct`; `hann`/`gaussian` may differ by ULPs (summation order).
+- `patch_metrics`/`per_patch_mse` materialize one f64 tensor instead of
+  three and sync the device once instead of three times.
+
+### Fixed
+
+- `resize` with `backend="pil"` clamped integer tensors to the uint8 range
+  before casting; values outside [0, 255] used to wrap (300 became 44).
+- Removed the machine-local `cache_dir = "Z:\caches\pytest"` from
+  `pyproject.toml` (created a literal `Z:\caches\...` directory on
+  Linux/macOS).
+
+### Documentation
+
+- Corrected stale 0.2.1 version strings on all cover pages and in GUIDE.
+- Corrected the gaussian-kernel floor claim in `stitch` (exp(-4) at corners,
+  not exp(-2) everywhere).
+- Corrected the bit-exactness rule in THEORY/USAGE (power-of-two count map).
+- SCOPE §4.4 no longer claims `reconstruct` lacks a dtype guard.
+- CHANGELOG: link targets for [Unreleased], [0.2.2], [0.2.1].
+
+### Internal
+
+- `reconstruct`/`stitch` share one fold-geometry validator
+  (`patchcraft._foldgeom.check_fold_geometry`); error messages unchanged.
+
+## [0.2.2] - 2026-08-30
+
+Documentation release. No behaviour changes, so every call that worked on 0.2.1
+works identically here, and the only file under `src/` that changed is a
+docstring.
+
+### Fixed
+
+- **`reconstruct`'s docstring claimed the overlap round trip returns the
+  original image.** It said each pixel comes back as "the average of all patches
+  covering it, the same as the original when patches came from `extract`
+  unmodified". The second half is false. Measured on a 16x16 image with
+  `patch_size=4, stride=1`, unmodified patches straight from `extract` come back
+  with `torch.equal` False and a maximum absolute error of 2.4e-07 in float32.
+
+  The docstring now states the real rule: the round trip is bit-exact when every
+  value in the count map is a power of two, because dividing a float by a power
+  of two is the one division that never rounds. It also says that widening the
+  dtype does not rescue it, since the deciding axis is the geometry rather than
+  the precision.
 - **`pair()`'s docstring double-applied the stride, and could silently
   misplace every patch for a caller who trusted it.** It said patch `k` has
   its top-left at LR pixel `(row * sh_lr, col * sw_lr)`, but `PatchMeta.row`
@@ -37,32 +309,11 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   Reported from an API review done for the QSR prototype, which uses patch
   position as a context feature.
 
-## [0.2.2] 2026-08-30
-
-Documentation release. No behaviour changes, so every call that worked on 0.2.1
-works identically here, and the only file under `src/` that changed is a
-docstring.
-
-### Fixed
-
-- **`reconstruct`'s docstring claimed the overlap round trip returns the
-  original image.** It said each pixel comes back as "the average of all patches
-  covering it, the same as the original when patches came from `extract`
-  unmodified". The second half is false. Measured on a 16x16 image with
-  `patch_size=4, stride=1`, unmodified patches straight from `extract` come back
-  with `torch.equal` False and a maximum absolute error of 2.4e-07 in float32.
-
-  The docstring now states the real rule: the round trip is bit-exact when every
-  value in the count map is a power of two, because dividing a float by a power
-  of two is the one division that never rounds. It also says that widening the
-  dtype does not rescue it, since the deciding axis is the geometry rather than
-  the precision.
-
 ### Changed
 
 - **The README is now a call page and the manual moved to `docs/GUIDE.md`.** The
   README had reached 864 lines, which made it a manual printed on the front
-  door. It is 137 lines now, and it answers what the library is, where you are
+  door. It is 156 lines now, and it answers what the library is, where you are
   getting into, and which of `reconstruct` or `stitch` you want. Nothing was
   discarded: every measurement, table and long example moved into the guide,
   which gained its own table of contents.
@@ -233,7 +484,7 @@ kernel so each pixel "trusts" patches closer to its center more.
   on overlap). With `"hann"` it strongly suppresses seams at the
   cost of zeroing image corners that fall on Hann's edge-weight-zero
   region (documented artifact). With `"gaussian"`
-  (`sigma = max(1, min(ph, pw) / 4)`) it blends smoothly with no
+  (per-axis `sigma = max(1.0, n / 4.0)`) it blends smoothly with no
   corner artifact.
 
 Floating-point patches only, because window kernels are float-valued and we
@@ -336,5 +587,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.5.1...HEAD
+[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
 [0.1.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.1.0

patchcraft-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# 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
+```
+
+---
+
+## 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
+│   └── superpowers/                the design specs and implementation plans per work phase
+└── 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:
+
+| Change | Bump | Why |
+|---|---|---|
+| An output value, a signature, a name or documented behaviour changes | `0.Y.0` | Resolvers stop at the y boundary, so this is where a break belongs |
+| New functionality that breaks nothing, or a fix | `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]` |
+
+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.1/MANIFEST.in

@@ -0,0 +1,37 @@
+# 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 .superpowers
+prune .github
+prune .vscode