patchcraft 0.5.3__tar.gz → 0.5.4__tar.gz

{patchcraft-0.5.3 → patchcraft-0.5.4}/AGENTS.md

@@ -89,7 +89,30 @@ literal directory of that name on Linux.
 `tools/check_dist.py` holds the matching allowlist. Adding a top-level
 directory means updating both. The gate will tell you; do not silence it.
 
-### I10. Do not invent what already exists
+### I10. An ADR carries the choice, not the research behind it
+
+Before writing one, split what is being said into what is **determined** and
+what is **chosen**, and put only the second in the ADR.
+
+A name is determined: which identifier a parameter carries is a fact about the
+ecosystem the caller already imports, and picking one by taste is a guess made
+permanent by a frozen surface. A measurement is determined. A benchmark table is
+determined. Those belong in `docs/STUDIES/`, dated, with the ADR linking to
+them.
+
+What is chosen is whether to do the thing at all, when, and what it costs the
+surface. If that part comes out empty, it was never an ADR: it was a finding,
+and a study is where it goes.
+
+Both ADRs written in 2026-09 failed this on the first draft, in the same way
+and for the same reason, which is that writing down everything you learned feels
+like thoroughness and reads as a lab notebook. ADR 0003 mixed a rule with a
+vocabulary for six transforms that never shipped; ADR 0004 mixed the names,
+which precedent decides, with whether to spend a frozen surface on them, which
+only the owner decides. Both came out clearer once separated, and both were
+caught by the owner asking what the document was for.
+
+### I11. Do not invent what already exists
 
 Check for an official or established solution before writing one. The
 accelerator's packaging, the versioning rule, the citation format and the

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

