patchcraft 0.5.5__tar.gz → 0.5.6__tar.gz

{patchcraft-0.5.5 → patchcraft-0.5.6}/.pre-commit-config.yaml

@@ -1,8 +1,8 @@
 # Runs the gates CI runs, before the commit rather than after it.
 #
 # Deliberately absent: `ruff-format`. This project has never used it and
-# adopting it here would reformat 36 of 65 files in a commit that changed no
-# behaviour. `ruff check` is the gate; formatting is not.
+# adopting it here would reformat about half the tree (CONTRIBUTING.md has the
+# count) in a commit that changed no behaviour. `ruff check` is the gate; formatting is not.
 #
 # `mypy` runs through the project environment rather than through a pre-commit
 # virtualenv, because it needs torch to resolve any annotation in `src/` and

{patchcraft-0.5.5 → patchcraft-0.5.6}/AGENTS.md

@@ -128,9 +128,11 @@ connectives; one idea per paragraph. `README.md` is a call page, not a manual:
 the manual is [`docs/GUIDE.md`](docs/GUIDE.md), and complex examples belong
 there.
 
-Documents that state a version go stale. There is exactly one version string
-left in the documentation, the BibTeX entry in GUIDE section 9, plus
-[`CITATION.cff`](CITATION.cff). Do not add a third.
+Documents that state a version go stale. A release bumps three: the BibTeX
+entry in GUIDE section 9, [`CITATION.cff`](CITATION.cff), and the release
+named at the top of [`STATUS.md`](STATUS.md). [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md)
+names the version it measured, and changes only when it is re-measured. Do
+not add another.
 
 ## 2. Before you touch anything
 

{patchcraft-0.5.5 → patchcraft-0.5.6}/CHANGELOG.md

