patchcraft 0.5.4__tar.gz → 0.5.5__tar.gz

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

@@ -6,6 +6,127 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-09-26
+
+A performance release that changes no bit. Every change to `src/` below was
+compared against the 0.5.4 code through integer views, so that `-0.0` and
+`+0.0` or two NaN payloads count as different: 53,716 cases over 1,382
+geometries, four float dtypes, both code paths and gradients, with 0
+differences. The full 126,736-geometry exactness sweep passes on both paths.
+
+### Changed
+
+- **`stitch` builds its window denominator without a Python loop.** The
+  1-D window fold ran one iteration per stride residue, six tensor operations
+  each, and that loop dominated `stitch` at every size once the numerator was
+  accelerated. All residues are now one cumsum over a `(m, step)` view of the
+  zero-padded kernel, which scans each residue in the same order, so the
+  output is bit-identical: 0 differences against the previous code over
+  38,696 cases, covering three windows, four float dtypes, both code paths and
+  gradients. Accelerated `stitch` is 2.7x to 5.1x faster at 512x512 and 1.2x
+  to 1.4x at 2048x2048; on the pure path `F.fold` still dominates at 2048.
+
+- **`reconstruct` builds its count map with fewer operations, and both
+  `reconstruct` and `stitch` divide in place.** The suffix ramp of the
+  closed-form count map is the prefix ramp reversed, a square grid reuses the
+  H axis for W, and the outer product is taken in the accumulation dtype,
+  where multiplying two small exact integers rounds their exact product once,
+  as casting the int64 product did. The numerator and the denominator are
+  fresh tensors each function owns, so the final clamp and division no longer
+  allocate. Bit-identical: 0 differences over 13,820 `reconstruct` and 38,696
+  `stitch` cases, and the caller's patches are never mutated or aliased.
+  Accelerated `reconstruct` is 1.15x to 1.26x faster, and one call at
+  3x2048x2048 with patch 64 and stride 32 allocates 64 MiB instead of 177
+  (`stitch` hann: 65 instead of 128).
+
+- **`tilings(allow_overlap=True)` visits only the strides that can work.** A
+  stride covers both axes exactly when it divides `h - p` and `w - p`, that
+  is when it divides their gcd, so the loop runs over the divisors of the gcd
+  instead of over every stride below the patch size. The output is the same
+  list in the same order: identical in 9,530 cases, every shape from 1x1 to
+  69x69 in both modes plus larger ones, and `paired_tilings`, which builds on
+  it. 22.8 to 7.3 ms at 512x512, 91 to 9 ms at 1080x1920, 699 to 17 ms at
+  4000x3000.
+
+- **`stitch` with the uniform window skips the fold on non-overlapping
+  grids.** There the fold adds each value, times 1, into a zero-filled buffer
+  and divides by a count of 1, which is `0.0 + x`: the value itself, except
+  that `-0.0` comes out as `+0.0` and a NaN comes out quiet. The new path
+  rearranges the patches and adds `0.0`, which reproduces exactly that; a bare
+  rearrangement would have kept `-0.0`, a difference `torch.equal` cannot see
+  and an integer-view comparison can. Bit-identical in the full comparison
+  and in a dedicated check of zeros of both signs, NaN payloads, infinities,
+  extremes and subnormals, and pinned by a new test against `F.fold` itself.
+  3.4x to 58x faster depending on size: 146 to 9.4 ms on the pure path at
+  3x2048x2048 with patch 32.
+
+- docs/PERFORMANCE.md is re-measured on the code that ships, twice, agreeing
+  within about 10%. The accelerator's range over the published table is now
+  5.8x to 16.5x, against 2.6x to 14x at 0.5.1; the low end moved most, since
+  accelerated `stitch` at 512 went from 6.3 to 3.0 ms. The thread sweep behind
+  "the gain is algorithmic" was re-run as well: the pure path at 2048 takes
+  448 ms at 4 threads and 390 at 36, no better than at 8.
+
+- **The manual, the usage page and the three READMEs no longer carry
+  development history.** Sentences about what an earlier version did, what a
+  first audit found or what used to be printed moved out; where an old
+  measurement is the argument for the current rule it stays, in the present
+  tense. GUIDE §8 is now "Where this applies today", and each of its items says
+  what a reader should do (on GPU it works and does not accelerate; on macOS and
+  aarch64, compare once against `PATCHCRAFT_ACCEL=0`), instead of listing what
+  the project has not done. The old anchor is updated everywhere it was linked.
+
+- The README tagline read "Encode one image into patches, decode it back",
+  which invited the compression reading the page then had to head off. It now
+  says "Cut one image into patches, and put it back together", followed by one
+  sentence on what a patch is for.
+
+- GUIDE's hann figure against the model's own patches read 27.14 dB and prints
+  27.15 dB on both code paths; the page now quotes what the code prints.
+
+- `tools/make_outreach_figures.py` lost 301 unreachable lines left from
+  earlier layouts, with every generated file byte-identical before the later
+  edits. Every caption that states a result is now checked against it before
+  it is drawn, including the refusal at stride 20 and the exact round trip at
+  32 and 16. The MNIST grid is drawn at display scale instead of into the
+  digit's pixels, where it hid more than a third of a 28x28 image, and the
+  patch shown alone is outlined in it.
+
+### Added
+
+- `tools/compare_exactness_rules.py` measures the exactness rule against the
+  obvious looser one, keeping the largest coverage count at 4 or below, over
+  the 126,736 geometries `tests/test_exactness.py` enumerates, with the round
+  trip on five seeds as ground truth. The power-of-two rule makes no false
+  promise and withholds none; `k_max <= 4` promises exactness on 13,870
+  geometries that do not come back exact. The outreach article quoted an
+  earlier sweep of 14,969 rectangular geometries from a lab script that is not
+  in the tree, so no command reproduced it; it now cites this one.
+
+### Fixed
+
+- docs/PERFORMANCE.md and `tools/benchmark.py` said non-overlapping geometries
+  never reach the fold. At 0.5.4 that held for `reconstruct`, which has a
+  closed-form path at `stride == patch_size`, and not for `stitch`, which
+  folded at every geometry: about 144 ms on the pure path at 3x2048x2048 with
+  patch 32, where `reconstruct` returned the same bits in about 6 ms. This
+  release gives `stitch` that path under the uniform window, and both texts
+  now say which windows still fold and why.
+
+- `metrics.py` claimed no allocation beyond the difference and, in a comment,
+  that the in-place subtract avoids a float64 copy of `b`. Measured with the
+  torch profiler, `a.to(float64).sub_(b)` with `b` in float32 allocates a
+  float64 temporary of `b` first, doubling the largest allocation from 188 to
+  375 MiB on 94 MiB of input. The comment and the module docstring now say
+  what happens; the code is unchanged.
+
+- CONTRIBUTING placed the `WeightKind` paragraph between "what each digit is
+  for here:" and the table the colon announced, and its errata repeated two
+  worked examples word for word. MAP and CONTRIBUTING counted five issue forms
+  where there are four, called all-closed 1.0 blockers "still in the way", and
+  listed neither generator in `tools/`. STATUS still called the `Cache` fix
+  unreleased after 0.5.4 shipped it.
+
 ## [0.5.4] - 2026-09-04
 
 ### Fixed