@@ -6,6 +6,130 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-09-04
+
+### Fixed
+
+- **13 of the 25 resample-mode x integer-dtype combinations raised a raw torch
+  error** instead of resizing. THEORY §9.4 accepts any integer tensor on the
+  `torch` backend and promises interpolation in float with round + clamp on the
+  way back, unconditionally. `_resize_torch` guarded the promotion with
+  `mode in {"bilinear", "bicubic"}`, so an integer tensor reached
+  `F.interpolate` unpromoted under `nearest`, `area` and `nearest-exact` and
+  surfaced `NotImplementedError: "adaptive_avg_pool2d" not implemented for
+  'Int'`, naming an internal op the caller never called. The outbound half of
+  the same function already did the right thing for every integer dtype with no
+  condition on the mode, so only the inbound guard was ever wrong.
+
+  The suite could not catch it because the two parametrizations that would have
+  never crossed: `test_torch_accepts_all_resamples` sweeps all five modes on
+  `torch.rand`, and every integer test used the default mode. The regression is
+  that crossing, 50 cases, plus the upsampling direction because `area` is
+  `adaptive_avg_pool2d` and behaves differently going up.
+
+  Fixing it by promoting everything through `float32` would have traded the
+  loud error for the silent truncation this library exists to prevent, so the
+  promotion width is now derived from the dtype's range: the narrowest float
+  that represents it exactly, `float32` for `uint8`, `int8` and `int16` and
+  `float64` for `int32`. That mirrors `patchcraft.metrics`, which already
+  promotes to `float64` for the same reason. **This also fixes a silent defect
+  that predates the one above**: on the bilinear path an `int32` tensor was
+  already being promoted through `float32`, so `2**24 + 1` came back as
+  `2**24`. Measured on 2026-09-04, on every mode. `int64` remains the one dtype
+  no float covers, and §9.4 now says so rather than implying otherwise.
+
+- **`Cache("~/cache")` created a directory literally named `~`** in the working
+  directory instead of using the home directory. `Path(root)` was used without
+  `expanduser`. Every established library expands and then stops: verified that
+  `torch.hub.set_dir` calls `expanduser` and validates nothing, that pytest's
+  cacheprovider does not validate, and that pip passes `--cache-dir` through.
+  `Cache` now does the same one thing they do.
+
+  The question that found this was whether to reject a `namespace` containing
+  `..`. The answer is no, and the reason is the owner's: it is not this
+  library's job to invent path security, and no library in the ecosystem does
+  it. What it was missing was the one thing they all do. `SECURITY.md` and
+  THEORY §9.5 now say that the path is the caller's and that only `~` is
+  expanded.
+
+
+### Added
+
+- The rule that produced the two rescopings is recorded as invariant I10 in
+  `AGENTS.md`: an ADR carries the choice, not the research behind it. Before
+  writing one, split what is determined from what is chosen and keep only the
+  second; if the chosen part comes out empty it was a finding, and a dated
+  study is where it goes. Both ADRs written this month failed it on the first
+  draft, in the same way, and both were caught by the owner asking what the
+  document was for. `docs/ADR/0001` and `0002` were checked and do not have the
+  problem: they are context, decision, consequences and alternatives, at a
+  hundred lines each.
+- **ADR 0004 separates what is determined from what is chosen, and what is left
+  is nothing.** The owner's point settled the first half: naming is a fact about
+  the ecosystem the caller already imports, not a preference of this project,
+  and choosing by taste would be a guess made permanent by a frozen surface. So
+  the three names are stated as determined by precedent, verified on 2026-09-03
+  against the installed libraries: `numpy.sum` and `torch.sum` take `dtype=`,
+  `torch.div` takes `rounding_mode=` and documents exactly `None`, `"trunc"` and
+  `"floor"`, both `interpolate` and torchvision's `resize` take `antialias=`,
+  and `numpy.ufunc.accumulate` exists, which is the collision that rules out
+  `accumulate=`.
+
+  That narrowing left one apparent question, whether to add the knobs before the
+  1.0 freeze or after, on the stated ground that afterwards each costs a minor
+  release. Applying I10 to it dissolved it, because the premise is false: every
+  one of these is a keyword-only argument with a default, so adding one is
+  additive and can never be a major, and `reconstruct` has no positional-only
+  parameters to make the order matter. Nothing about adding one later is harder
+  than adding one now. With the premise gone, YAGNI, the absence of any external
+  consumer and Strata §9's default verdict all point the same way, and the ADR's
+  own table had already marked every knob "after 1.0" before the question was
+  written on top of it. The document now records a design that is not built, and
+  stays `Proposed` because none of it is implemented rather than because
+  anything is pending.
+- `docs/STUDIES/2026-09-03-precision-measurements.md`. ADR 0004 was carrying
+  its own evidence, which made a 227-line document that read as a lab notebook
+  where a decision was wanted. The measurements moved here, the ADR kept the
+  decision, the names and the order, and it is 176 lines. Each measurement now
+  says what it settled, so a number can be checked without reading the argument
+  that used it.
+
+### Changed
+
+- **ADR 0004 step 0 is done**, which the ADR names as the only item that must
+  land before 1.0: the `reconstruct` docstring's "widening the dtype does not
+  help" now says *input* dtype, and that widening the accumulator does help,
+  with the measurement. It was the one live site; earlier counts of seven
+  included historical and study files that are not edited.
+- **`WeightKind` is declared an open set** in the GUIDE symbol table and in
+  CONTRIBUTING's versioning policy. The choice was made and pinned by test long
+  ago; what did not exist was the sentence a consumer reads before writing an
+  exhaustive `match`.
+- Four one-line corrections found by the 2026-09-04 audit: FOCO §1 counted
+  "four things" over a list of five; MAP and CONTRIBUTING said ten invariants
+  after I10 made it eleven; AGENTS.md claimed both rescoped ADRs "shrank by a
+  third" when ADR 0003 grew; and `tilings`' docstring promised an ordering by
+  `(patch_size, stride)` that the function does not produce. The docstring now
+  states the measured order (patch size ascending, exact tile first within each)
+  rather than the function changing, because nothing depends on the order and
+  a change would be behaviour.
+- **ADR 0003 is accepted, after being rescoped to what it actually governs.**
+  Its first draft decided two things at once: a rule about how an exactness
+  claim is written, and a three-letter vocabulary plus naming policy for six
+  transforms that were under consideration. A month later the rule was
+  governing the code and the vocabulary had been used nowhere: `R1`, `R2` and
+  `R3` appear in no docstring, no contract section and no page a reader opens,
+  and none of rotation, flips, padding, DCT, quantization or dithering shipped.
+  What is now accepted is the rule, that an exactness claim is declared per
+  regime with a condition the caller can evaluate before calling, with the four
+  measured regime axes in its body including the accumulator amendment from
+  ADR 0004. The vocabulary is deferred until the first transform that needs it.
+  The document also states plainly what its title had obscured: inexact
+  operations are not restricted, since `resize` and windowed `stitch` are
+  exactly what users come for, and what is forbidden is a docstring implying an
+  exactness the operation does not have.
+
+
 ## [0.5.3] - 2026-09-03
 
 ### Added
