patchcraft 0.5.1__tar.gz → 0.5.2__tar.gz

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

@@ -6,6 +6,85 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-09-03
+
+### Fixed
+
+- **`stitch(weight="hann")` corrupted the corner band of every patch of 99 or
+  more.** The denominator was floored by an absolute `clamp(min=1e-6)` whose
+  comment called it a defensive no-op. It was not: the 2-D hann corner weight
+  is `(pi/(n+1))**4`, which crosses below `1e-6` at patch 99, so the corner
+  band was divided by the floor rather than by the real weight. Measured at
+  640x640, patch 256, stride 128: maximum error 0.94 on data in [0, 1] and 960
+  wrong pixels, identical in float64 because the constant and not the precision
+  was the cause. The floor is now `finfo(dtype).tiny`, the model already used
+  in `metrics.py`, which never reaches a legitimate weight: the smallest 2-D
+  hann corner even at patch 1024 is 8.8e-11. THEORY 9.9 claimed no covered
+  pixel is zeroed by the window, which was true of the window and false of the
+  result.
+- **`reconstruct` returned a view aliasing the caller's patches on a
+  single-patch grid.** Writing to the patches afterwards changed an image the
+  function had already returned, measured as 0.744 becoming 99.0. `extract`
+  guards the mirror image of this case and `reconstruct` did not.
+- **`resize(..., backend="pil")` raised a raw `RuntimeError` on `int8`.** The
+  inbound `clamp(0, 255)` was applied in the input dtype, where the bound 255
+  is unrepresentable, so torch raised `value cannot be converted to type
+  int8_t without overflow` before clamping anything. Every integer dtype now
+  works on both backends, and THEORY 9.4 gained the row for integer tensors on
+  the PIL backend, which it had never specified.
+
+
+### Removed
+
+- The agentic workflow's leftovers. `.superpowers/` at the repository root
+  held 62 files of review diffs and task-progress notes, hidden from
+  `git status` by a nested `.gitignore` containing `*`, so it sat in the tree
+  unseen and reached the 0.5.0 sdist. The three implementation plans under
+  `docs/superpowers/plans/` were 4527 lines of checkbox task lists addressed
+  "For agentic workers", and they shipped to PyPI inside every sdist.
+
+### Added
+
+- `docs/ADR/0004-precision-and-effort-parameters.md`, in `Proposed` status: names the
+  precision policy the library already applies in five places, and designs an `effort=`
+  preset under the constraint that it may change speed and memory but never a returned
+  value. Nothing is implemented; the ADR records the design, the effort per step and the
+  order. It amends ADR 0003 on one measured point, that the exactness predicate is a
+  property of the geometry and the accumulator rather than of the geometry alone.
+- `outreach/`, material for presenting the project publicly, in the shape the
+  sibling projects use: a dated news source at the root and one subfolder per
+  channel, with the rule that no channel text changes before the source does.
+  It publishes no new measurement, and it is pruned from the sdist.
+
+### Changed
+
+- The three design specs that were under `docs/superpowers/specs/` moved to
+  `docs/design/`. They are the record of what was measured before each phase
+  was built, including the spike table that rejected `conv_transpose2d` and
+  `index_add_` before the Rust kernel was written, and Amendment A, which
+  `tests/test_exactness.py` cites for the per-pixel error bound.
+- The sdist is 264 KiB where it was 316 KiB.
+- Nothing ephemeral is kept in the project folder any more. `accel/target`
+  had reached 269 MiB of Rust build output, and `dist/`, `.pytest_cache` and
+  `src/patchcraft.egg-info` were accumulating alongside it. The caches are
+  now redirected by user-level environment variables, joining the ones this
+  machine already had for uv, ruff, mypy, pip and `__pycache__`, and
+  `CONTRIBUTING.md` records the convention and why it is not committed here.
+- `.vscode/settings.json` stays tracked and is pruned from the sdist instead.
+- **The versioning rule was self-contradictory and is corrected.** One row said
+  an output value change is a `0.Y.0`, the next said a fix is a `0.y.Z`, and a
+  bug fix satisfies both, so the table made every fix a minor and left patch
+  releases unable to fix anything. It also contradicted the project's own
+  history: `0.2.1` changed `stitch(weight="hann")` output for every geometry
+  and shipped as a patch. The rule now turns on whether the contract moved or
+  the implementation stopped violating it, which sorts `0.2.1`, `0.3.0`,
+  `0.5.0` and `0.5.2` correctly. `CONTRIBUTING.md` carries the rule with those
+  four worked, and GUIDE section 8 item 6 no longer cites a patch release as
+  an example of what only a minor may do.
+  Its `${workspaceFolder}/.venv` path is not broken: `.venv` is a directory
+  junction to the real environment outside the tree, so the setting resolves
+  and is portable to any checkout following the same convention.
+
 ## [0.5.1] - 2026-09-02
 
 > Numbered `0.6.0` while it was being built. Corrected before release: the