@@ -895,7 +1016,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.4...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.5...HEAD
+[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
 [0.5.2]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.2

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

@@ -6,8 +6,8 @@ authors:
   - given-names: Leonardo
     family-names: Marques de Souza
     email: leonardo.marques.souza@gmail.com
-version: "0.5.4"
-date-released: "2026-09-04"
+version: "0.5.5"
+date-released: "2026-09-26"
 repository-code: "https://github.com/LeoPR/PatchCraft"
 license: MIT
 abstract: >

{patchcraft-0.5.4 → patchcraft-0.5.5}/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 36 of 65 files in a commit that changed no
+it, and adopting it would reformat 37 of 82 files in a commit that changed no
 behaviour.
 
 ```
@@ -130,6 +130,8 @@ PatchCraft/
 ├── 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
+├── tools/compare_exactness_rules.py  the power-of-two rule against k_max <= 4, measured
+├── tools/make_outreach_figures.py  every outreach figure and generated page, computed
 ├── MANIFEST.in                     what the sdist carries
 ├── README.md                       the call page, canonical, English
 ├── README.pt-BR.md                 the same call page in Portuguese
@@ -148,7 +150,7 @@ PatchCraft/
 ├── SECURITY.md                     how to report, and what the real attack surface is
 ├── CODE_OF_CONDUCT.md              Contributor Covenant 2.1, verbatim
 ├── .github/
-│   ├── ISSUE_TEMPLATE/             five forms; the required fields are what makes a report reproducible
+│   ├── 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
@@ -185,6 +187,9 @@ PatchCraft/
 │   ├── test_accel.py               native path, skipped unless the extension was built
 │   ├── test_datasets_helper.py     label_subset
 │   ├── test_import.py
+│   ├── test_docs_usage.py          runs docs/USAGE.md as a doctest
+│   ├── test_citation.py            CITATION.cff agrees with the package
+│   ├── conftest.py                 shared fixtures
 │   ├── _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
@@ -199,14 +204,15 @@ PatchCraft/
 │   ├── 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
+│   ├── 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
 ├── 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
+│   ├── 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
+│   └── linkedin/                   post, artigo, the illustrated page and the figures, PT and EN
 └── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
 ```
 
@@ -253,12 +259,7 @@ 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:
-
-One consequence worth stating on its own, because a consumer cannot infer it
-from a `Literal`: **`WeightKind` is an open set.** Adding a member is additive
-and lands in a `0.y` before 1.0 and a minor after it; removing or renaming one
-is a break. Code that matches on it exhaustively should keep a fallback arm.
+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
@@ -289,6 +290,11 @@ under any rule keyed on whether values changed:
 - `0.5.0` made `tilings` return 73 specs where it returned 100. The
   enumeration's output set is the contract. A **y**.
 
+One consequence worth stating on its own, because a consumer cannot infer it
+from a `Literal`: **`WeightKind` is an open set.** Adding a member is additive
+and lands in a `0.y` before 1.0 and a minor after it; removing or renaming one
+is a break. Code that matches on it exhaustively should keep a fallback arm.
+
 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).
