patchcraft 0.5.3__tar.gz → 0.5.5__tar.gz

{patchcraft-0.5.3 → patchcraft-0.5.5}/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.5}/CHANGELOG.md

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

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

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

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

@@ -34,7 +34,7 @@ is silently inert here. Either make that global hook delegate, or set
 whatever else the global hooks were doing.
 
 `ruff-format` is deliberately not among the hooks. This project has never used
-it, and adopting it would reformat 36 of 65 files in a commit that changed no
+it, and adopting it would reformat 37 of 82 files in a commit that changed no
 behaviour.
 
 ```
@@ -130,13 +130,15 @@ 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
 ├── 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
@@ -148,7 +150,7 @@ PatchCraft/
 ├── SECURITY.md                     how to report, and what the real attack surface is
 ├── CODE_OF_CONDUCT.md              Contributor Covenant 2.1, verbatim
 ├── .github/
-│   ├── ISSUE_TEMPLATE/             five forms; the required fields are what makes a report reproducible
+│   ├── ISSUE_TEMPLATE/             four forms and a chooser; the required fields are what makes a report reproducible
 │   ├── PULL_REQUEST_TEMPLATE.md    asks whether a returned value moved, which decides the version bump
 │   └── workflows/
 │   ├── test.yml                    matrix CI on PRs/main, plus the accelerated job
@@ -185,6 +187,9 @@ PatchCraft/
 │   ├── test_accel.py               native path, skipped unless the extension was built
 │   ├── test_datasets_helper.py     label_subset
 │   ├── test_import.py
+│   ├── test_docs_usage.py          runs docs/USAGE.md as a doctest
+│   ├── test_citation.py            CITATION.cff agrees with the package
+│   ├── conftest.py                 shared fixtures
 │   ├── _rng.py                     audited round-trip helpers (data generation, bit equality)
 │   ├── test_rng.py                 tests for those helpers
 │   └── _datasets.py                dev-only fixtures (MNIST, etc), NOT public API
@@ -199,14 +204,15 @@ PatchCraft/
 │   ├── AUXILIARY.md                tests/_datasets, lab/, Z:\ conventions (NOT part of the wheel)
 │   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
 │   ├── ROADMAP.md                  milestone plan
-│   ├── FOCO-1.0.md                 what 1.0 freezes and the blockers in the way
-│   ├── ADR/                        one file per decision that shaped the API
+│   ├── FOCO-1.0.md                 what 1.0 freezes, and the six blockers, all closed
+│   ├── ADR/                        one file per decision; the choice only, evidence in STUDIES/
 │   ├── STUDIES/                    background reading behind those decisions
 │   └── design/                     one spec per work phase: the alternatives measured and the decision
 ├── outreach/                       material for presenting the project publicly, not shipped
 │   ├── README.md                   how it is organized and what to check before publishing
-│   ├── 2026-09-03-lancamento.md    the dated news source every channel text derives from
-│   └── linkedin/                   post (short) and artigo (long), each in PT and EN
+│   ├── 2026-09-04-lancamento.md    the current dated news source the channel texts derive from
+│   ├── 2026-09-03-lancamento.md    the previous one, kept as the record of 0.5.1
+│   └── linkedin/                   post, artigo, the illustrated page and the figures, PT and EN
 └── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
 ```
 
@@ -253,7 +259,7 @@ PEP 440's `~=0.5.0` means `>=0.5.0, <0.6.0`. In every one of them a `0.y` bump
 is the announcement that something may break, and a `0.y.z` bump is the
 promise that nothing does.
 
-That fixes what each digit is for here:
+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
@@ -284,6 +290,11 @@ under any rule keyed on whether values changed:
 - `0.5.0` made `tilings` return 73 specs where it returned 100. The
   enumeration's output set is the contract. A **y**.
 
+One consequence worth stating on its own, because a consumer cannot infer it
+from a `Literal`: **`WeightKind` is an open set.** Adding a member is additive
+and lands in a `0.y` before 1.0 and a minor after it; removing or renaming one
+is a break. Code that matches on it exhaustively should keep a fallback arm.
+
 After 1.0 the ordinary reading applies: breaking is major, additive is minor,
 fixed is patch. What 1.0 freezes is written in
 [`docs/FOCO-1.0.md`](docs/FOCO-1.0.md).