@@ -587,7 +666,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.1...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.2
 [0.5.1]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.1
 [0.5.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.0
 

{patchcraft-0.5.1 → patchcraft-0.5.2}/CONTRIBUTING.md

@@ -68,6 +68,36 @@ CARGO_TARGET_DIR=/tmp/pc-target uv sync --extra cache --extra dev
 
 ---
 
+## Nothing ephemeral lives in the project folder
+
+Caches, build output and virtual environments are kept off the tree, because
+they are large, regenerable and machine-specific. They are redirected by
+user-level environment variables rather than by anything committed here: a
+machine path in `pyproject.toml` would be wrong for every other machine and
+for CI, which is why one was removed in 0.3.0.
+
+| Variable | Sends |
+|---|---|
+| `CARGO_TARGET_DIR` | the Rust build output, which reached 269 MiB inside `accel/target` before it was redirected |
+| `PYTEST_ADDOPTS=-o cache_dir=...` | `.pytest_cache` |
+| `RUFF_CACHE_DIR`, `MYPY_CACHE_DIR` | the linter caches |
+| `UV_CACHE_DIR`, `PIP_CACHE_DIR` | downloaded wheels |
+| `PYTHONPYCACHEPREFIX` | `__pycache__` |
+
+The virtual environment lives outside the tree too; see
+[`docs/AUXILIARY.md`](docs/AUXILIARY.md).
+
+Two directories still appear during a build and are gitignored: `build/` and
+`src/patchcraft.egg-info/`, both setuptools working state. They exist only
+while you build, and redirecting them would need a machine path in a tracked
+file, which is the thing this section is avoiding.
+
+Three files are written into `src/patchcraft/` by an editable install and
+are gitignored: the compiled `_accel_native`, the generated `_version.py`, and
+`__pycache__`. Those have to be there for the package to import.
+
+---
+
 ## Layout
 
 ```
@@ -137,7 +167,11 @@ PatchCraft/
 │   ├── FOCO-1.0.md                 what 1.0 freezes and the blockers in the way
 │   ├── ADR/                        one file per decision that shaped the API
 │   ├── STUDIES/                    background reading behind those decisions
-│   └── superpowers/                the design specs and implementation plans per work phase
+│   └── design/                     one spec per work phase: the alternatives measured and the decision
+├── outreach/                       material for presenting the project publicly, not shipped
+│   ├── README.md                   how it is organized and what to check before publishing
+│   ├── 2026-09-03-lancamento.md    the dated news source every channel text derives from
+│   └── linkedin/                   post (short) and artigo (long), each in PT and EN
 └── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
 ```
 
@@ -186,13 +220,35 @@ promise that nothing does.
 
 That fixes what each digit is for here:
 
+The question that decides it is not "did a returned value change". A bug fix
+changes returned values by definition, and if that forced a `0.Y.0` then a
+patch release could never fix anything. The question is **whether the contract
+moved, or whether the implementation stopped violating it**:
+
 | Change | Bump | Why |
 |---|---|---|
-| An output value, a signature, a name or documented behaviour changes | `0.Y.0` | Resolvers stop at the y boundary, so this is where a break belongs |
-| New functionality that breaks nothing, or a fix | `0.y.Z` | Anyone pinned to the y-series should get it |
+| The documented contract moves: a signature, a name, or behaviour the documentation described as correct | `0.Y.0` | Code that was right against the old documentation can now be wrong |
+| The implementation stops violating the contract, however visibly | `0.y.Z` | The documentation always promised this; only the code was wrong |
+| New functionality that breaks nothing | `0.y.Z` | Anyone pinned to the y-series should get it |
 | Documentation, tests, CI, packaging or tooling only | `0.y.Z` | Still a release if it is published, still no break |
 | Nothing published | nothing | Accumulate under `[Unreleased]` |
 
+The project's own history sorts cleanly under that rule, and does not sort
+under any rule keyed on whether values changed:
+
+- `0.2.1` rewrote the hann window, changing `stitch(weight="hann")` output for
+  **every** geometry. THEORY §9.9 had promised no covered pixel is zeroed by
+  the window; the old window zeroed 108 of 144 pixels in one measured case. A
+  violation, so a **z**, and it shipped as one.
+- `0.5.2` floored the `stitch` denominator by the dtype's tiny instead of an
+  absolute `1e-6`, changing hann output at patch 99 and above. The same
+  promise, the same kind of violation, so also a **z**.
+- `0.3.0` moved `stitch` output by ULPs through a different summation order.
+  Nothing was wrong before, so behaviour the documentation endorsed changed.
+  A **y**.
+- `0.5.0` made `tilings` return 73 specs where it returned 100. The
+  enumeration's output set is the contract. A **y**.
+
 After 1.0 the ordinary reading applies: breaking is major, additive is minor,
 fixed is patch. What 1.0 freezes is written in
 [`docs/FOCO-1.0.md`](docs/FOCO-1.0.md).

{patchcraft-0.5.1 → patchcraft-0.5.2}/MANIFEST.in

@@ -32,6 +32,8 @@ recursive-include tools *.py
 
 prune lab
 prune archive
-prune .superpowers
 prune .github
 prune .vscode
+# Presentation material, not source. It is tracked, so the file finder offers
+# it and only this line keeps it out.
+prune outreach

{patchcraft-0.5.1 → patchcraft-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.1
+Version: 0.5.2
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT

{patchcraft-0.5.1 → patchcraft-0.5.2}/docs/ADR/0003-reversibility-classes.md

@@ -3,6 +3,7 @@
 - **Status:** Proposed
 - **Date:** 2026-08-04
 - **Deciders:** Leonardo Marques de Souza
+- **Amended by:** [ADR 0004](0004-precision-and-effort-parameters.md), which measures the exactness predicate below to be a property of the geometry **and the accumulator**, not of the geometry alone: with a `float64` accumulator, 76 of 76 sampled legal geometries are bit-exact where a `float32` accumulator gives 45, and those 45 are exactly the power-of-two ones.
 - **Relates to:** [ADR 0001](0001-patch-extraction-api.md), [`THEORY.md`](../THEORY.md) §0, §9, [`STUDIES/2026-08-04-patch-techniques.md`](../STUDIES/2026-08-04-patch-techniques.md) §4, §5
 
 ## Context

patchcraft-0.5.2/docs/ADR/0004-precision-and-effort-parameters.md

@@ -0,0 +1,227 @@
+# ADR 0004: naming the precision policy, and an effort preset that may not change values
+
+- **Status:** Proposed
+- **Date:** 2026-09-03
+- **Deciders:** Leonardo Marques de Souza
+- **Relates to:** [ADR 0003](0003-reversibility-classes.md) (which this amends on one point), [`THEORY.md`](../THEORY.md) §9.1, §9.2, §9.9, [`FOCO-1.0.md`](../FOCO-1.0.md) §1, [`PERFORMANCE.md`](../PERFORMANCE.md)
+
+## Context
+
+### The library already has a precision policy. It has no name.
+
+Five places decide precision on the caller's behalf, none of them visible from a call site:
+
+| Site | The choice made for you |
+|---|---|
+| `reconstruct.py:55`, `stitch.py:189` | `float16` and `bfloat16` accumulate in `float32`, rounding once on return |
+| `stitch.py:229` | the denominator is floored by `clamp(min=1e-6)`, an absolute constant |
+| `metrics.py:67`, `:123` | accumulation promotes to `float64` whatever the input was |
+| `metrics.py:164` | `clamp_min(finfo(float64).tiny)` before the PSNR logarithm |
+| `resize.py:47`, `:148` | every cross-backend conversion passes through normalised `float32` in [0, 1] |
+
+So the question is not whether to introduce a precision concept. The concept is already
+here, applied by default and unnamed. The question is whether to give it a name.
+
+### What forced the question
+
+A user with a `uint8` image cannot use the library at all. `extract` raises
+`NotImplementedError: "im2col_out_cpu" not implemented for 'Byte'`, and `reconstruct` and
+`stitch` reject every non-floating-point dtype outright. The only route is `.float()`
+first, which on an 8192x8192 tile at patch 512 stride 256 turns a 721 MiB patch stack into
+2883 MiB.
+
+The owner's framing of the problem is the right one and worth quoting, because it rules out
+the easy answer: `input(byte) -> operation(???) -> output(byte)` is not the same thing as
+`input(byte) -> operation(byte) -> output(byte)`. Returning the input dtype after widening
+internally gives back neither the memory nor the time.
+
+### Measurements that shaped the design
+
+All taken on 2026-09-03, CPU, torch 2.14.0+cpu, on the machine named in
+[`PERFORMANCE.md`](../PERFORMANCE.md).
+
+**Byte-native averaging is exact, and it is the fastest option.** The identity
+`sum(a_i)//k == sum(a_i//k) + sum(a_i mod k)//k` holds for every `k`, verified exhaustively
+for k in 2..5 and over 200,000 random samples up to k=16. The quotient accumulator always
+fits `uint8`; the remainder accumulator holds `k*(k-1)` and so fits `uint8` only for k <= 16.
+At k=4 over 3.1M pixels: 2.51 ms byte-native, 4.24 ms widening to `int16`, 6.19 ms via
+`float32`, with accumulators of 3.0, 6.0 and 12.0 MiB.
+
+**A first measurement of this said the opposite, and the error is instructive.** Writing
+the byte path as `(x // k).sum(0)` measured 9x slower than float. `torch`'s `uint8.sum()`
+promotes to `int64` silently, so that benchmark was the very
+`input(byte) -> operation(???)` shape the design exists to avoid. Only accumulators declared
+`uint8` measure the thing.
+
+**What decides speed is not integer versus float. It is whether the divisor is a power of
+two.** The same arithmetic, the same k, written with `//` and `%` against `>>` and `&`:
+
+| k | via `//` and `%` | via `>>` and `&` | ratio |
+|---|---|---|---|
+| 2 | 22.51 ms | 1.39 ms | 16.1x |
+| 4 | 40.17 ms | 2.53 ms | 15.9x |
+| 8 | 76.46 ms | 5.09 ms | 15.0x |
+| 16 | 148.71 ms | 9.71 ms | 15.3x |
+
+x86 has no SIMD integer division. A power-of-two divisor turns it into a shift, which
+vectorises.
+
+**The same idea generalises to floats, and fixes a defect the library papered over.**
+THEORY §9.2 records that a constant `float16` image at 10000.0 with `ph=3, stride=1`
+returned `inf` in 144 of 256 pixels, and that `float32` promotion was added to prevent it.
+Reproduced exactly. Scaling each patch by `1/k` before the fold keeps the numerator at
+1.0e+04 against a finite `float16` maximum of 6.55e+04, produces no `inf`, and returns the
+image with zero error, in a 2 byte per pixel accumulator instead of 4. On ordinary [0, 1]
+data it costs 5.96e-08. On this machine it is nonetheless 1.35x slower than the promotion,
+because torch's CPU `float16` kernels are weak. The advantage is real but it is per-dtype
+and must be measured, never assumed.
+
+**`bfloat16` is in the wrong bucket.** THEORY §9.2 justifies promoting both half formats by
+`float16` overflowing its finite maximum of 65504, then applies the rule to `bfloat16` too.
+`bfloat16` carries `float32`'s exponent: on the same case its numerator reached 9.01e+04
+with no `inf` and a finite maximum of 3.39e+38. Promoting it buys precision, since it has
+7 mantissa bits against `float16`'s 10, not range. The stated reason covers one of the two.
+
+## Decision
+
+Three fine-grained knobs, each naming one existing policy, plus one preset under a hard
+constraint. **Nothing here is implemented. This ADR records the design and the order.**
+
+### The knobs
+
+| Name | Type | Values | Default | Governs | Borrowed from |
+|---|---|---|---|---|---|
+| `accum_dtype` | `torch.dtype \| None`, keyword-only | any dtype at least as wide as the input, of the same kind | `None`, meaning today's rule | where the numerator and count map live in `reconstruct` and `stitch`. Does not change the return dtype. | `numpy.sum(dtype=)`, documented as "the accumulator in which the elements are summed", and `torch.sum(dtype=)` |
+| `rounding_mode` | `Literal["trunc","floor","nearest_even"] \| None` | as listed | `None` | the single rounding event on `stitch`'s final divide, once `stitch` accepts integers. Not offered on `reconstruct`. | `torch.div(rounding_mode=)`, same name, two of three values; the tie-break vocabulary from stdlib `decimal` |
+| `antialias` | `bool \| None` | `True`, `False`, `None` | `None`, meaning whatever the backend does today | whether the torch `resize` backend prefilters before downsampling | `torch.nn.functional.interpolate` and `torchvision.transforms.v2.functional.resize`, verbatim |
+
+`None` is a sentinel on every one of them, never a spelled-out default. Without it a preset
+cannot distinguish "unspecified" from "explicitly asked for the current value", and the
+resolver has nothing to key on.
+
+**Not `accumulate=`.** It is a verb where every precedent is a noun, it does not say the
+value is a dtype, and `numpy` already owns the identifier for `ufunc.accumulate`, which is a
+running scan and a different operation.
+
+**No `rounding_mode` on `reconstruct`.** For unmodified patches every covering value is the
+same `v`, so the sum is exactly `k*v` and `k*v // k == v` for every `k`, in every dtype.
+`reconstruct` does not round. A knob there would advertise a decision the function does not
+make.
+
+### The preset
+
+`effort: Literal["balanced", "fast"] | None = None`, keyword-only, on `reconstruct`,
+`stitch`, `extract` and `Patchify.__init__`. `Patchify` is the reason it exists: inside a
+`Compose` there is no per-call keyword, so a stored string is the only way a policy reaches
+a data pipeline.
+
+One axis, following x264 and x265, whose presets are all speed and whose quality is a
+separate orthogonal knob. Not `fast`/`quality`/`precise`: that trio spans three axes and
+admits no correct ordering, and it leaves the caller who wants exact-and-fast, which is the
+common case here, nothing to pass. No superlative at either end, so a third rung can be
+added later without a lie, which is the wall both `torch` ("highest") and JAX (`HIGHEST`)
+hit.
+
+**The constraint, and it is the whole decision:**
+
+> `effort=` may change speed and memory. It may never change a returned value. Anything
+> that changes values requires an explicit knob.
+
+That constraint is what separates this from `-ffast-math`, which is structurally the same
+proposal: a name promising speed whose effect changes results. Its failure modes are all
+reachable here in miniature. It deletes the caller's own safety checks, a compiler update
+silently reinterpreted it more aggressively and broke shipping software with no source
+change, and it escapes the caller's scope entirely by setting process-wide floating point
+mode. The constraint also makes the preset falsifiable, which is what this project's
+contract style demands: "fast" is unprovable, but "`effort="fast"` is bit-identical to
+`effort="balanced"`" is a test id.
+
+`effort="fast"` may therefore expand only into: permitting the native accelerator without
+an environment variable, which structurally replaces the `PATCHCRAFT_ACCEL` global that is
+already an unnamed preset today; permitting the shift-and-mask integer path where the
+coverage map makes it bit-identical to the divide; and returning views where aliasing is
+provably safe, which is a memory choice and needs its own sub-knob rather than hiding here.
+`effort="balanced"` expands to nothing at all: it is today's behaviour, exhaustively.
+
+Ship `patchcraft.effort_options(name) -> dict` returning the literal expansion, after
+`torch._inductor.list_mode_options`, so the preset is never a black box and the knobs stay
+the source of truth.
+
+**Precedence: the preset seeds defaults, explicit keyword arguments override, and argument
+order is irrelevant.** After x265, which promises exactly that in prose. Not mutual
+exclusion: `torch.compile` raises on preset-plus-options and the bill is visible, because
+`max-autotune-no-cudagraphs` exists as a whole extra public name purely to work around it.
+
+### Amendment to ADR 0003
+
+**The exactness predicate is a property of the geometry *and the accumulator*, not of the
+geometry alone.** ADR 0003 states the round trip is bit-exact iff every coverage count is a
+power of two. Measured over 76 legal square geometries on `float32` input: with a `float32`
+accumulator, 45 of 76 are exact, and those 45 are exactly the power-of-two geometries, so
+the predicate is perfectly predictive. With a `float64` accumulator, **76 of 76 are exact**.
+
+The predicate as written carries an unstated premise, which is the accumulator the library
+happens to use today. ADR 0003 should say so. It also means `accum_dtype=torch.float64`
+would offer unconditional bit-exactness for `float32` input at twice the accumulator memory,
+which is a stronger guarantee than the library currently advertises.
+
+**And the predicate does not govern integers at all.** A `uint8` round trip through an
+`int32` accumulator was exact on all six geometries tested, including three whose count maps
+are not powers of two, for the reason given above: the sum is exactly `k*v`. Gating an
+integer path on the float predicate would be a category error.
+
+## Consequences
+
+### Effort, each step independently shippable
+
+| Step | Size | Breaks frozen surface | When |
+|---|---|---|---|
+| 0. Record this ADR, and qualify the four copies of "widening the dtype does not help" | 0.5 to 1 day | no | before 1.0, and it is the only item that must be |
+| A. Fix three defects as bugs, no knob | done, 2026-09-03 | no signature change | done before 1.0, as planned |
+| 1. `extract` accepts the five integer dtypes, by adding them to the fast-path set | ~1 day | no | after 1.0, never alone |
+| 2. Exact integer `reconstruct`, unrestricted, `int32` accumulator, every legal geometry | 4 to 6 days | no signature change | after 1.0, shipped with step 1 as one 1.1 |
+| 3. Byte-native `uint8` quotient-and-remainder path | 2 to 3 days | no | do not build yet: 1.7x over an `int32` accumulator, at the cost of a second, different predicate on the doc surface |
+| 4. `accum_dtype=` on `reconstruct` and `stitch` | 1 day, 2 alongside step 2 | yes, signature | after 1.0 |
+| 5. `rounding_mode=` on `stitch` | 1 day | yes, signature | after 1.0, and only if a real caller appears |
+| 6. `effort=` and `effort_options()` | 1 day of code, 3+ of contract | yes, signature, four sites | after 1.0, after 1 and 2 have shipped |
+| 7. Bool support, where the inverse is a majority vote | 3 to 4 days | it is a 21st public name | 1.1 at the earliest, a function rather than a parameter |
+
+### Order
+
+Record the design. Fix the three defects as bugs on their own merits, because folding them
+into a `precise` tier would sell the absence of a bug as a quality level. **Step A landed on
+2026-09-03**, and the three were the `stitch` denominator floor, the `reconstruct`
+single-patch aliasing and the `resize` inbound clamp on a dtype that cannot hold the bound.
+The remaining items named in the audit, the `bfloat16` justification in THEORY 9.2 and the
+resize antialias gap, are still open and are not defects of the same kind: the first is a
+documentation correction and the second is a user-facing choice that needs its own release. Document, at zero
+cost, the rounding policy already in force. Freeze 1.0 at 20 names with no new parameters.
+Then 1.1 brings steps 1 and 2 together and unrestricted. Then stop and wait for a user:
+only if one appears do the knobs follow, and the preset last of all.
+
+### What not to do
+
+- Do not gate the integer path on the power-of-two predicate. It is a float predicate.
+- Do not let any preset change a returned value.
+- Do not ship step 1 without step 2. `extract` accepting `uint8` while `reconstruct` rejects
+  it makes THEORY §9.1 and §9.2 false as the matched pair they are written as.
+- Do not make any of this a module global, an environment variable, or a context manager
+  that mutates torch state.
+- Do not offer `rounding="nearest"` without saying which tie-break.
+- Do not add a knob to `accel_available()`. It is one of the 20 frozen names with a pinned
+  zero-argument signature.
+
+### Open questions, for the decision this ADR defers
+
+1. Does `accum_dtype` change only where the sum lives, or also what comes back?
+   `reconstruct` casts back to `patches.dtype`; `metrics` returns `float64` unconditionally.
+   The two are inconsistent today and the knob would expose it.
+2. If `accum_dtype=float64` makes every geometry exact, does the headline contract become
+   "exact, at this accumulator width" rather than "exact on these geometries"? That reads
+   as a stronger promise and needs its own falsification suite before it is made.
+3. Are steps 1 to 3 a `0.Y.0` or a `z` bump? The project shipped the mirror-image change
+   once: 0.2.1 added the `reconstruct` integer guard, turning a raw `NotImplementedError`
+   into a framed `ValueError`.
+4. Integers with `dilation > 1`: a framed `ValueError`, or torch's raw error in that corner?
+5. CUDA. Everything here was measured on CPU, and the accelerator refuses non-CPU tensors
+   outright. No accept text may say "integers work" without a device qualifier.

{patchcraft-0.5.1 → patchcraft-0.5.2}/docs/GUIDE.md

@@ -812,7 +812,7 @@ Five things this project does not claim.
 
 **5. The accelerated and the pure paths are equal by test, on two platforms out of five.** Every geometry in the suite is checked with `torch.equal` against the pure path, but that job runs on Ubuntu and Windows x86_64 only. The macOS and aarch64 wheels are built and their contents are checked, and nothing has ever executed their kernel in CI.
 
-**6. Pre-1.0 means output values can change when the middle digit moves.** One release rewrote the hann window, so `stitch(..., weight="hann")` returns different values than the release before it did for every geometry, and the round-trip contract did not change. That is the kind of change a new `0.y` is allowed to carry and a new `0.y.z` is not. [CHANGELOG.md](../CHANGELOG.md) records each one together with the measurement that motivated it.
+**6. Pre-1.0 means output values can change in either kind of release, for two different reasons.** A new `0.y` may move behaviour the documentation endorsed, which is what happened when `tilings` began returning 73 specs where it returned 100. A new `0.y.z` may change values too, but only by making the code match a promise the documentation was already making: twice now that has been the `stitch` hann denominator, once for a window that zeroed covered pixels and once for a floor that swallowed the corner band. [CHANGELOG.md](../CHANGELOG.md) records each one together with the measurement that motivated it, and [CONTRIBUTING.md](../CONTRIBUTING.md) carries the rule.
 
 The backlog that closes these is [FOCO-1.0.md](FOCO-1.0.md).
 
@@ -855,7 +855,7 @@ Installing from the sdist compiles the accelerator when a Rust toolchain is pres
   author  = {Souza, Leonardo Marques de},
   title   = {PatchCraft: image patch extraction, reconstruction, pairing
              and seam-aware stitching},
-  version = {0.5.1},   % check CHANGELOG.md for the release you used
+  version = {0.5.2},   % check CHANGELOG.md for the release you used
   year    = {2026},
   url     = {https://github.com/LeoPR/PatchCraft}
 }

{patchcraft-0.5.1 → patchcraft-0.5.2}/docs/THEORY.md

@@ -111,9 +111,9 @@ Visualizing the count map along one axis (image cols 0..7, `ph=4`, `sh=2`):
 
 **Dilation.** `F.fold` does not support dilation in the same way as `F.unfold`: for `d > 1` the patch footprint skips pixels, and `fold` would deposit the sparse contributions into a canvas that is not the image. Rather than building a custom scatter, we refuse `dilation != 1` at reconstruction time with a clear `ValueError`. Callers who extracted with dilation are expected to consume patches directly (e.g., as features) and not round-trip.
 
-**Stride maior que patch (lacunas).** Quando `sh > ph` ou `sw > pw`, o grid pula pixels: a soma `fold(...)` tem zeros nessas posições, e qualquer divisão (incluindo pelo clamp `min=1e-6`) produz pixels com valor arbitrário, ou seja, síntese de dado, exatamente o que §1 proíbe ao escolher truncamento como única política de borda. Recusamos a condição com `ValueError` logo na entrada de `reconstruct`. Consumidores que querem features esparsas (kernels, classificadores) usam apenas `extract`, onde `stride > patch_size` é aceito sem objeções, e não tentam round-trip.
+**Stride maior que patch (lacunas).** Quando `sh > ph` ou `sw > pw`, o grid pula pixels: a soma `fold(...)` tem zeros nessas posições, e qualquer divisão (incluindo pelo piso do denominador) produz pixels com valor arbitrário, ou seja, síntese de dado, exatamente o que §1 proíbe ao escolher truncamento como única política de borda. Recusamos a condição com `ValueError` logo na entrada de `reconstruct`. Consumidores que querem features esparsas (kernels, classificadores) usam apenas `extract`, onde `stride > patch_size` é aceito sem objeções, e não tentam round-trip.
 
-**Design decision.** `patchcraft.reconstruct(patches, image_shape, stride, dilation=1) -> Tensor[C, H, W]` uses `F.fold` followed by division by the overlap-count map (computed once, same-geometry fold of ones). Raises `ValueError` when `dilation != 1` **ou quando `sh > ph` ou `sw > pw`** (cobertura parcial é proibida). `image_shape` is `(C, H, W)` and must match the geometry implied by the patch grid; inconsistent shapes raise `ValueError`. The count map clamp (`min=1e-6`) existe apenas para absorver ruído float em pixels totalmente cobertos, nunca para mascarar buracos de cobertura. Output dtype matches input.
+**Design decision.** `patchcraft.reconstruct(patches, image_shape, stride, dilation=1) -> Tensor[C, H, W]` uses `F.fold` followed by division by the overlap-count map (computed once, same-geometry fold of ones). Raises `ValueError` when `dilation != 1` **ou quando `sh > ph` ou `sw > pw`** (cobertura parcial é proibida). `image_shape` is `(C, H, W)` and must match the geometry implied by the patch grid; inconsistent shapes raise `ValueError`. O piso do denominador existe apenas para absorver ruído float em pixels totalmente cobertos, nunca para mascarar buracos de cobertura; desde 0.5.2 ele é `finfo(dtype).tiny`, que nunca alcança um peso legítimo (o menor canto hann 2-D, mesmo em patch 1024, é 8,8e-11). Output dtype matches input.
 
 ## 2.5 Stitching modified patches
 
@@ -129,7 +129,7 @@ The standard trick is to weight each patch's contribution by a 2-D window whose
 
 For *unmodified* patches, every `patch_k(i_k, j_k)` equals `img(x, y)` (definition of `extract`), so the numerator factors as `img(x, y) · denominator(x, y)`, and the output is `img(x, y)` exactly, so round-trip is preserved for any kernel as long as the denominator at `(x, y)` is positive. For *modified* patches, contributions are weighted by how central `(x, y)` is to each contributing patch, so seams are attenuated.
 
-**Implementation.** Two `F.fold` calls: one on the weighted patches (numerator), one on the kernel replicated across the `L` patch slots (denominator). Identical geometry to `reconstruct`'s count-map fold; same `clamp(min=1e-6)` on the denominator to absorb float noise.
+**Implementation.** Two `F.fold` calls: one on the weighted patches (numerator), one on the kernel replicated across the `L` patch slots (denominator). Identical geometry to `reconstruct`'s count-map fold; the denominator carries the same floor. Since 0.5.2 that floor is `torch.finfo(dtype).tiny` and no longer an absolute `1e-6`: the 2-D hann corner weight is `(π/(n+1))⁴`, which falls below `1e-6` at patch 99, so every larger hann stitch had its corner band divided by the floor instead of by the real weight. Medido a 640×640, patch 256, stride 128: erro máximo 0,94 em dado [0, 1] e 960 pixels errados, idêntico em float64 porque a causa era a constante e não a precisão.
 
 **Window kernels.**
 
@@ -319,6 +319,7 @@ Retorna `PatchPair(lr_patches, hr_patches, metas)` (frozen dataclass com `__slot
 - `resample=None` → default por backend (LANCZOS pra PIL, bilinear pra torch).
 - Tensor inteiro com `backend == "torch"`: interpolação em float, cast de volta com **round + clamp** ao range do dtype (bicubic ultrapassa o range de entrada legitimamente, e um cast cru wrapava: `-9.0 → 247` em uint8; corrigido em 0.2.1).
 - Tensor float com `backend == "pil"`: o hop uint8 pelo PIL **clampa a `[0, 1]`**; valores fora desse intervalo não sobrevivem nesse backend (comportamento documentado, não exceção).
+- Tensor inteiro com `backend == "pil"`: o mesmo hop uint8 **clampa a `[0, 255]`** na ida e satura ao range do dtype na volta. Os dois backends recusam-se a dar a volta (`wrap`), que é a classe de defeito da 0.2.0, mas saturam em ranges diferentes de propósito: o torch preserva 300 e −9 num int32, o PIL não. Até 0.5.1 a ida fazia `clamp(0, 255)` no dtype de entrada, e num `int8` o próprio limite era irrepresentável, então o torch levantava `RuntimeError` cru antes de limitar coisa alguma.
 
 **Rejeita (`ValueError`):**
 - `Tensor` em CUDA com `backend == "pil"` (PIL não enxerga GPU, então exige `.cpu()` explícito do caller).
@@ -439,7 +440,7 @@ The blending counterpart to `reconstruct`. Same fold geometry, same rejections;
 - `dtype` and `device` preserved on output.
 
 **Sinaliza (não exceção):**
-- (nenhuma condição sinalizada; as três janelas são estritamente positivas desde 0.2.1, então nenhum pixel coberto é zerado pela janela)
+- (nenhuma condição sinalizada; as três janelas são estritamente positivas desde 0.2.1, então nenhum pixel coberto é zerado pela janela. Até 0.5.1 essa frase era verdadeira quanto à janela e falsa quanto ao resultado, porque o piso absoluto `1e-6` do denominador corrompia a banda de canto a partir de patch 99; corrigido em 0.5.2.)
 
 **Rejeita (`ValueError` / `TypeError`):**
 - `patches` not a tensor (`TypeError`).

{patchcraft-0.5.1 → patchcraft-0.5.2}/src/patchcraft/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.1'
-__version_tuple__ = version_tuple = (0, 5, 1)
+__version__ = version = '0.5.2'
+__version_tuple__ = version_tuple = (0, 5, 2)
 
-__commit_id__ = commit_id = 'g375362d3b'
+__commit_id__ = commit_id = 'g6090abd8c'

{patchcraft-0.5.1 → patchcraft-0.5.2}/src/patchcraft/reconstruct.py

@@ -85,7 +85,14 @@ def reconstruct(
         # reconstruction is a pure rearrangement -- no fold, no count map, and
         # no widening for half precision (nothing accumulates).
         grid = patches.reshape(num_h, num_w, c, ph, pw)
-        return grid.permute(2, 0, 3, 1, 4).reshape(c, h, w)
+        out = grid.permute(2, 0, 3, 1, 4).reshape(c, h, w)
+        if out.untyped_storage().data_ptr() == patches.untyped_storage().data_ptr():
+            # Single-patch grid: the permuted view is already contiguous, so
+            # reshape aliased the caller's patches and a later write to them
+            # would change an image this function already returned. `extract`
+            # guards the mirror image of this case.
+            out = out.clone()
+        return out
 
     # Half-precision inputs overflow inside F.fold, which accumulates the sum
     # of all overlapping patches before the count-map division (fp16 max is

{patchcraft-0.5.1 → patchcraft-0.5.2}/src/patchcraft/resize.py

@@ -57,8 +57,11 @@ def _tensor_to_pil_u8(tensor: torch.Tensor) -> PILImage:
     else:
         # Integer tensors: clamp to the uint8 range before casting, otherwise
         # values outside [0, 255] wrap (300 -> 44) -- same defect class as the
-        # 0.2.0 bicubic overshoot wrap on the torch backend.
-        arr = tensor.clamp(0, 255).cpu().numpy().astype(np.uint8)
+        # 0.2.0 bicubic overshoot wrap on the torch backend. Widen first,
+        # because the bound itself has to be representable: `clamp(0, 255)` on
+        # an int8 tensor raised `value cannot be converted to type int8_t
+        # without overflow` before clamping anything.
+        arr = tensor.to(torch.int32).clamp(0, 255).cpu().numpy().astype(np.uint8)
     c = arr.shape[0]
     if c == 1:
         return Image.fromarray(arr[0], mode="L")
@@ -184,7 +187,13 @@ def resize(
             pil_out = _resize_pil(pil_in, target_size, resample)
             tensor_out = _pil_to_tensor_f32(pil_out)
             if not original_dtype.is_floating_point:
-                tensor_out = (tensor_out * 255).round()
+                # Round AND clamp, the same pair the torch branch applies.
+                # Without the clamp a narrow signed dtype cannot represent the
+                # 0..255 range the PIL hop produces, and the cast raised a raw
+                # `RuntimeError: value cannot be converted to type int8_t
+                # without overflow` instead of returning a saturated value.
+                info = torch.iinfo(original_dtype)
+                tensor_out = (tensor_out * 255).round().clamp(info.min, info.max)
             return tensor_out.to(original_dtype)
         return _resize_torch(image, target_size, resample)
 

{patchcraft-0.5.1 → patchcraft-0.5.2}/src/patchcraft/stitch.py

@@ -223,7 +223,13 @@ def stitch(
     den_w = _fold_window_1d(ww, w, num_w, sw)
     den = den_h.unsqueeze(1) * den_w.unsqueeze(0)
 
-    # clamp(min=1e-6): geometry validation guarantees coverage and all three
-    # windows are strictly positive, so the denominator is genuinely
-    # positive; the clamp is a defensive no-op kept from the fold version.
-    return (numerator / den.clamp(min=1e-6)).to(patches.dtype)
+    # The floor is the dtype's own smallest normal, not an absolute constant.
+    # Geometry validation guarantees coverage and all three windows are
+    # strictly positive, so the denominator is genuinely positive and this
+    # only guards a true zero. An absolute 1e-6 was not the no-op its comment
+    # claimed: the 2-D hann corner weight is (pi/(n+1))**4, which falls below
+    # 1e-6 at patch 99, so every larger hann stitch had its corner band
+    # divided by 1e-6 instead of by the real weight. Measured at 640x640,
+    # patch 256, stride 128: max error 0.94 on data in [0, 1], 960 pixels
+    # wrong, identical in float64 because it was never a precision problem.
+    return (numerator / den.clamp_min(torch.finfo(den.dtype).tiny)).to(patches.dtype)

{patchcraft-0.5.1 → patchcraft-0.5.2}/src/patchcraft.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.1
+Version: 0.5.2
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT

{patchcraft-0.5.1 → patchcraft-0.5.2}/src/patchcraft.egg-info/SOURCES.txt

@@ -26,13 +26,11 @@ docs/USAGE.md
 docs/ADR/0001-patch-extraction-api.md
 docs/ADR/0002-patchify-transform.md
 docs/ADR/0003-reversibility-classes.md
+docs/ADR/0004-precision-and-effort-parameters.md
 docs/STUDIES/2026-08-04-patch-techniques.md
-docs/superpowers/plans/2026-09-01-fase1-bugs-performance.md
-docs/superpowers/plans/2026-09-01-fase2-acel.md
-docs/superpowers/plans/2026-09-01-fase3-g1-predicado.md
-docs/superpowers/specs/2026-09-01-fase1-bugs-performance-design.md
-docs/superpowers/specs/2026-09-01-fase2-acel-design.md
-docs/superpowers/specs/2026-09-01-fase3-g1-predicado-design.md
+docs/design/2026-09-01-fase1-bugs-performance.md
+docs/design/2026-09-01-fase2-acelerador.md
+docs/design/2026-09-01-fase3-predicado.md
 src/patchcraft/__init__.py
 src/patchcraft/_accel.py
 src/patchcraft/_foldgeom.py