@@ -305,11 +311,6 @@ 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

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

@@ -22,7 +22,7 @@ PatchCraft/
 ├── CONTRIBUTING.md ........... layout, the two code paths, the versioning rule, releasing
 ├── CITATION.cff .............. citation metadata; GitHub reads it for the cite button
 ├── LICENSE ................... MIT
-├── SECURITY.md ............... how to report, and the three trust boundaries that matter
+├── SECURITY.md ............... how to report, and the five edges of the attack surface
 ├── CODE_OF_CONDUCT.md ........ Contributor Covenant 2.1
 │
 ├── src/patchcraft/ ........... THE LIBRARY. 20 public names, frozen by test
@@ -55,19 +55,21 @@ PatchCraft/
 │   ├── USAGE.md .............. the 20 symbols one at a time; every >>> runs in the suite
 │   ├── AUXILIARY.md .......... test fixtures, lab/, the off-tree conventions
 │   ├── ROADMAP.md ............ milestones, historical
-│   ├── FOCO-1.0.md ........... what 1.0 freezes, and the blockers still in the way
+│   ├── 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
 │
 ├── tools/
 │   ├── benchmark.py .......... accelerated vs pure, and proves they agree before timing
-│   └── check_dist.py ......... release gate: extension present, versions agree, tag respected
+│   ├── 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
+│   └── make_outreach_figures.py    every outreach figure and generated page, computed
 │
 ├── outreach/ ................. material for presenting the project; not shipped
 ├── lab/ ...................... scratch experiments; only the README is tracked
 └── .github/
-    ├── ISSUE_TEMPLATE/ ....... five forms, each asking for the geometry and PATCHCRAFT_ACCEL=0
+    ├── ISSUE_TEMPLATE/ ....... four forms, each asking for the geometry and PATCHCRAFT_ACCEL=0
     ├── PULL_REQUEST_TEMPLATE.md
     └── workflows/ ............ test.yml (both code paths) and release.yml (one project, six wheels)
 ```
@@ -83,7 +85,7 @@ PatchCraft/
 | 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` |