@@ -6,6 +6,158 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.6] - 2026-10-10
+
+A fix release. `torch.vmap` works again over `extract`, `reconstruct` and
+`stitch`, which it had not since 0.5.0, and `tilings` returns `[]` for an
+image smaller than the default minimum patch instead of raising. No other
+returned value changes. The full suite passes on both code paths at the
+declared floor (Python 3.12, torch 2.6.0, numpy 1.26.0, pillow 10.1.0, Rust
+1.82) and at the newest releases (Python 3.14, torch 2.14.1, numpy 2.5.4,
+pillow 12.3.0), and the 126,736-geometry exactness sweep passes on both paths.
+The rest is documentation, a CI job that now holds the floor to that claim,
+and the CI actions moved to Node 24.
+
+### Added
+
+- `docs/PAPER/`, the scaffold of an article on computing a mean whose every
+  intermediate stays in the input's domain, drawing on PatchCraft's
+  patch-grid mean: outline, formal statements with proofs, measurements with
+  the scripts that reproduce them, and checked references. It is not
+  documentation of the library and does not ship: `MANIFEST.in` prunes it and
+  `tools/check_dist.py` fails a release that carries it.
+- **CI tests the declared floor, not only the newest versions.** A new job
+  builds the extension with Rust 1.82 and runs the whole suite on both code
+  paths at Python 3.12, torch 2.6.0, numpy 1.26.0 and pillow 10.1.0, the
+  oldest versions `pyproject.toml` and `Cargo.toml` accept that install on
+  3.12; until now the floor was a claim no job exercised. The lock moves to
+  the newest runtime releases (torch 2.14.1, torchvision 0.29.1, numpy
+  2.5.4), so the other jobs test the top of the range; the development tools
+  stay pinned. The first run at the floor found one claim that held only at
+  the top: `extract` on an integer tensor raises torch's own error, which is a
+  `RuntimeError` at torch 2.6 and its subclass `NotImplementedError` in newer
+  releases, while the test, THEORY §9.1 and the PyPI page named the subclass.
+  They now name what holds across the range.
+- ADR 0005 is recorded in the ROADMAP as the 1.1 candidate, not scheduled.
+- ADR 0005 (`Proposed`) records how a grid that does not cover the image
+  would be padded, borrowed rather than designed: kornia's auto-padding on the
+  way in and unpadding on the way back, MONAI's `padding_mode` with `F.pad`'s
+  values, the padding split between both sides, and `None` as the default
+  that changes no call. Nothing is implemented. The survey and the
+  measurements behind it are in `docs/STUDIES/2026-10-10-border-policy.md`,
+  reproduced by `tools/compare_border_strategies.py`.
+- **THEORY §2.6 states the operator behind `reconstruct` and `stitch`.**
+  `extract` is a selection matrix `U`, the fold is `Uᵀ`, `UᵀU` is the count
+  map, `reconstruct` is the least-squares inverse `(UᵀU)⁻¹Uᵀ` and `stitch` the
+  window-weighted one, the same weighted overlap-add that inverts an STFT.
+  `tests/test_operator.py` pins each statement on both code paths. GUIDE
+  gains three recipes built on it, run against 0.5.5: what averaging does to a
+  per-patch quantization (§2), a filter applied per tile with a halo, which
+  comes back bit-identical to the whole-image filter (§5), and the padded
+  round trip for a frame no tiling covers (§6). Section 6 used to rule
+  padding out because it puts pixels the frame never had into the edge
+  patches; it now offers it with that cost stated.
+
+### Fixed
+
+- **`torch.vmap` works again over `extract`, `reconstruct` and `stitch`.** The
+  documentation names vmap as one of the three ways to batch (README, SCOPE,
+  USAGE, THEORY §0 and §9.1), and since 0.5.0 it failed on most calls: `extract`
+  at every geometry without dilation and `reconstruct` at `stride ==
+  patch_size` asked the tensor for its storage to guard against aliasing, which
+  a vmap batched tensor does not have, and with the accelerator every
+  overlapping `reconstruct` and `stitch` failed reading a data pointer. Both
+  guards are now an unconditional clone, which is the one copy those paths
+  always made, and the accelerator treats a tensor without storage as
+  ineligible and hands it to the torch path, as its docstring already said.
+  Bit-identical to 0.5.5 on ordinary calls in 144 comparisons per path,
+  including the degenerate geometries the guard existed for, with no output
+  sharing memory with its input and no change in time. `tests/test_vmap.py`
+  pins vmap to a plain loop bit for bit, on both paths and in four dtypes; 70
+  of its 114 cases fail against 0.5.5. The test helper `bit_equal` gained
+  bfloat16.
+- **`tilings` returns `[]` for an image smaller than the default minimum
+  patch.** A one-row image raised `min_patch_size (2) > max_patch_size (1)`,
+  blaming a bound the caller never passed, while THEORY §9.6 accepts any
+  positive shape and an explicit bound that excludes every patch already
+  returned `[]`. An explicit `max_patch_size` below `min_patch_size` still
+  raises. The docstring no longer promises at least one entry, which was false
+  for both cases.
+
+### Changed
+
+- **CI actions moved off Node 20**, which GitHub has deprecated and was
+  forcing onto Node 24: `actions/checkout` v5, `astral-sh/setup-uv` v7,
+  `actions/upload-artifact` v6, `actions/download-artifact` v7 and
+  `softprops/action-gh-release` v3, each the first major on Node 24 rather
+  than the newest. Every input the workflows pass exists in those versions.
+- **USAGE walks a 4×4 image through every call.** Its sections now show
+  the pixels, not only the shapes: the patches `extract` returns and their
+  order, where each patch lands in `reconstruct`, the per-pixel mean when
+  patches disagree, the step `uniform` leaves and the ramp `hann` and
+  `gaussian` make, an LR patch beside its HR patch in `pair`, a resize down
+  and back up, and the one patch `per_patch_mse` singles out. Every example
+  runs as a doctest. GUIDE §1 shows the uncovered band on a 5×5 count map, and
+  GUIDE §4 shows the count map beside the pixels that come back different.
+- GUIDE §4 still gave the old reason for the exactness rule, that division by
+  a power of two is exact; it now gives the corrected one, as the other pages
+  do since the entry below.
+- **The stated reason for the exactness rule is corrected.** The pages said the
+  round trip is exact because dividing a float by a power of two never rounds.
+  That leaves out the sum: k equal values added one at a time and divided by k
+  come back exact for k = 2 and 4, and for k = 8 they do not, since 3x, 5x, 6x
+  and 7x round (3,914,684 of the 8,388,608 float32 values in [1, 2) fail,
+  `python docs/PAPER/experiments/float_mean.py`). The rule itself stands,
+  because a coverage of three on either axis puts a 3 in the map, so over all
+  126,736 legal geometries a map of powers of two holds only 1, 2 and 4. The
+  READMEs, THEORY §1, the `reconstruct` docstring, ADR 0003 (with a dated
+  correction) and the outreach sources now give that reason.
+- Exact inside the rule means equal as values, which is what `torch.equal`
+  checks, and THEORY and the `reconstruct` docstring now say so: the fold sums
+  into `+0.0`, so on an overlapping grid a `-0.0` comes back `+0.0` and a NaN
+  may change its bits. Both paths do the same, and a test now pins it, which
+  `torch.equal` could not.
+- THEORY §9.2 said promotion cut the bfloat16 error from 9.3e-03 to 1.9e-03.
+  Those two numbers measured the input's cast from float32, not the library:
+  on data drawn in bfloat16 the native fold misses by 7.8e-03 and the promoted
+  round trip returns the input bit for bit, at counts 3, 6 and 9. THEORY,
+  GUIDE and the code comment now say so, and a test pins it.
+- THEORY §2 and §2.5 and USAGE §5 described the `reconstruct` and `stitch`
+  implementation from before 0.5.0 (a second fold of ones, a floor on every
+  denominator). They now describe the closed-form count map, the separable
+  window denominator and the non-overlapping rearrangement. USAGE §5 checks
+  the overlapping round trip with `torch.equal` instead of `torch.allclose`.
+- THEORY §9.6 said `tilings` returns a sorted list. Its order is patch size
+  ascending with the exact tile first, which `sorted()` does not give, and a
+  test now pins it.
+- The accelerator parity tests compare bits instead of `torch.equal`, and
+  include `stride == patch_size`, where hann and gaussian still fold now that
+  uniform takes the fast path.
+- Errata for 0.5.5, whose entry says it "changes no bit": that holds for
+  returned values in eager mode. Under the uniform window at `stride ==
+  patch_size`, derivatives pass a `-0.0` or a signaling NaN through unchanged
+  and `torch.compile` folds the `+ 0.0` away; the code comment now says so.
+- **Documentation that said more than the code does.** GUIDE called hann the
+  cheapest window, where on an overlapping grid the three cost the same; GUIDE
+  and the PyPI page said `extract` hands every tensor to `F.unfold`, where only
+  an integer one goes there; PERFORMANCE said 25 runs where the benchmark
+  takes 15; GUIDE's two bound figures now read as the measured misses inside
+  the `(k+1)·eps·|v|` bound, with the shape of the fp16 example stated.
+  FOCO-1.0 freezes values rather than bits, the bound rather than "1 ULP",
+  and 20 names. CONTRIBUTING and AGENTS name the three version strings a
+  release bumps, STATUS among them. The CITATION abstract no longer carries
+  development history, and the BibTeX author reads `Marques de Souza`.
+- `tools/compare_exactness_rules.py` also reports the worst miss outside the
+  rule: 19.0 ULP in float32, at `(h, w, ph, pw, sh, sw) = (18, 23, 9, 9, 1,
+  1)`, on a pixel covered 81 times. CI's ruff step checks `tools/` as well.
+- Outreach: a news source dated 2026-10-10 carries the 0.5.5 table, and the
+  2026-09-04 one stays as the record of 0.5.4. The articles follow it, scope
+  the 19 ULP figure to the geometry that produced it, and say where each path
+  was executed instead of calling the GPU path correct. The post no longer
+  says `extract` validates the geometry, the MNIST page states when each of
+  the three problems appears, and every reproduction block clones the
+  repository, since the wheel carries neither `tools/` nor `tests/`.
+
 ## [0.5.5] - 2026-09-26
 
 A performance release that changes no bit. Every change to `src/` below was