@@ -300,11 +311,6 @@ minting a y announced a break that never happened.
 `0.5.1` was briefly numbered `0.6.0` before release. It changes only how the
 package is built and shipped, so it is a z-bump.
 
-Two others were right and are worth recording as the shape to copy. `0.3.0`
-moved `stitch` output by ULPs through a different summation order, which is an
-output change and belongs at a y boundary. `0.5.0` made `tilings` return 73
-specs where it returned 100, which is squarely a break.
-
 The accelerator in [`accel/`](accel/) has no version of its own to manage. It
 is compiled into this wheel, so it ships when `patchcraft` ships. The version
 in `accel/Cargo.toml` is internal and nothing reads it; what the Python side

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

@@ -15,14 +15,14 @@ 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
 ├── CONTRIBUTING.md ........... layout, the two code paths, the versioning rule, releasing
 ├── CITATION.cff .............. citation metadata; GitHub reads it for the cite button
 ├── LICENSE ................... MIT
-├── SECURITY.md ............... how to report, and the three trust boundaries that matter
+├── SECURITY.md ............... how to report, and the five edges of the attack surface
 ├── CODE_OF_CONDUCT.md ........ Contributor Covenant 2.1
 │
 ├── src/patchcraft/ ........... THE LIBRARY. 20 public names, frozen by test
@@ -55,19 +55,21 @@ PatchCraft/
 │   ├── USAGE.md .............. the 20 symbols one at a time; every >>> runs in the suite
 │   ├── AUXILIARY.md .......... test fixtures, lab/, the off-tree conventions
 │   ├── ROADMAP.md ............ milestones, historical
-│   ├── FOCO-1.0.md ........... what 1.0 freezes, and the blockers still in the way
-│   ├── ADR/ .................. one file per decision that shaped the API
+│   ├── FOCO-1.0.md ........... what 1.0 freezes, and the six blockers, all closed
+│   ├── ADR/ .................. one file per decision; the choice, not the research
 │   ├── design/ ............... one spec per work phase: alternatives measured, then chosen
 │   └── STUDIES/ .............. background reading, and the Strata conformity review
 │
 ├── tools/
 │   ├── benchmark.py .......... accelerated vs pure, and proves they agree before timing
-│   └── check_dist.py ......... release gate: extension present, versions agree, tag respected
+│   ├── check_dist.py ......... release gate: extension present, versions agree, tag respected
+│   ├── compare_exactness_rules.py  the power-of-two rule against k_max <= 4, measured
+│   └── make_outreach_figures.py    every outreach figure and generated page, computed
 │
 ├── outreach/ ................. material for presenting the project; not shipped
 ├── lab/ ...................... scratch experiments; only the README is tracked
 └── .github/