-| Know **what the project refuses to claim** | [docs/GUIDE.md §8](docs/GUIDE.md#8-what-this-project-does-not-claim) |
+| Know **where the library applies today** | [docs/GUIDE.md §8](docs/GUIDE.md#8-where-this-applies-today) |
 | Understand **why the API looks like this** | [docs/ADR/](docs/ADR/), and [docs/STUDIES/](docs/STUDIES/) for the measurements behind them |
 | Understand **why a phase was built the way it was** | [docs/design/](docs/design/) |
 | **Contribute**: run the gates, understand the two code paths | [CONTRIBUTING.md](CONTRIBUTING.md) |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.4
+Version: 0.5.5
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT
@@ -42,7 +42,7 @@ Dynamic: license-file
 
 # PatchCraft
 
-Encode one image into patches, decode it back, and decide what happens at the seams.
+Cut one image into patches, put it back together, and decide what happens at the seams.
 
 [![Latest version on PyPI](https://img.shields.io/pypi/v/patchcraft?color=3775A9&label=PyPI)](https://pypi.org/project/patchcraft/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/patchcraft?color=3776AB)](https://pypi.org/project/patchcraft/)
@@ -88,7 +88,7 @@ paths, which return the same values.
 
 `patchcraft.accel_available()` reports at runtime which one you got, and
 `PATCHCRAFT_ACCEL=0` in the environment forces the pure path. On the overlapping
-fold it is worth between 2.6x and 14x on the machine it was measured on, which
+fold the accelerator is worth between 5.8x and 16.5x on the machine it was measured on, which
 the [performance page](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md)
 reports in full.
 
@@ -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].
+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 geometry has to cover the image
 
@@ -170,9 +170,9 @@ The everyday shorthand is that `stride == patch_size` and `stride == patch_size
 
 ## Status
 
-This is pre-1.0, so both the output values and the API shape can still move. While the leading digit is zero the middle one is the compatibility boundary, which makes a new `0.y.z` safe to take and a new `0.y` the place where a change is allowed to land, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) records each one with the measurement behind it. The suite collects 1656 tests and passes on Python 3.12, 3.13 and 3.14, on Ubuntu and on Windows alike.
+This is pre-1.0, so both the output values and the API shape can still move. While the leading digit is zero the middle one is the compatibility boundary, which makes a new `0.y.z` safe to take and a new `0.y` the place where a change is allowed to land, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) records each one with the measurement behind it. The suite collects 1657 tests and passes on Python 3.12, 3.13 and 3.14, on Ubuntu and on Windows alike.
 
-Two limits are worth knowing before you depend on it. Every figure on this page was measured on CPU, and no CUDA path has ever executed in the test matrix, so the pipeline does preserve the device you hand it while the exactness numbers stay unverified on GPU. The other limit is that no external project has consumed the published API in real use yet, and that consumption is this project's own stated gate for calling the shape settled.
+Where it applies today: on GPU the functions accept CUDA tensors and keep the device, and the Rust kernel is CPU-only, so it does not accelerate there; every figure on this page is a CPU figure, so check exactness on your device before relying on it. No external project consumes the published API yet, which is the gate this project set for calling the shape settled.
 
 ## Documentation
 

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

@@ -8,7 +8,7 @@
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/patchcraft.svg)](https://pypi.org/project/patchcraft/)
 [![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/LeoPR/PatchCraft/blob/main/LICENSE)
 
-**Encode one image into patches, decode it back.** PatchCraft owns the `unfold` and `fold` arithmetic, the geometry validation and the seam blending, so that your pipeline can own everything else.
+**Cut one image into patches, and put it back together.** A large image rarely goes into a network whole: it is cut into small tiles, the patches, each one is processed on its own, and the image is put back. PatchCraft owns the `unfold` and `fold` arithmetic, the geometry validation and the seam blending, so that your pipeline can own everything else.
 
 **One image at a time, on purpose.** Every call takes one `(C, H, W)` float tensor and returns one tensor, because the patch count depends on the image and a batched API would have to pad or return a list. Your `for` loop, `torch.vmap` or `DataLoader` supplies the batching.
 
@@ -30,7 +30,7 @@ The image goes out as a stack of patches, you do your work on the stack, and it
 image. That last arrow has two doors: `reconstruct` when the patches are untouched, and `stitch`
 when a model rewrote them and the seams need to fade.
 
-This page is the call page. The manual is [docs/GUIDE.md](docs/GUIDE.md), and it carries the measurements, the tables and the long examples that used to live here.
+This page is the call page. The manual is [docs/GUIDE.md](docs/GUIDE.md), and it carries the measurements, the tables and the long examples.
 
 ## Install
 
@@ -47,8 +47,8 @@ paths, which return the same values.
 
 `patchcraft.accel_available()` reports at runtime which one you got, and
 `PATCHCRAFT_ACCEL=0` in the environment forces the pure path. On the overlapping
-fold it is worth between 2.6x and 14x here, measured in
-[docs/PERFORMANCE.md](docs/PERFORMANCE.md).
+fold the accelerator is worth between 5.8x and 16.5x on the machine it was
+measured on, which [docs/PERFORMANCE.md](docs/PERFORMANCE.md) reports in full.
 
 The distribution name and the import name are both `patchcraft`. The runtime dependencies are `torch>=2.6`, `numpy>=1.26` and `pillow>=10`, and the supported Python versions are in [the guide](docs/GUIDE.md#9-install-details-and-citation) together with the note you need before you install a GPU wheel.
 
@@ -108,7 +108,7 @@ assert not torch.equal(scrambled, patches)                   # and the wrong pix
 
 The second one is a stride that does not cover the image. On a 128 by 128 image with `patch=32, stride=20` the grid stops at pixel 112, which leaves 3840 of the 16384 pixels at zero, and a hand-rolled `fold` returns that partly black image without complaining.
 
-Writing the tile-and-blend loop by hand costs 17 non-blank lines against 3 here, and the two results agree to about 1.2e-05 on a value in [0, 1], the two routes differing only in the order they sum a separable window. [The guide](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) runs both versions side by side.
+Writing the tile-and-blend loop by hand costs 17 non-blank lines against 3 here, and the two results agree to about 1.2e-05 on a value in [0, 1], more than 300 times smaller than one 8-bit step, the two routes differing only in the order they sum a separable window. [The guide](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) runs both versions side by side.
 
 ## The geometry has to cover the image
 
@@ -130,7 +130,7 @@ print([s.patch_size for s in tilings(image.shape)])  # 7 exact tilings, from the
 
 `tilings` is arithmetic on the shape, so it reads nothing and allocates nothing. Pass `allow_overlap=True` when you want the overlapping geometries too.
 
-## Where you are getting into
+## What you are getting into
 
 The surface is one tensor in and one tensor out. There is no batch axis, no dataset, no dataloader and no training, and that boundary is binding rather than provisional, recorded in [docs/THEORY.md](docs/THEORY.md) §0.
 
@@ -146,9 +146,9 @@ The round trip is exact when every value in the count map is a power of two, whi
 
 **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.
 
-1656 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`.
+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`.
 
-No external project has consumed it yet, and no CUDA path in this library has ever executed. [The guide](docs/GUIDE.md#8-what-this-project-does-not-claim) lists what else this project declines to claim.
+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.
 
 ## Where to read next
 

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

@@ -8,7 +8,7 @@
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/patchcraft.svg)](https://pypi.org/project/patchcraft/)
 [![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/LeoPR/PatchCraft/blob/main/LICENSE)
 
-**Codifica uma imagem em patches e decodifica de volta.** O PatchCraft cuida da aritmética do `unfold` e do `fold`, da validação da geometria e da mistura nas emendas, para que o seu pipeline possa cuidar de todo o resto.
+**Recorta uma imagem em patches e monta de volta.** Uma imagem grande raramente entra inteira numa rede: ela é cortada em pedaços pequenos, os patches, cada um é processado sozinho, e a imagem é montada de volta. O PatchCraft cuida da aritmética do `unfold` e do `fold`, da validação da geometria e da mistura nas emendas, para que o seu pipeline possa cuidar de todo o resto.
 
 **Uma imagem por vez, de propósito.** Cada chamada recebe um tensor float `(C, H, W)` e devolve um tensor, porque a quantidade de patches depende da imagem, e uma API em lote teria que preencher com padding ou devolver uma lista. Quem fornece o lote é o seu `for`, o `torch.vmap` ou o `DataLoader`.
 
@@ -47,8 +47,8 @@ rodam os caminhos em torch puro, que devolvem os mesmos valores.
 
 O `patchcraft.accel_available()` informa em runtime qual dos dois você recebeu,
 e `PATCHCRAFT_ACCEL=0` no ambiente força o caminho puro. No fold com
-sobreposição ele vale entre 2.6x e 14x aqui, medido em
-[docs/PERFORMANCE.md](docs/PERFORMANCE.md).
+sobreposição o acelerador vale entre 5,8x e 16,5x na máquina em que foi
+medido, que o [docs/PERFORMANCE.md](docs/PERFORMANCE.md) relata por inteiro.
 
 O nome da distribuição e o nome de importação são os dois `patchcraft`. As dependências de execução são `torch>=2.6`, `numpy>=1.26` e `pillow>=10`. As versões de Python suportadas estão [no manual](docs/GUIDE.md#9-install-details-and-citation), junto com a observação que você precisa ler antes de instalar uma wheel de GPU.
 
@@ -108,7 +108,7 @@ assert not torch.equal(scrambled, patches)                   # e os pixels errad
 
 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.
 
-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], 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.
+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.
 
 ## A geometria precisa cobrir a imagem
 
@@ -146,9 +146,9 @@ O round-trip é exato quando todo valor do mapa de cobertura é potência de doi
 
 **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 1656 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`.
+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`.
 
-Nenhum projeto externo consumiu a biblioteca ainda, e nenhum caminho CUDA dela jamais executou. [O manual](docs/GUIDE.md#8-what-this-project-does-not-claim) lista o que mais este projeto se recusa a afirmar.
+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.
 
 ## Onde ler em seguida
 

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

@@ -1,6 +1,6 @@
 # PatchCraft
 
-Encode one image into patches, decode it back, and decide what happens at the seams.
+Cut one image into patches, put it back together, and decide what happens at the seams.
 
 [![Latest version on PyPI](https://img.shields.io/pypi/v/patchcraft?color=3775A9&label=PyPI)](https://pypi.org/project/patchcraft/)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/patchcraft?color=3776AB)](https://pypi.org/project/patchcraft/)
@@ -46,7 +46,7 @@ paths, which return the same values.
 
 `patchcraft.accel_available()` reports at runtime which one you got, and
 `PATCHCRAFT_ACCEL=0` in the environment forces the pure path. On the overlapping
-fold it is worth between 2.6x and 14x on the machine it was measured on, which
+fold the accelerator is worth between 5.8x and 16.5x on the machine it was measured on, which
 the [performance page](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md)
 reports in full.
 
@@ -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].
+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 geometry has to cover the image
 
@@ -128,9 +128,9 @@ The everyday shorthand is that `stride == patch_size` and `stride == patch_size
 
 ## Status
 
-This is pre-1.0, so both the output values and the API shape can still move. While the leading digit is zero the middle one is the compatibility boundary, which makes a new `0.y.z` safe to take and a new `0.y` the place where a change is allowed to land, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) records each one with the measurement behind it. The suite collects 1656 tests and passes on Python 3.12, 3.13 and 3.14, on Ubuntu and on Windows alike.
+This is pre-1.0, so both the output values and the API shape can still move. While the leading digit is zero the middle one is the compatibility boundary, which makes a new `0.y.z` safe to take and a new `0.y` the place where a change is allowed to land, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) records each one with the measurement behind it. The suite collects 1657 tests and passes on Python 3.12, 3.13 and 3.14, on Ubuntu and on Windows alike.
 
-Two limits are worth knowing before you depend on it. Every figure on this page was measured on CPU, and no CUDA path has ever executed in the test matrix, so the pipeline does preserve the device you hand it while the exactness numbers stay unverified on GPU. The other limit is that no external project has consumed the published API in real use yet, and that consumption is this project's own stated gate for calling the shape settled.
+Where it applies today: on GPU the functions accept CUDA tensors and keep the device, and the Rust kernel is CPU-only, so it does not accelerate there; every figure on this page is a CPU figure, so check exactness on your device before relying on it. No external project consumes the published API yet, which is the gate this project set for calling the shape settled.
 
 ## Documentation
 

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

@@ -1,4 +1,4 @@
-# STATUS: 2026-09-04
+# STATUS: 2026-09-26
 
 > 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,12 +6,12 @@
 
 ## Where the project is
 
-**0.5.4 is on PyPI**, published through Trusted Publishing on a tag push: one
+**0.5.5 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.
 
-**1619 tests pass** under `pytest -m "not gpu"`, with 32 skipped and 5
+**1620 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
@@ -22,13 +22,15 @@ builds the Rust kernel and runs the whole suite through it.
 
 ## What is in flight
 
-**Nothing unreleased.** 0.5.4 closed the nine entries that had accumulated
-since 0.5.3: two fixes, `Cache` not expanding a leading `~` and `resize`
-raising a raw torch error on 13 of the 25 resample-mode x integer-dtype
-combinations, the second of which also uncovered a silent `int32` truncation
-older than itself. The other seven are documentation, and they close every
-item the 2026-09-04 audit left open, including ADR 0004's step 0 and the
-`WeightKind` compatibility sentence.
+**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.
 
 ## What is blocked, and on whom
 
@@ -55,7 +57,7 @@ inventing path security is not this library's job, and no library in the
 ecosystem does it, verified against `torch.hub.set_dir`, pytest's cacheprovider
 and pip. Asking the question found the real defect, which was the opposite
 shape: `Cache` was missing the one thing all of them do, so `Cache("~/cache")`
-created a directory literally named `~`. Fixed in the unreleased set, with no
+created a directory literally named `~`. Fixed in 0.5.4, with no
 validation added. [SECURITY.md](SECURITY.md) and THEORY §9.5 now say the path
 is the caller's and that only `~` is expanded.