@@ -771,7 +895,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.3...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.4...HEAD
+[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
 [0.5.1]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.1

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

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

{patchcraft-0.5.3 → patchcraft-0.5.4}/CONTRIBUTING.md

@@ -136,7 +136,7 @@ PatchCraft/
 ├── README.pypi.md                  the PyPI page (long_description), links absolute
 ├── CONTRIBUTING.md                 this file
 ├── MAP.md                          one-page wayfinding: the tree, and a want-to/go-to table
-├── AGENTS.md                       the canonical rules; ten invariants, each earned
+├── AGENTS.md                       the canonical rules; eleven invariants, each earned
 ├── CLAUDE.md                       thin pointer to AGENTS.md plus tool-specific notes
 ├── STATUS.md                       the snapshot; what is in flight and what waits on whom
 ├── CHANGELOG.md                    Keep-a-Changelog format
@@ -200,7 +200,7 @@ PatchCraft/
 │   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
 │   ├── ROADMAP.md                  milestone plan
 │   ├── FOCO-1.0.md                 what 1.0 freezes and the blockers in the way
-│   ├── ADR/                        one file per decision that shaped the API
+│   ├── 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
@@ -255,6 +255,11 @@ 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.
+
 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

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

@@ -15,7 +15,7 @@ PatchCraft/
 │   README.pt-BR.md ........... the same page in Portuguese
 │   README.pypi.md ............ the PyPI page; links absolute, because relative ones break there
 ├── MAP.md .................... this file
-├── AGENTS.md ................. the rules, agent-agnostic and canonical; ten invariants
+├── AGENTS.md ................. the rules, agent-agnostic and canonical; eleven invariants
 ├── CLAUDE.md ................. thin; points at AGENTS.md and holds tool-specific notes
 ├── STATUS.md ................. the snapshot: where things are now, and who each item waits on
 ├── CHANGELOG.md .............. every release, each change with the measurement behind it
@@ -56,7 +56,7 @@ PatchCraft/
 │   ├── 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
-│   ├── ADR/ .................. one file per decision that shaped the API
+│   ├── 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
 │
@@ -84,7 +84,7 @@ PatchCraft/
 | 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) |
-| Understand **why the API looks like this** | [docs/ADR/](docs/ADR/) |
+| 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) |
 | **Release** it | [CONTRIBUTING.md](CONTRIBUTING.md), the "Releasing" section |