-    ├── ISSUE_TEMPLATE/ ....... five forms, each asking for the geometry and PATCHCRAFT_ACCEL=0
+    ├── ISSUE_TEMPLATE/ ....... four forms, each asking for the geometry and PATCHCRAFT_ACCEL=0
     ├── PULL_REQUEST_TEMPLATE.md
     └── workflows/ ............ test.yml (both code paths) and release.yml (one project, six wheels)
 ```
@@ -83,8 +85,8 @@ PatchCraft/
 | Know **what each function accepts and rejects**, precisely | [docs/THEORY.md §9](docs/THEORY.md), which is the arbiter where documents disagree |
 | Know **whether this library is the right tool** | [docs/SCOPE.md](docs/SCOPE.md) |
 | Know **what the native accelerator is worth**, and re-measure it | [docs/PERFORMANCE.md](docs/PERFORMANCE.md), then `python tools/benchmark.py` |
-| Know **what the project refuses to claim** | [docs/GUIDE.md §8](docs/GUIDE.md#8-what-this-project-does-not-claim) |
-| Understand **why the API looks like this** | [docs/ADR/](docs/ADR/) |
+| 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) |
 | **Release** it | [CONTRIBUTING.md](CONTRIBUTING.md), the "Releasing" section |

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

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

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

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

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

@@ -8,7 +8,7 @@
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/patchcraft.svg)](https://pypi.org/project/patchcraft/)
 [![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/LeoPR/PatchCraft/blob/main/LICENSE)
 
-**Codifica uma imagem em patches e decodifica de volta.** O PatchCraft cuida da aritmética do `unfold` e do `fold`, da validação da geometria e da mistura nas emendas, para que o seu pipeline possa cuidar de todo o resto.
+**Recorta uma imagem em patches e monta de volta.** Uma imagem grande raramente entra inteira numa rede: ela é cortada em pedaços pequenos, os patches, cada um é processado sozinho, e a imagem é montada de volta. O PatchCraft cuida da aritmética do `unfold` e do `fold`, da validação da geometria e da mistura nas emendas, para que o seu pipeline possa cuidar de todo o resto.
 
 **Uma imagem por vez, de propósito.** Cada chamada recebe um tensor float `(C, H, W)` e devolve um tensor, porque a quantidade de patches depende da imagem, e uma API em lote teria que preencher com padding ou devolver uma lista. Quem fornece o lote é o seu `for`, o `torch.vmap` ou o `DataLoader`.
 
@@ -47,8 +47,8 @@ rodam os caminhos em torch puro, que devolvem os mesmos valores.
 
 O `patchcraft.accel_available()` informa em runtime qual dos dois você recebeu,
 e `PATCHCRAFT_ACCEL=0` no ambiente força o caminho puro. No fold com
-sobreposição ele vale entre 2.6x e 14x aqui, medido em
-[docs/PERFORMANCE.md](docs/PERFORMANCE.md).
+sobreposição o acelerador vale entre 5,8x e 16,5x na máquina em que foi
+medido, que o [docs/PERFORMANCE.md](docs/PERFORMANCE.md) relata por inteiro.
 
 O nome da distribuição e o nome de importação são os dois `patchcraft`. As dependências de execução são `torch>=2.6`, `numpy>=1.26` e `pillow>=10`. As versões de Python suportadas estão [no manual](docs/GUIDE.md#9-install-details-and-citation), junto com a observação que você precisa ler antes de instalar uma wheel de GPU.
 
@@ -108,7 +108,7 @@ assert not torch.equal(scrambled, patches)                   # e os pixels errad
 
 O segundo é um stride que não cobre a imagem. Numa imagem de 128 por 128 com `patch=32, stride=20`, a grade para no pixel 112, o que deixa 3840 dos 16384 pixels em zero, e um `fold` escrito à mão devolve essa imagem parcialmente preta sem reclamar.
 
-Escrever o laço de recortar e remontar à mão custa 17 linhas não vazias contra 3 aqui, e os dois resultados concordam em cerca de 1.2e-05 num valor em [0, 1], com as duas rotas diferindo só na ordem em que somam uma janela separável. [O manual](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) roda as duas versões lado a lado.
+Escrever o laço de recortar e remontar à mão custa 17 linhas não vazias contra 3 aqui, e os dois resultados concordam em cerca de 1,2e-05 num valor em [0, 1], mais de 300 vezes menos que um degrau de 8 bits, com as duas rotas diferindo só na ordem em que somam uma janela separável. [O manual](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) roda as duas versões lado a lado.
 
 ## A geometria precisa cobrir a imagem
 
@@ -146,9 +146,9 @@ O round-trip é exato quando todo valor do mapa de cobertura é potência de doi
 
 **Pré-1.0**, e o badge acima mostra a versão atual. Enquanto o primeiro dígito for zero, quem marca a fronteira de compatibilidade é o do meio: um `0.y.z` novo é seguro de pegar, e é num `0.y` novo que um valor de saída ou uma assinatura pode mudar. O [CHANGELOG.md](CHANGELOG.md) registra cada uma dessas mudanças com a medição por trás dela.
 
-São 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 1657 testes coletados, com CI verde em {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14}, e com `ruff check` e `mypy --strict` na mesma execução. O pacote é tipado e distribui o `py.typed`.
 
-Nenhum projeto externo consumiu a biblioteca ainda, e nenhum caminho CUDA dela jamais executou. [O manual](docs/GUIDE.md#8-what-this-project-does-not-claim) lista o que mais este projeto se recusa a afirmar.
+Em GPU as funções preservam o dispositivo que você passa, e o kernel Rust é só de CPU, então não acelera ali; todo número desta página é de CPU. Nenhum projeto externo consome a biblioteca ainda, que é o critério para dizer a API assentada. [O manual](docs/GUIDE.md#8-where-this-applies-today) diz onde o resto se aplica.
 
 ## Onde ler em seguida