@@ -1016,7 +1168,8 @@ 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.5...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.6...HEAD
+[0.5.6]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.6
 [0.5.5]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.5
 [0.5.4]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.4
 [0.5.3]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.3

{patchcraft-0.5.5 → patchcraft-0.5.6}/CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - given-names: Leonardo
     family-names: Marques de Souza
     email: leonardo.marques.souza@gmail.com
-version: "0.5.5"
-date-released: "2026-09-26"
+version: "0.5.6"
+date-released: "2026-10-10"
 repository-code: "https://github.com/LeoPR/PatchCraft"
 license: MIT
 abstract: >
@@ -28,10 +28,9 @@ abstract: >
   every value of the overlap coverage map is a power of two, always true at
   stride equal to patch size, and outside that rule the per-pixel error is
   bounded by (k+1) times eps times the absolute value, with k the pixel's
-  coverage count. An earlier and weaker form of that claim was published, then
-  measured false and publicly retracted; a falsification suite now enumerates
-  the 126,736 legal geometries of the space independently of the predicate and
-  tries to break both halves of it.
+  coverage count. A falsification suite enumerates the 126,736 legal
+  geometries of the space independently of the predicate and tries to break
+  both halves of it.
 
   Five of the six published wheels carry a Rust kernel for the overlapping
   fold, compiled into the wheel itself rather than into a separate package, and

{patchcraft-0.5.5 → patchcraft-0.5.6}/CONTRIBUTING.md

@@ -34,7 +34,7 @@ is silently inert here. Either make that global hook delegate, or set
 whatever else the global hooks were doing.
 
 `ruff-format` is deliberately not among the hooks. This project has never used
