patchcraft 0.5.4__tar.gz → 0.5.6__tar.gz

{patchcraft-0.5.4 → 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.4 → 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.4 → patchcraft-0.5.6}/CHANGELOG.md

@@ -6,6 +6,279 @@ 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
+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 +1168,9 @@ 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.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
 [0.5.2]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.2

{patchcraft-0.5.4 → 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.4"
-date-released: "2026-09-04"
+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.4 → 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 36 of 65 files in a commit that changed no
+it, and adopting it would reformat 37 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,10 +150,10 @@ 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
+│   ├── 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
@@ -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,16 @@ 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
+│   ├── 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-03-lancamento.md    the dated news source every channel text derives from
-│   └── linkedin/                   post (short) and artigo (long), each in PT and EN
+│   ├── 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)
 ```
 
@@ -253,12 +260,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 +291,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 +312,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
@@ -346,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.4 → 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.4 → patchcraft-0.5.6}/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
@@ -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
 │
@@ -55,19 +56,23 @@ 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
+│   ├── 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
+│   ├── 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
 ├── 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)
 ```
@@ -80,10 +85,11 @@ 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` |
-| 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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.4
+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
@@ -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.
 
@@ -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].
+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.
 
@@ -170,15 +170,15 @@ 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
 
 - [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)