{patchcraft-0.5.3/src/patchcraft.egg-info → patchcraft-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.3
+Version: 0.5.4
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Author: Leonardo Marques de Souza
 License-Expression: MIT
@@ -170,7 +170,7 @@ 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 1571 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 1656 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.
 

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

@@ -146,7 +146,7 @@ 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.
 
-1571 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`.
+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`.
 
 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.
 

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

@@ -146,7 +146,7 @@ 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 1571 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 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`.
 
 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.
 

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

@@ -128,7 +128,7 @@ 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 1571 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 1656 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.
 

{patchcraft-0.5.3 → patchcraft-0.5.4}/SECURITY.md

@@ -35,12 +35,19 @@ out-of-bounds write rather than an exception, and it is the thing most worth
 reporting. `PATCHCRAFT_ACCEL=0` disables the native path entirely, and the
 universal wheel does not contain it at all.
 
-**`Cache` joins its `namespace` into a filesystem path.** The argument is
-validated only as a non-empty string, so `Cache(root, namespace="../elsewhere")`
-writes outside `root`. The namespace is chosen by the calling code, not read
-from data, so this is a trust boundary rather than a hole: **do not derive a
-cache namespace from untrusted input**. If you need per-user or per-request
-caches, hash or otherwise sanitise the value before passing it.
+**`Cache` uses the path you give it, and validates nothing beyond expanding
+`~`.** That is deliberate and it is what every established library does with a
+caller-supplied cache directory: `torch.hub.set_dir` calls `expanduser` and
+stops, pytest's cacheprovider does not validate, pip passes its `--cache-dir`
+through. A cache location is an argument the calling code chooses, not data
+read from an untrusted source, so `Cache(root, namespace="../elsewhere")` will
+write outside `root` and that is the caller's decision.
+
+The boundary, therefore: **do not derive a cache root or namespace from
+untrusted input.** If you need per-user or per-request caches, hash or
+otherwise sanitise the value in the layer that has the context to do it. This
+library is not the place for path policing, and adding it here would be
+inventing a security mechanism where the ecosystem has a settled convention.
 
 **Nothing in the shipped package opens a network connection.** The dataset
 helpers that download anything live in `tests/`, which is not part of the

patchcraft-0.5.4/STATUS.md

@@ -0,0 +1,97 @@
+# STATUS: 2026-09-04
+
+> 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);
+> the history is [CHANGELOG.md](CHANGELOG.md). This file does not repeat them.
+
+## Where the project is
+
+**0.5.4 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
+deselected, plus two full-sweep gates behind `PATCHCRAFT_SWEEP_FULL=1`
+that enumerate all 126,736 legal geometries. CI is green on
+{Ubuntu, Windows} x {3.12, 3.13, 3.14} on the pure path, plus a two-OS job that
+builds the Rust kernel and runs the whole suite through it.
+
+**The surface is 20 names**, pinned by `tests/test_public_api.py` with
+`inspect.signature`.
+
+## 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.
+
+## What is blocked, and on whom
+
+**ADR 0003 is accepted**, rescoped first. It ratifies one rule, that an
+exactness claim is declared per regime with a condition the caller can evaluate
+before calling, and it carries the accumulator amendment in its body: the
+predicate is a property of the geometry **and** the accumulator, since over 76
+legal geometries a `float32` accumulator is exact on 45, precisely the
+power-of-two ones, and a `float64` accumulator on all 76. The three-letter
+vocabulary its first draft proposed is deferred until a transform needs it.
+
+**ADR 0004 is `Proposed`, and asks nothing.** It records the precision and
+effort parameters as a design that is not built; the status reflects that none
+of it is implemented, not that a decision is pending. The one question it
+appeared to hold, whether to add the knobs before the 1.0 freeze or after,
+rested on the premise that adding one afterwards is expensive. It is not: each
+is a keyword-only argument with a default, so adding one is additive and is a
+minor release, and `reconstruct` has no positional-only parameters to make the
+order matter. Step A of its plan shipped in 0.5.2. **Waits on nobody.**
+
+**The `Cache` path question is closed, and it was not a decision.** It was
+posed as whether to reject a `namespace` containing `..`. The answer is no:
+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
+validation added. [SECURITY.md](SECURITY.md) and THEORY §9.5 now say the path
+is the caller's and that only `~` is expanded.
+
+## 1.0 blockers
+
+**All six are closed.** The last, B4, closed in 0.5.3 by making `docs/USAGE.md`
+executable rather than by regenerating it: every `>>>` on the page now runs in
+the suite, so it cannot go stale silently again.
+
+**And that leaves no decision before 1.0 either.** ADR 0003 is accepted and
+ADR 0004 asks nothing, so what stands between here and 1.0 is the project's own
+gate rather than an open question: an external consumer, which it does not have
+yet.
+
+| | |
+|---|---|
+| B1 predicate wrong in fifteen places | closed in 0.5.0 |
+| B2 the suite could not falsify B1 | closed in 0.5.0 |
+| B3 nothing pinned the public surface | closed in 0.5.0 |
+| B4 the two pages a stranger reads | closed in 0.5.3 |
+| B5 THEORY §9 contradicted itself on fp16 | closed in 0.5.2 |
+| B6 enumeration junk and asymmetric guards | closed in 0.5.0 |
+
+## What the project still declines to claim
+
+No external project has consumed the library, and that consumption is this
+project's own stated gate for calling the shape settled. No CUDA path has ever
+executed, in CI or outside it. Three of the five accelerated wheels, the two
+macOS ones and the aarch64 one, are built and have their contents checked, and
+their kernel has never run in CI.
+
+## Also outstanding, outside the 1.0 path
+
+**A DOI.** The Strata conformity review
+([docs/STUDIES/2026-09-03-strata-conformity.md](docs/STUDIES/2026-09-03-strata-conformity.md))
+found it to be the one item missing from the publishing pattern, and it is the
+kind that cannot be applied retroactively: Zenodo mints a DOI per release from
+the moment it is connected, and every release before that has none, permanently.
+One authorisation. **Waits on the owner.**

patchcraft-0.5.4/docs/ADR/0003-reversibility-classes.md

@@ -0,0 +1,139 @@
+# ADR 0003: declaring exactness per regime
+
+- **Status:** Accepted 2026-09-03
+- **Date:** 2026-08-04, rescoped and accepted 2026-09-03
+- **Deciders:** Leonardo Marques de Souza
+- **Relates to:** [ADR 0001](0001-patch-extraction-api.md), [ADR 0004](0004-precision-and-effort-parameters.md), [`THEORY.md`](../THEORY.md) §0, §9, [`STUDIES/2026-08-04-patch-techniques.md`](../STUDIES/2026-08-04-patch-techniques.md) §4, §5
+
+> **What this rescoping did.** The original draft decided two things at once: a
+> rule about *how exactness is declared*, and a vocabulary plus naming policy for
+> *six transforms that were being considered*. A month later the rule is
+> governing the code and the vocabulary has never been used: `R1`, `R2` and `R3`
+> appear in no docstring, in no contract section and on no page a reader opens,
+> and none of rotation, flips, padding, DCT, quantization or dithering shipped.
+> The rule is what was accepted. The vocabulary is deferred, and §4 says until
+> when. Freezing unused vocabulary into 1.0 would be inventing work where
+> nothing is broken.
+
+## 1. Context: "reversible" means three different things
+
+Several operations claim a reversal, and the word covers three unrelated cases.
+
+`rot90` and flips reverse **exactly**: the same tensor comes back, any dtype.
+Arbitrary-angle rotation reverses only **approximately**, because the forward and
+inverse interpolations each degrade the signal, and no parameter choice makes it
+exact. Quantization does not reverse at all: it is many-to-one by construction,
+and the useful contract is a measured error bound rather than an inverse.
+
+The library already ships operations of the second and third kind, and they are
+not accidents. `resize` from 64 to 32 and back differs from the original by
+0.619 on data in [0, 1], because two thirds of the pixels are gone; that is what
+resizing is. `stitch(weight="hann")` averages the pixels that overlap, so the
+sum survives and the parts do not; that is what seam blending is.
+
+**So the problem is not that inexact operations exist.** The problem is that
+nothing in the contract distinguishes them, and a caller cannot tell from a
+signature whether what comes back is the same tensor, a close one, or a
+different thing entirely.
+
+## 2. Decision: exactness is declared per regime, not per function
+
+Each transform declares, in its docstring and in its [`THEORY.md`](../THEORY.md)
+§9 contract section, the conditions under which its result is exact, and states
+the measured error where it is not.
+
+**The condition must be evaluable by the caller before the call.** A statement
+that a result is exact "in the usual case" is not a contract; a statement that
+it is exact when every value of the coverage map is a power of two is one,
+because the caller can compute that from the geometry alone.
+
+**One label per function is not writable for this library**, which is the whole
+reason for the rule. `stitch`'s behaviour is selected by its `weight` argument.
+`reconstruct`'s depends on the geometry, on the dtype, and, since ADR 0004
+measured it, on the accumulator. Any single label attached to those names would
+be false over part of their accepted input.
+
+### 2.1 The regime axes, as measured
+
+**Geometry.** The `extract`/`reconstruct` round trip is bit-exact when every
+value of the overlap coverage map is a power of two, and not otherwise. The
+reason is arithmetic rather than statistical: the fold sums `k` copies of a value
+and divides by `k`, which is exact in binary floating point exactly when `k` is a
+power of two. Every exact tiling qualifies, since all its counts are 1.
+
+**Accumulator.** ADR 0004 measured the sentence above to carry an unstated
+premise, which is the accumulator the library happens to use. Over 76 legal
+geometries on float32 input, a float32 accumulator is exact on 45, and those 45
+are precisely the power-of-two ones. A float64 accumulator is exact on all 76.
+The predicate is therefore a property of the geometry **and** the accumulator,
+and a regime row must say which accumulator it holds for.
+
+**Dtype, and it runs the opposite way to intuition.** In a geometry where
+float32 and float64 are inexact, `float16` and `bfloat16` are exact, because half
+precision is promoted to a float32 accumulator before the fold and a short
+mantissa times a small count still lands inside 24 bits. No per-function label
+can express an ordering in which the lower precision is the exact one.
+
+**Input values, and this is why the suite missed the error.** The round-trip
+tests built their images from `torch.arange`, and integer-valued data comes back
+exact in regimes where random data does not. Any test asserting exactness must
+use random full-mantissa data in the declared dtype, or it is a false-negative
+generator.
+
+## 3. The refutation this ADR exists to prevent from returning
+
+An earlier revision proposed `k_max <= 4` as the predicate. It is false, and the
+measurement is recorded here so that it cannot come back.
+
+It coincides with the correct predicate on square patches, where a count of 3
+cannot occur, and fails on rectangular ones, where it can. Swept over 14,969
+rectangular full-coverage geometries: `k_max <= 4` mispredicts 3,936 of them,
+26 percent, while the power-of-two predicate mispredicts 8. Those 8 fail in the
+safe direction: the power-of-two predicate has **zero false positives**, never
+promising exactness and then failing, and its 8 misses are geometries that happen
+to be exact without having been promised.
+
+**A contract may under-promise. It may not over-promise.** That sentence is the
+norm this ADR contributes, and the project has already used it once, to retract
+the wrong predicate in public.
+
+## 4. What is deferred, and until when
+
+The original draft also proposed a three-letter vocabulary (`R1` bit-exact, `R2`
+measured-approximate, `R3` irreversible), a naming rule reserving `inverse_*`,
+`un*` and `de*` for exact inverses, and a policy sending entirely-inexact
+features to auxiliary packages.
+
+None of it is wrong. All of it was written for six transforms that do not exist,
+and it has been used nowhere in a month. It is **deferred until the first
+transform that needs it**, which is the first operation offering an inverse that
+is not exact. At that point this ADR is amended or a successor is written, with
+the vocabulary applied to a real case rather than to six hypothetical ones.
+
+Until then the naming rule is worth keeping as a one-line habit rather than a
+frozen policy: **do not give an approximate inverse a name that promises an exact
+one**. `rotate_back`, never `derotate`.
+
+## 5. Consequences
+
+- **Nothing in the code changes.** No public name moves, no call that worked
+  stops working, no new exception is raised. What this ratifies is how the
+  contract is written.
+- **Inexact operations are not restricted.** `resize` and `stitch` with a window
+  are exactly the operations users come for. What is forbidden is shipping one
+  whose docstring implies an exactness it does not have.
+- **The 1.0 freeze gains a rule and not a vocabulary.** [`FOCO-1.0.md`](../FOCO-1.0.md)
+  makes accepting this ADR part of the freeze; what gets frozen is the
+  requirement that every exactness claim name its regime and be caller-evaluable.
+- **Tests mirror the regime, not the function.** An exactness claim is asserted
+  by a sweep over the regime's own condition, on random full-mantissa data.
+  `tests/test_exactness.py` is that, and it enumerates the space independently of
+  the predicate so it can falsify rather than confirm.
+- **Integers are outside this predicate.** For unmodified patches the integer sum
+  is exactly `k*v` and `k*v // k == v` for every `k`, so an integer regime needs
+  its own condition, which is that the accumulator does not overflow. ADR 0004
+  carries that.
+- **CPU verified only.** Every measurement here was taken on CPU, because no CUDA
+  path in this library has ever executed. The power-of-two boundary is argued
+  from IEEE arithmetic rather than from an accumulation order, so it should hold
+  anywhere, but the caveat stays until a CUDA sweep confirms it.