-it, and adopting it would reformat 37 of 82 files in a commit that changed no
+it, and adopting it would reformat 37 files in a commit that changed no
 behaviour.
 
 ```
@@ -153,7 +153,7 @@ PatchCraft/
 │   ├── ISSUE_TEMPLATE/             four forms and a chooser; the required fields are what makes a report reproducible
 │   ├── PULL_REQUEST_TEMPLATE.md    asks whether a returned value moved, which decides the version bump
 │   └── workflows/
-│   ├── test.yml                    matrix CI on PRs/main, plus the accelerated job
+│   ├── test.yml                    matrix CI on PRs/main, plus the accelerated and floor jobs
 │   └── 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
@@ -207,11 +207,12 @@ PatchCraft/
 │   ├── FOCO-1.0.md                 what 1.0 freezes, and the six blockers, all closed
 │   ├── ADR/                        one file per decision; the choice only, evidence in STUDIES/
 │   ├── STUDIES/                    background reading behind those decisions
-│   └── design/                     one spec per work phase: the alternatives measured and the decision
+│   ├── design/                     one spec per work phase: the alternatives measured and the decision
+│   └── PAPER/                      an article in preparation, with its experiments; not shipped
 ├── outreach/                       material for presenting the project publicly, not shipped
 │   ├── README.md                   how it is organized and what to check before publishing
-│   ├── 2026-09-04-lancamento.md    the current dated news source the channel texts derive from
-│   ├── 2026-09-03-lancamento.md    the previous one, kept as the record of 0.5.1
+│   ├── 2026-10-10-lancamento.md    the current dated news source the channel texts derive from
+│   ├── 2026-09-0*-lancamento.md    the earlier ones, kept as the records of 0.5.4 and 0.5.1
 │   └── linkedin/                   post, artigo, the illustrated page and the figures, PT and EN
 └── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
 ```
@@ -347,7 +348,7 @@ 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 `version` and `date-released` in [`CITATION.cff`](CITATION.cff), and the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9. Those are the only version strings left in the repository, because a citation needs a concrete one. `uvx --from cffconvert cffconvert --validate` checks the file.
+2. Update `version` and `date-released` in [`CITATION.cff`](CITATION.cff), the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9, and the release named at the top of [`STATUS.md`](STATUS.md). Those are the version strings a release bumps, because a citation needs a concrete one and a snapshot names its release; [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md) names the version it measured and changes only when the table is re-measured. `uvx --from cffconvert cffconvert --validate` checks the file.
 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`.

{patchcraft-0.5.5 → patchcraft-0.5.6}/MANIFEST.in

@@ -42,3 +42,7 @@ prune .vscode
 # Presentation material, not source. It is tracked, so the file finder offers
 # it and only this line keeps it out.
 prune outreach
+# An article in preparation, not documentation of the library. Without this
+# line its experiment scripts would ship too, since the finder offers every
+# tracked file.
+prune docs/PAPER

{patchcraft-0.5.5 → patchcraft-0.5.6}/MAP.md

@@ -44,6 +44,7 @@ PatchCraft/
 ├── tests/ .................... the contract, executable
 │   ├── test_exactness.py ..... enumerates 126,736 geometries and tries to FALSIFY the predicate
 │   ├── test_reference.py ..... a naive loop the fast paths must agree with
+│   ├── test_operator.py ...... extract as a matrix U: the fold is U^T, reconstruct and stitch are least squares
 │   ├── test_public_api.py .... freezes the 20 names, their signatures and carrier fields
 │   └── _rng.py ............... audited data generation; integer ramps hid a real defect once
 │
@@ -58,12 +59,14 @@ PatchCraft/
 │   ├── FOCO-1.0.md ........... what 1.0 freezes, and the six blockers, all closed
 │   ├── ADR/ .................. one file per decision; the choice, not the research
 │   ├── design/ ............... one spec per work phase: alternatives measured, then chosen
-│   └── STUDIES/ .............. background reading, and the Strata conformity review
+│   ├── STUDIES/ .............. background reading, and the Strata conformity review
+│   └── PAPER/ ................ an article in preparation, on means that stay in their domain; not shipped
 │
 ├── tools/
 │   ├── benchmark.py .......... accelerated vs pure, and proves they agree before timing
 │   ├── check_dist.py ......... release gate: extension present, versions agree, tag respected
 │   ├── compare_exactness_rules.py  the power-of-two rule against k_max <= 4, measured
+│   ├── compare_border_strategies.py  truncate, pad or move the last window, measured
 │   └── make_outreach_figures.py    every outreach figure and generated page, computed
 │
 ├── outreach/ ................. material for presenting the project; not shipped
@@ -82,6 +85,7 @@ PatchCraft/
 | **Work on it as an agent**, or learn what this repo insists on | [AGENTS.md](AGENTS.md) |
 | **Use it**: every argument, measured, with its printed output | [docs/GUIDE.md](docs/GUIDE.md) |
 | Know **when the round trip is exact**, as a rule I can evaluate myself | [docs/GUIDE.md §4](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit), and [docs/ADR/0003](docs/ADR/0003-reversibility-classes.md) for the contract |
+| Know **what `reconstruct` and `stitch` compute** for patches a model changed, and how to filter or pad around them | [docs/THEORY.md §2.6](docs/THEORY.md), then [docs/GUIDE.md](docs/GUIDE.md) §2, §5 and §6 for the measured recipes |
 | Know **what each function accepts and rejects**, precisely | [docs/THEORY.md §9](docs/THEORY.md), which is the arbiter where documents disagree |
 | Know **whether this library is the right tool** | [docs/SCOPE.md](docs/SCOPE.md) |
 | Know **what the native accelerator is worth**, and re-measure it | [docs/PERFORMANCE.md](docs/PERFORMANCE.md), then `python tools/benchmark.py` |

{patchcraft-0.5.5 → patchcraft-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.5
+Version: 0.5.6
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT
@@ -111,7 +111,7 @@ blended = stitch(edited, image.shape, stride=16, weight="hann")
 assert blended.shape == image.shape                  # seams smoothed, geometry preserved
 ```
 
-PatchCraft accepts float tensors only. An 8-bit image has to become `image.float() / 255` before it reaches `extract`, because `extract` passes the tensor straight to `F.unfold`, and torch has no integer kernel there: it raises `NotImplementedError: "im2col_out_cpu" not implemented for 'Byte'`.
+PatchCraft accepts float tensors only. An 8-bit image has to become `image.float() / 255` before it reaches `extract`, because `extract` routes an integer tensor to `F.unfold`, and torch has no integer kernel there: it raises its own error, `"im2col_out_cpu" not implemented for 'Byte'`.
 
 ## reconstruct or stitch
 
@@ -128,7 +128,7 @@ Uniform averaging is the default, and it is the option that reports what the mod
 
 ## Why not unfold and fold directly
 
-Nothing stops you, and PatchCraft is a thin contract over exactly those two calls. What the contract buys is the pixel order and the boundary checks, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
+Nothing stops you. What PatchCraft adds is the pixel order and the boundary checks, done once with tests around them, and a faster fold where the wheel carries one, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
 
 ```python
 import torch
@@ -144,7 +144,7 @@ assert scrambled.shape == patches.shape                      # the right shape
 assert not torch.equal(scrambled, patches)                   # and the wrong pixels
 ```
 
-The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window took 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agreed to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
+The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window costs 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agree to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
 
 ## The geometry has to cover the image
 
@@ -162,7 +162,7 @@ It helps when you tile one image for an inference pass too large to run in a sin
 
 ## When the round trip is bit for bit
 
-The round trip is exact when every value in the count map is a power of two. The reason is that reconstruction divides each pixel by the number of patches that covered it, and dividing a float by a power of two is the one division that never rounds.
+The round trip is exact when every value in the count map is a power of two. Reconstruction adds up the patches covering each pixel and divides by how many there were, and in a legal geometry a map of powers of two holds only the counts 1, 2 and 4, where both steps are exact: adding two or four copies of a value never rounds, and neither does dividing by 2 or 4.
 
 That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness.
 
@@ -178,7 +178,7 @@ Where it applies today: on GPU the functions accept CUDA tensors and keep the de
 
 - [Guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md), the manual, with every figure on this page shown as runnable code
 - [Performance](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md), what the native accelerator is worth and how to re-measure it
-- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of each of the 20 public symbols, executed as a doctest
+- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of the public surface, executed as a doctest
 - [Theory](https://github.com/LeoPR/PatchCraft/blob/main/docs/THEORY.md), the math and the per-function contract
 - [Scope](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md), the line between this library and your pipeline
 - [Repository](https://github.com/LeoPR/PatchCraft), [issues](https://github.com/LeoPR/PatchCraft/issues) and [contributing](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md)

{patchcraft-0.5.5 → patchcraft-0.5.6}/README.md

@@ -140,13 +140,13 @@ PatchCraft does not help when you want a batched op over N images, a dataset or
 
 ## When the round trip is bit for bit
 
-The round trip is exact when every value in the count map is a power of two, which happens because dividing a float by a power of two is the one division that never rounds. Outside that rule the per-pixel error is bounded by (k+1)·eps·|v|, with k the pixel's coverage count. A wider float buys a smaller miss and never exactness, so float64 is not a safe harbour. The axis that decides the answer is the geometry and not the dtype, and [the guide](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) has the sweep that measures it.
+The round trip is exact when every value in the count map is a power of two, which in a legal geometry means every count is 1, 2 or 4: adding two or four copies of a value never rounds, and neither does dividing by 2 or 4. Outside that rule the per-pixel error is bounded by (k+1)·eps·|v|, with k the pixel's coverage count. A wider float buys a smaller miss and never exactness, so float64 is not a safe harbour. The axis that decides the answer is the geometry and not the dtype, and [the guide](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) has the sweep that measures it.
 
 ## Status
 
 **Pre-1.0**, and the badge above is the current release. While the leading digit is zero the middle one is the compatibility boundary, so `0.y.z` is safe to take and a new `0.y` is where an output value or a signature is allowed to move. [CHANGELOG.md](CHANGELOG.md) records every such change with the measurement behind it.
 
-1657 tests collected and CI is green on {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14}, with `ruff check` and `mypy --strict` in the same run. The package is typed and ships `py.typed`.
+CI is green on {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14} with the newest torch, and on the declared floor, Python 3.12 with torch 2.6, numpy 1.26, pillow 10.1 and Rust 1.82, with `ruff check` and `mypy --strict` in the same run. The package is typed and ships `py.typed`.
 
 On GPU the functions keep the device you hand them, and the Rust kernel is CPU-only, so it does not accelerate there; every figure here is a CPU figure. No external project consumes the library yet, which is the gate for calling the API settled. [The guide](docs/GUIDE.md#8-where-this-applies-today) says where the rest applies.
 
@@ -156,7 +156,7 @@ On GPU the functions keep the device you hand them, and the Rust kernel is CPU-o
 |---|---|
 | The manual: every argument above, measured, with its output | [docs/GUIDE.md](docs/GUIDE.md) |
 | What the native accelerator is worth, and how to re-measure it | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) |
-| A walkthrough of each of the 20 public symbols, executed as a doctest | [docs/USAGE.md](docs/USAGE.md) |
+| A walkthrough of the public surface, executed as a doctest | [docs/USAGE.md](docs/USAGE.md) |
 | The line between this library and your pipeline | [docs/SCOPE.md](docs/SCOPE.md) |
 | The math, the decisions and the per-function contract | [docs/THEORY.md](docs/THEORY.md) |
 | Why the API looks like this | [docs/ADR/](docs/ADR) |

{patchcraft-0.5.5 → patchcraft-0.5.6}/README.pt-BR.md

@@ -106,7 +106,7 @@ assert scrambled.shape == patches.shape                      # a forma certa
 assert not torch.equal(scrambled, patches)                   # e os pixels errados
 ```
 
-O segundo é um stride que não cobre a imagem. Numa imagem de 128 por 128 com `patch=32, stride=20`, a grade para no pixel 112, o que deixa 3840 dos 16384 pixels em zero, e um `fold` escrito à mão devolve essa imagem parcialmente preta sem reclamar.
+O segundo é um stride, a distância de um patch para o próximo, que não cobre a imagem. Numa imagem de 128 por 128 com `patch=32, stride=20`, a grade para no pixel 112, o que deixa 3840 dos 16384 pixels em zero, e um `fold` escrito à mão devolve essa imagem parcialmente preta sem reclamar.
 
 Escrever o laço de recortar e remontar à mão custa 17 linhas não vazias contra 3 aqui, e os dois resultados concordam em cerca de 1,2e-05 num valor em [0, 1], mais de 300 vezes menos que um degrau de 8 bits, com as duas rotas diferindo só na ordem em que somam uma janela separável. [O manual](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) roda as duas versões lado a lado.
 
@@ -140,13 +140,13 @@ O PatchCraft não ajuda quando você quer uma operação em lote sobre N imagens
 
 ## Quando o round-trip é bit a bit
 
-O round-trip é exato quando todo valor do mapa de cobertura é potência de dois, e isso acontece porque dividir um float por uma potência de dois é a única divisão que nunca arredonda. Fora dessa regra, o erro por pixel é limitado por (k+1)·eps·|v|, com k a contagem de cobertura do pixel. Um float mais largo compra um erro menor e nunca a exatidão, então o float64 não é um porto seguro. Quem decide a resposta é a geometria, e não o dtype. [O manual](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) traz a varredura que mede isso.
+O round-trip é exato quando todo valor do mapa de cobertura é potência de dois, o que numa geometria legal quer dizer que toda contagem é 1, 2 ou 4: somar duas ou quatro cópias de um valor nunca arredonda, e dividir por 2 ou por 4 também não. Fora dessa regra, o erro por pixel é limitado por (k+1)·eps·|v|, com k a contagem de cobertura do pixel. Um float mais largo compra um erro menor e nunca a exatidão, então o float64 não é um porto seguro. Quem decide a resposta é a geometria, e não o dtype. [O manual](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) traz a varredura que mede isso.
 
 ## Estado
 
 **Pré-1.0**, e o badge acima mostra a versão atual. Enquanto o primeiro dígito for zero, quem marca a fronteira de compatibilidade é o do meio: um `0.y.z` novo é seguro de pegar, e é num `0.y` novo que um valor de saída ou uma assinatura pode mudar. O [CHANGELOG.md](CHANGELOG.md) registra cada uma dessas mudanças com a medição por trás dela.
 
-São 1657 testes coletados, com CI verde em {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14}, e com `ruff check` e `mypy --strict` na mesma execução. O pacote é tipado e distribui o `py.typed`.
+A CI está verde em {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14} com o torch mais novo, e no piso declarado, Python 3.12 com torch 2.6, numpy 1.26, pillow 10.1 e Rust 1.82, com `ruff check` e `mypy --strict` na mesma execução. O pacote é tipado e distribui o `py.typed`.
 
 Em GPU as funções preservam o dispositivo que você passa, e o kernel Rust é só de CPU, então não acelera ali; todo número desta página é de CPU. Nenhum projeto externo consome a biblioteca ainda, que é o critério para dizer a API assentada. [O manual](docs/GUIDE.md#8-where-this-applies-today) diz onde o resto se aplica.
 
@@ -156,7 +156,7 @@ Em GPU as funções preservam o dispositivo que você passa, e o kernel Rust é
 |---|---|
 | O manual: cada argumento acima, medido, com a saída | [docs/GUIDE.md](docs/GUIDE.md) |
 | Quanto vale o acelerador nativo, e como remedir | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) |
-| Um passeio por cada um dos 20 símbolos públicos, executado como doctest | [docs/USAGE.md](docs/USAGE.md) |
+| Um passeio pela superfície pública, executado como doctest | [docs/USAGE.md](docs/USAGE.md) |
 | A linha entre esta biblioteca e o seu pipeline | [docs/SCOPE.md](docs/SCOPE.md) |
 | A matemática, as decisões e o contrato por função | [docs/THEORY.md](docs/THEORY.md) |
 | Por que a API tem essa cara | [docs/ADR/](docs/ADR) |

{patchcraft-0.5.5 → patchcraft-0.5.6}/README.pypi.md

@@ -69,7 +69,7 @@ blended = stitch(edited, image.shape, stride=16, weight="hann")
 assert blended.shape == image.shape                  # seams smoothed, geometry preserved
 ```
 
-PatchCraft accepts float tensors only. An 8-bit image has to become `image.float() / 255` before it reaches `extract`, because `extract` passes the tensor straight to `F.unfold`, and torch has no integer kernel there: it raises `NotImplementedError: "im2col_out_cpu" not implemented for 'Byte'`.
+PatchCraft accepts float tensors only. An 8-bit image has to become `image.float() / 255` before it reaches `extract`, because `extract` routes an integer tensor to `F.unfold`, and torch has no integer kernel there: it raises its own error, `"im2col_out_cpu" not implemented for 'Byte'`.
 
 ## reconstruct or stitch
 
@@ -86,7 +86,7 @@ Uniform averaging is the default, and it is the option that reports what the mod
 
 ## Why not unfold and fold directly
 
-Nothing stops you, and PatchCraft is a thin contract over exactly those two calls. What the contract buys is the pixel order and the boundary checks, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
+Nothing stops you. What PatchCraft adds is the pixel order and the boundary checks, done once with tests around them, and a faster fold where the wheel carries one, because the intuitive reshape after `F.unfold` returns a tensor of the right shape whose pixels are scrambled.
 
 ```python
 import torch
@@ -102,7 +102,7 @@ assert scrambled.shape == patches.shape                      # the right shape
 assert not torch.equal(scrambled, patches)                   # and the wrong pixels
 ```
 
-The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window took 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agreed to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
+The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window costs 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agree to about 1.2e-05 on a value in [0, 1], summation-order rounding more than 300 times smaller than one 8-bit step.
 
 ## The geometry has to cover the image
 
@@ -120,7 +120,7 @@ It helps when you tile one image for an inference pass too large to run in a sin
 
 ## When the round trip is bit for bit
 
-The round trip is exact when every value in the count map is a power of two. The reason is that reconstruction divides each pixel by the number of patches that covered it, and dividing a float by a power of two is the one division that never rounds.
+The round trip is exact when every value in the count map is a power of two. Reconstruction adds up the patches covering each pixel and divides by how many there were, and in a legal geometry a map of powers of two holds only the counts 1, 2 and 4, where both steps are exact: adding two or four copies of a value never rounds, and neither does dividing by 2 or 4.
 
 That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness.
 
@@ -136,7 +136,7 @@ Where it applies today: on GPU the functions accept CUDA tensors and keep the de
 
 - [Guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md), the manual, with every figure on this page shown as runnable code
 - [Performance](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md), what the native accelerator is worth and how to re-measure it
-- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of each of the 20 public symbols, executed as a doctest
+- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of the public surface, executed as a doctest
 - [Theory](https://github.com/LeoPR/PatchCraft/blob/main/docs/THEORY.md), the math and the per-function contract
 - [Scope](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md), the line between this library and your pipeline
 - [Repository](https://github.com/LeoPR/PatchCraft), [issues](https://github.com/LeoPR/PatchCraft/issues) and [contributing](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md)

{patchcraft-0.5.5 → patchcraft-0.5.6}/STATUS.md

@@ -1,4 +1,4 @@
-# STATUS: 2026-09-26
+# STATUS: 2026-10-10
 
 > The snapshot. Where things are *right now*, and who each open item waits on.
 > Where things **are** is [MAP.md](MAP.md); the rules are [AGENTS.md](AGENTS.md);
@@ -6,31 +6,44 @@
 
 ## Where the project is
 
-**0.5.5 is on PyPI**, published through Trusted Publishing on a tag push: one
+**0.5.6 is on PyPI**, published through Trusted Publishing on a tag push: one
 sdist, five `cp312-abi3` platform wheels carrying the Rust accelerator, and one
 universal `py3-none-any` wheel. There is no extra to enable and no second
 package.
 
-**1620 tests pass** under `pytest -m "not gpu"`, with 32 skipped and 5
+**1818 tests pass** under `pytest -m "not gpu"`, with 32 skipped and 5
 deselected, plus two full-sweep gates behind `PATCHCRAFT_SWEEP_FULL=1`
 that enumerate all 126,736 legal geometries. CI is green on
 {Ubuntu, Windows} x {3.12, 3.13, 3.14} on the pure path, plus a two-OS job that
-builds the Rust kernel and runs the whole suite through it.
+builds the Rust kernel and runs the whole suite through it, all at the newest
+torch, and a job at the declared floor (Python 3.12, torch 2.6, numpy 1.26,
+pillow 10.1, Rust 1.82) that runs it on both paths.
 
 **The surface is 20 names**, pinned by `tests/test_public_api.py` with
 `inspect.signature`.
 
 ## What is in flight
 
-**Nothing unreleased.** 0.5.5 is a performance release that changes no bit:
-`stitch` folds its window without a Python loop and skips the fold for the
-uniform window on non-overlapping grids, `reconstruct` builds its count map
-with fewer operations, both divide in place, and `tilings` visits only the
-strides that can work. Each was compared against the 0.5.4 code through
-integer views, 53,716 cases with 0 differences, and the full 126,736-geometry
-sweep passes on both paths. Alongside it, the surface pages lost their
-development history, GUIDE section 8 became "Where this applies today", and
-docs/PERFORMANCE.md was re-measured on the code that ships.
+**Nothing unreleased.** 0.5.6 is a fix release: `torch.vmap` over `extract`,
+`reconstruct` and `stitch`, which the documentation offers as a way to batch,
+failed on most calls since 0.5.0 and works again, pinned by
+`tests/test_vmap.py`; and `tilings` returns `[]` for an image smaller than the
+default minimum patch instead of raising. With them came the corrected reason
+for the exactness rule, THEORY §2.6 on the operator, the USAGE walk through a
+4×4 image, and a CI job at the declared floor, whose first run found a claim
+that held only at the top. The full 126,736-geometry sweep passes on both
+paths.
+
+**ADR 0005 is `Proposed`**: padding a grid that does not cover the image, with
+the design taken from kornia's auto-padding and MONAI's `padding_mode`, one
+keyword with a default that changes no call. Nothing is implemented. The owner
+recorded it in the ROADMAP as the 1.1 candidate rather than scheduling it, so it
+**waits on a consumer**.
+
+**`docs/PAPER/` is a scaffold** for an article on means that never leave
+their domain: outline, formal statements, measurements and references, with
+the prose not yet written. It does not ship. Its first open item, a search for
+prior art on the integer carry, **waits on the owner**, as does the writing.
 
 ## What is blocked, and on whom
 

{patchcraft-0.5.5 → patchcraft-0.5.6}/docs/ADR/0003-reversibility-classes.md

@@ -58,8 +58,13 @@ be false over part of their accepted input.
 **Geometry.** The `extract`/`reconstruct` round trip is bit-exact when every
 value of the overlap coverage map is a power of two, and not otherwise. The
 reason is arithmetic rather than statistical: the fold sums `k` copies of a value
-and divides by `k`, which is exact in binary floating point exactly when `k` is a
-power of two. Every exact tiling qualifies, since all its counts are 1.
+and divides by `k`. Dividing by a power of two never rounds, and for `k` = 2 and 4
+the sum of equal values is exact too, short of overflow. For `k` = 8 it is not,
+since the partial sums 3x, 5x, 6x and 7x round; the rule holds anyway because a
+coverage of three or more on either axis puts a 3 in the map, so a map of powers
+of two only ever holds 1, 2 and 4, which is what all 126,736 legal geometries
+show. (Corrected 2026-10-10: the earlier wording credited every power of two.)
+Every exact tiling qualifies, since all its counts are 1.
 
 **Accumulator.** ADR 0004 measured the sentence above to carry an unstated
 premise, which is the accumulator the library happens to use. Over 76 legal