patchcraft 0.5.2__tar.gz → 0.5.3__tar.gz

patchcraft-0.5.3/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+# Runs the gates CI runs, before the commit rather than after it.
+#
+# Deliberately absent: `ruff-format`. This project has never used it and
+# adopting it here would reformat 36 of 65 files in a commit that changed no
+# behaviour. `ruff check` is the gate; formatting is not.
+#
+# `mypy` runs through the project environment rather than through a pre-commit
+# virtualenv, because it needs torch to resolve any annotation in `src/` and
+# installing torch into an isolated hook environment would cost hundreds of
+# megabytes per hook update.
+#
+# Install: see the "Run tests" section of CONTRIBUTING.md. On a machine with a
+# global `core.hooksPath`, `pre-commit install` writes to `.git/hooks/`, which
+# git then ignores, and the hook is silently inert. CONTRIBUTING says how to
+# check.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=512"]
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ["--fix=no"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff-check
+        args: ["src", "tests", "tools"]
+        pass_filenames: false
+
+  - repo: local
+    hooks:
+      - id: mypy-strict
+        name: mypy --strict src
+        entry: mypy --strict src
+        language: system
+        types: [python]
+        pass_filenames: false

patchcraft-0.5.3/AGENTS.md

@@ -0,0 +1,137 @@
+# PatchCraft: the canonical guide
+
+> **Single source, agent-agnostic.** The branded files ([`CLAUDE.md`](CLAUDE.md))
+> point here and do not duplicate content. On any disagreement, this file wins.
+>
+> **Route**: this guide = *the rules* · [`MAP.md`](MAP.md) = *where things are* ·
+> [`CONTRIBUTING.md`](CONTRIBUTING.md) = *how to run the gates and release* ·
+> [`STATUS.md`](STATUS.md) = *where things stand now* ·
+> [`docs/FOCO-1.0.md`](docs/FOCO-1.0.md) = *what is left before 1.0*.
+> Do not repeat between them. Link.
+
+## 0. The invariants
+
+Each of these was earned. Where one names an incident, the incident is real and
+is in the changelog.
+
+### I1. Measure before you write it down
+
+Every number in this repository has a command that reproduces it. A sentence
+that says "faster", "exact" or "negligible" without one is a defect waiting to
+be found, and several have been.
+
+The failures this rule comes from: a predicate published as `k_max <= 4`,
+measured false and retracted in public; a benchmark that reported the
+byte-native path as nine times slower because `torch`'s `uint8.sum()` silently
+promotes to `int64`, so it measured the opposite of what it claimed; a security
+note asserting `Cache` runs `torch.load`, which it does not.
+
+Recalling is not measuring. Reading the code is not measuring either, when the
+question is numeric.
+
+### I2. `docs/THEORY.md` §9 is the arbiter
+
+It says so itself. When two documents disagree about what a function accepts,
+rejects or returns, §9 is the truth and the other document is the bug. When §9
+and the code disagree, decide which is wrong before changing either, and say
+which in the commit.
+
+§9 has been wrong twice. That is not a reason to trust it less; it is why the
+rule exists.
+
+### I3. A fix ships with a test that fails on the old code
+
+Without one it is not a fix, it is a coincidence. The suite already contains
+several tests whose only job is to prevent a specific defect from returning,
+and each names the measurement in its docstring.
+
+### I4. The exactness suite exists to falsify, not to confirm
+
+`tests/test_exactness.py` enumerates the legal geometry space independently of
+the predicate and hunts for both counterexamples: a case inside the rule that
+is not exact, and a case outside it that is exact by luck. If you change the
+predicate, the enumerator must not learn about the change.
+
+### I5. The public surface is 20 names, frozen by test
+
+`tests/test_public_api.py` pins the names, their signatures and the fields of
+the four data carriers. Adding a name is a decision recorded in an ADR, never a
+convenience taken mid-task. [`docs/FOCO-1.0.md`](docs/FOCO-1.0.md) says what
+1.0 freezes.
+
+### I6. Both code paths stay green
+
+The library has a pure-torch path and, on five of six wheels, a Rust one. They
+are bit-identical by test. Any change to the fold, the count map or the
+accelerator must run both: `pytest -m "not gpu"` with the extension built, and
+again with `PATCHCRAFT_ACCEL=0`.
+
+### I7. The version answers one question
+
+Not "did a returned value change", because a fix changes values by definition.
+The question is whether the **contract moved** (`0.Y.0`) or the
+**implementation stopped violating it** (`0.y.Z`). The rule and its four worked
+examples are in [`CONTRIBUTING.md`](CONTRIBUTING.md), and getting it wrong is
+what nearly shipped 0.5.2 as 0.6.0.
+
+### I8. Nothing ephemeral lives in the project folder
+
+Caches, build output and virtual environments are redirected by user-level
+environment variables. `accel/target` reached 269 MiB inside the tree before
+this was enforced. Never commit a machine path to fix it: that mistake is
+already in the history, as a `cache_dir = "Z:\caches\pytest"` that created a
+literal directory of that name on Linux.
+
+### I9. A tracked file ships to PyPI unless two files say otherwise
+
+`setuptools-scm`'s file finder offers every git-tracked file to the sdist, so
+`MANIFEST.in` is a blocklist over everything git knows about, and
+`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
+
+Check for an official or established solution before writing one. The
+accelerator's packaging, the versioning rule, the citation format and the
+outreach layout were all taken from prior art rather than designed here, and
+each is better for it. Writing something new is fine when nothing fits; writing
+it without looking is not.
+
+## 1. Writing
+
+Prose in this repository has no em-dashes. Replace the semantic role with a
+sentence that carries it, never with another symbol. Keep articles and
+connectives; one idea per paragraph. `README.md` is a call page, not a manual:
+the manual is [`docs/GUIDE.md`](docs/GUIDE.md), and complex examples belong
+there.
+
+Documents that state a version go stale. There is exactly one version string
+left in the documentation, the BibTeX entry in GUIDE section 9, plus
+[`CITATION.cff`](CITATION.cff). Do not add a third.
+
+## 2. Before you touch anything
+
+```
+uv sync --locked --extra cache --extra dev
+ruff check src tests tools
+mypy --strict src
+pytest -m "not gpu"
+```
+
+For a change to the fold, the predicate or the accelerator, add:
+
+```
+PATCHCRAFT_SWEEP_FULL=1 pytest tests/test_exactness.py
+cargo test --manifest-path accel/Cargo.toml
+```
+
+The same gates run as a pre-commit hook. On a machine with a global
+`core.hooksPath`, that hook is installed but inert;
+[`CONTRIBUTING.md`](CONTRIBUTING.md) says how to tell.
+
+## 3. What this project is not
+
+No batch axis, no dataset, no dataloader, no model, no padding to make an
+awkward geometry fit. Those are out by decision and the line is drawn in
+[`docs/SCOPE.md`](docs/SCOPE.md) and [`docs/THEORY.md`](docs/THEORY.md) §0.
+A request to add one of them is a scope conversation, not a feature.

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

@@ -6,6 +6,111 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-09-03
+
+### Added
+- `docs/STUDIES/2026-09-03-strata-conformity.md`, a review of this repository
+  against Strata v1.2.2. Its §9 bounded the review before it bounded the
+  project: name the genre and apply its standard, and take no change as the
+  default verdict unless a defect pays for the fix. The genre is a library, so
+  the standard is tests, packaging and CI. The finding is conformance, one gap
+  and one piece of debris. The gap is the absence of a DOI, which is the only
+  item missing from the publishing pattern and cannot be applied to releases
+  already out. The debris was a stale `.pytest_cache`, removed, with the
+  redirect verified to hold.
+
+
+
+- `STATUS.md`, the snapshot: what is released, what is unreleased, and who each
+  open item waits on. Writing it surfaced that `docs/FOCO-1.0.md` still listed
+  B1, B2, B3 and B6 as open although all four were closed in 0.5.0, the same
+  bookkeeping gap B5 had. Each is now recorded with what closed it, verified
+  rather than assumed: the retracted predicate survives only in the phase spec
+  and in the blocker's own text, the falsification suite enumerates 126,736
+  geometries, the surface is pinned with `inspect.signature`, and `tilings`
+  returns 73 specs with one whole-image entry and none labelled `overlap`.
+  B4 is the only blocker still open.
+- `AGENTS.md`, the canonical agent-facing guide, and a thin `CLAUDE.md` that
+  points at it rather than duplicating it. Its ten invariants are the ones this
+  repository actually enforces, and each names the incident it came from: the
+  predicate published and retracted, the benchmark that measured the opposite
+  of what it claimed because `uint8.sum()` promotes silently, the 269 MiB of
+  Rust build output that lived in the tree, and the machine path once committed
+  to `pyproject.toml` that created a literal `Z:\caches\pytest` directory on
+  Linux. `AGENTS.md` ships in the sdist; `CLAUDE.md` does not, having no reader
+  there.
+- Issue forms and a pull-request template. A report about this library is
+  irreproducible without the geometry, the dtype, the torch version and
+  `accel_available()`, so the forms make those required rather than suggested,
+  and every bug form asks whether the behaviour survives `PATCHCRAFT_ACCEL=0`,
+  which is the one answer that separates the native kernel from the library.
+  "Wrong numeric result" is a form of its own, because a wrong number is a
+  first-class defect here. The PR template asks whether a returned value moved
+  and offers the four answers the versioning rule distinguishes.
+- `SECURITY.md`. It names the real edges instead of being boilerplate: the
+  native kernel writes through raw pointers and trusts the geometry the Python
+  side validated, which is the sharpest thing in the library; `Cache` joins its
+  `namespace` straight into a path, so a namespace derived from untrusted input
+  escapes the root; nothing in the shipped package opens a network connection;
+  and image decoding happens in Pillow before this library sees anything. It
+  also says what is not a security issue here, because a wrong numeric result
+  belongs in a public issue with its measurement.
+- `CODE_OF_CONDUCT.md`, Contributor Covenant 2.1, taken verbatim from the
+  source repository rather than retyped.
+- `MAP.md`, one page of wayfinding: an annotated tree of the repository and a
+  want-to/go-to table. It follows the shape the sibling projects use, and it
+  opens by saying what the repository actually is, which is 20 public names
+  over eight modules plus the evidence that they behave as documented. Every
+  link and anchor in it is checked, and every path it names exists.
+- `.pre-commit-config.yaml`, running the gates CI runs. `ruff-format` is
+  deliberately absent: the project has never used it and adopting it would
+  reformat 36 of 65 files in a commit that changed no behaviour. Two things
+  surfaced while wiring it up. `docs/FOCO-1.0.md` had no trailing newline, now
+  fixed with the file's own CRLF rather than a bare LF, which is a mistake the
+  `mixed-line-ending` hook caught on the first attempt. And on a machine with a
+  global `core.hooksPath`, `pre-commit install` writes a hook git then ignores,
+  so it is inert without saying so; `CONTRIBUTING.md` gives the one command
+  that tells you which case you are in.
+- `CITATION.cff`, validated against Citation File Format 1.2.0, so GitHub shows
+  the "Cite this repository" button and the metadata has one authoritative
+  home. It ships in the sdist. The BibTeX entry in GUIDE section 9 stays,
+  because `cffconvert`'s generated form drops the version and emits a
+  placeholder key, but the `.cff` is now the source and the release checklist
+  moves both. A test pins its version against the newest released section of
+  this file, since comparing it to `patchcraft.__version__` cannot work in a
+  checkout, where setuptools-scm resolves a development version.
+
+### Changed
+- **`docs/USAGE.md` is executed instead of transcribed, which closes the last
+  1.0 blocker.** The page claimed eighteen public names when there were twenty
+  and had spent three releases describing an API that had moved, and the script
+  that once generated it was never tracked, so it could not be regenerated.
+  Making the page run in place is the durable fix: `tests/test_docs_usage.py`
+  collects it as a doctest, so a stale line fails CI rather than misleading a
+  reader. Only five outputs were genuinely wrong; the other eight failures were
+  formatting, where the output touched the closing fence and doctest read the
+  fence as expected text. `ELLIPSIS` and `NORMALIZE_WHITESPACE` are enabled in
+  `pyproject.toml` so the page may still elide a temp path or wrap a long repr
+  for the reader. The version literal is gone from it: the version comes from
+  the git tag, so any literal is wrong the moment it is written.
+
+### Fixed
+- **THEORY §9 justified promoting `bfloat16` with a fact that is false of it,
+  and §9 is the arbiter of the contract.** Both half formats were promoted to
+  a `float32` accumulator citing `float16`'s finite maximum of 65504. Only
+  `float16` overflows there: on the documented case its numerator reaches
+  `inf` in 144 of 256 pixels, while `bfloat16` carries `float32`'s exponent
+  and peaked at `9.0112e+04` against a finite maximum of `3.390e+38`. What the
+  promotion buys `bfloat16` is precision, since it has 8 mantissa bits to
+  `float16`'s 11, and on ordinary [0, 1] data it cut the maximum error from
+  `9.262e-03` to `1.935e-03`. §9.2 now carries one entry per format with the
+  measurement behind each, and the two docstrings and GUIDE section 4 say the
+  same. Two tests pin it.
+- Closed blocker B5 in `docs/FOCO-1.0.md`. The contradiction it named, §9.2
+  accepting the half-precision promotion in one list and excluding it as out
+  of scope eight lines below, had already been removed in 0.3.0 and never
+  recorded. Checking that is what surfaced the `bfloat16` error above.
+
 ## [0.5.2] - 2026-09-03
 
 ### Fixed
@@ -666,7 +771,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.2...HEAD
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.3...HEAD
+[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
 [0.5.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.0

patchcraft-0.5.3/CITATION.cff

@@ -0,0 +1,51 @@
+cff-version: 1.2.0
+title: "PatchCraft: image patch extraction, reconstruction, pairing and seam-aware stitching"
+message: "If you use this software, please cite it using these metadata."
+type: software
+authors:
+  - given-names: Leonardo
+    family-names: Marques de Souza
+    email: leonardo.marques.souza@gmail.com
+version: "0.5.3"
+date-released: "2026-09-03"
+repository-code: "https://github.com/LeoPR/PatchCraft"
+license: MIT
+abstract: >
+  PatchCraft cuts one image into patches and puts it back. One call takes one
+  (C, H, W) float tensor and returns one tensor: there is no batch axis, no
+  dataset, no dataloader and no model, and that boundary is documented as
+  binding rather than provisional. It owns the unfold and fold arithmetic, the
+  geometry validation and the seam blending, so a pipeline can own the rest.
+
+  Two silent defects motivate it. The intuitive reshape of F.unfold's output
+  gives the right shape with the wrong pixels, and a stride that does not cover
+  the image leaves pixels at zero without any error: on a 128 by 128 image with
+  patch 32 and stride 20, 3840 of 16384 pixels. Both are checked once here,
+  with tests around them.
+
+  The numeric contract is stated as a caller-evaluable predicate rather than a
+  promise. The extract and reconstruct round trip is bit-exact if and only if
+  every value of the overlap coverage map is a power of two, always true at
+  stride equal to patch size, and outside that rule the per-pixel error is
+  bounded by (k+1) times eps times the absolute value, with k the pixel's
+  coverage count. An earlier and weaker form of that claim was published, then
+  measured false and publicly retracted; a falsification suite now enumerates
+  the 126,736 legal geometries of the space independently of the predicate and
+  tries to break both halves of it.
+
+  Five of the six published wheels carry a Rust kernel for the overlapping
+  fold, compiled into the wheel itself rather than into a separate package, and
+  bit-identical to the pure-torch path by test. Every other platform installs a
+  universal wheel and runs the same operation in torch.
+
+  Pre-1.0: output values may change when the middle digit moves, and the
+  changelog records each change with the measurement behind it.
+keywords:
+  - image-processing
+  - patches
+  - super-resolution
+  - pytorch
+  - tiling
+  - reconstruction
+  - seam-blending
+  - numerical-reproducibility

patchcraft-0.5.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at leonardo.marques.souza@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

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

@@ -13,6 +13,30 @@ does not install them:
 uv sync --locked --extra cache --extra dev
 ```
 
+The same gates run before a commit if you install the hooks:
+
+```
+uvx pre-commit install
+uvx pre-commit run --all-files     # once, to see the tree is clean
+```
+
+**Check that the hook is actually live**, because on some machines it is not.
+`pre-commit install` writes `.git/hooks/pre-commit`, and git ignores that file
+entirely when a global `core.hooksPath` is set:
+
+```
+git config --get core.hooksPath        # empty means the hook will run
+```
+
+If it prints a path, the hooks in it run instead of yours, and `pre-commit`
+is silently inert here. Either make that global hook delegate, or set
+`core.hooksPath` for this clone alone, remembering that doing so also disables
+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
+behaviour.
+
 ```
 pytest
 pytest -m "not gpu"        # skip GPU-requiring tests
@@ -111,11 +135,22 @@ PatchCraft/
 ├── 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
+├── 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
 ├── LICENSE                         MIT
 ├── .python-version                 3.13
 ├── .gitignore                      ignores archive/, venvs, caches, outputs
-├── .github/workflows/
+├── .pre-commit-config.yaml         the CI gates, before the commit instead of after
+├── CITATION.cff                    citation metadata; GitHub reads it for the cite button
+├── 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
+│   ├── 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
 │   └── release.yml                 publishes to PyPI on vX.Y.Z tag push (Trusted Publishing)
 ├── src/patchcraft/                 library core, one-image-at-a-time primitives
@@ -159,7 +194,7 @@ PatchCraft/
 ├── docs/
 │   ├── GUIDE.md                    the manual, every README claim measured with its output
 │   ├── PERFORMANCE.md              what the accelerator is worth, and how to re-measure
-│   ├── USAGE.md                    REPL walkthrough of every public symbol (behind, see B4)
+│   ├── USAGE.md                    REPL walkthrough of every public symbol; run as a doctest
 │   ├── SCOPE.md                    responsibilities matrix + parallelization analysis
 │   ├── AUXILIARY.md                tests/_datasets, lab/, Z:\ conventions (NOT part of the wheel)
 │   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
@@ -306,7 +341,7 @@ silent: a version that walks backwards rather than an error.
 ## Releasing (maintainer only)
 
 1. Close the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) as `[X.Y.Z] YYYY-MM-DD`.
-2. Update the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9. It is the one version string left in the documentation, because a citation needs a concrete one.
+2. Update `version` and `date-released` in [`CITATION.cff`](CITATION.cff), and the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9. Those are the only version strings left in the repository, because a citation needs a concrete one. `uvx --from cffconvert cffconvert --validate` checks the file.
 3. Update [`docs/ROADMAP.md`](docs/ROADMAP.md) milestone checkboxes.
 4. Commit: `release: vX.Y.Z`.
 5. Tag + push: `git tag -a vX.Y.Z -m "..."` then `git push origin vX.Y.Z`.

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

@@ -17,10 +17,15 @@
 # `tools/check_dist.py` holds the matching allowlist and will fail the release
 # for anything unexpected, which is the reminder to come back here.
 
-include LICENSE
-include CHANGELOG.md CONTRIBUTING.md
+include LICENSE CITATION.cff SECURITY.md CODE_OF_CONDUCT.md
+include CHANGELOG.md CONTRIBUTING.md MAP.md AGENTS.md STATUS.md
+# CLAUDE.md is tool-specific and points at AGENTS.md; it has no reader in an
+# sdist. `exclude`, not `prune`: prune takes a directory and is a silent no-op
+# on a file, which is how this shipped once.
+exclude CLAUDE.md
 include README.md README.pt-BR.md README.pypi.md
 include pyproject.toml setup.py uv.lock .python-version
+include .pre-commit-config.yaml
 
 recursive-include src *.py
 include src/patchcraft/py.typed

patchcraft-0.5.3/MAP.md

@@ -0,0 +1,107 @@
+# MAP: finding your way around PatchCraft
+
+> One page. If you know **what** you want, this says **where** it is.
+> If you do not know yet, start at [README.md](README.md), which is the call page.
+
+PatchCraft cuts one image into patches and puts it back. The whole library is
+20 public names over eight modules; almost everything in this repository is the
+evidence that those 20 behave as documented.
+
+## The tree
+
+```
+PatchCraft/
+├── README.md ................. the call page, canonical, English
+│   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
+├── 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
+├── CODE_OF_CONDUCT.md ........ Contributor Covenant 2.1
+│
+├── src/patchcraft/ ........... THE LIBRARY. 20 public names, frozen by test
+│   ├── __init__.py ........... re-exports the surface and the generated version
+│   ├── extract.py ............ image -> patches; Patchify wraps it for a Compose
+│   ├── reconstruct.py ........ patches -> image, the exact inverse for untouched patches
+│   ├── stitch.py ............. patches -> image with a window, for patches a model rewrote
+│   ├── geometry.py ........... num_patches, tilings, scale_factor, paired_tilings; no pixels
+│   ├── pair.py ............... LR/HR pairing; PatchPair, PatchMeta
+│   ├── metrics.py ............ patch_metrics, per_patch_mse, per_patch_psnr
+│   ├── resize.py ............. PIL and torch backends
+│   ├── cache.py .............. content-addressed disk cache
+│   ├── _foldgeom.py .......... the coverage guard both reconstruct and stitch call
+│   └── _accel.py ............. bridge to the native kernel; falls back silently
+│
+├── accel/ .................... the Rust kernel, compiled INTO the wheel, not a second package
+│   └── src/kernel.rs ......... the gather-fold; cargo-tested without Python
+│
+├── tests/ .................... the contract, executable
+│   ├── test_exactness.py ..... enumerates 126,736 geometries and tries to FALSIFY the predicate
+│   ├── test_reference.py ..... a naive loop the fast paths must agree with
+│   ├── test_public_api.py .... freezes the 20 names, their signatures and carrier fields
+│   └── _rng.py ............... audited data generation; integer ramps hid a real defect once
+│
+├── docs/
+│   ├── GUIDE.md .............. THE MANUAL. every README claim, measured, with its output
+│   ├── THEORY.md ............. the math, and §9 is the arbiter of the per-function contract
+│   ├── SCOPE.md .............. the line between this library and your pipeline
+│   ├── PERFORMANCE.md ........ what the accelerator is worth; machine, versions, date, command
+│   ├── 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
+│   ├── 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
+│
+├── 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
+    ├── PULL_REQUEST_TEMPLATE.md
+    └── workflows/ ............ test.yml (both code paths) and release.yml (one project, six wheels)
+```
+
+## I want to... go here
+
+| I want to | Go to |
+|---|---|
+| **See what this is, in two minutes** | [README.md](README.md) |
+| **Work on it as an agent**, or learn what this repo insists on | [AGENTS.md](AGENTS.md) |
+| **Use it**: every argument, measured, with its printed output | [docs/GUIDE.md](docs/GUIDE.md) |
+| Know **when the round trip is exact**, as a rule I can evaluate myself | [docs/GUIDE.md §4](docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit), and [docs/ADR/0003](docs/ADR/0003-reversibility-classes.md) for the contract |
+| Know **what 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/) |
+| 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 |
+| Know **what changed and why** | [CHANGELOG.md](CHANGELOG.md) |
+| Know **what is left before 1.0** | [docs/FOCO-1.0.md](docs/FOCO-1.0.md) |
+| Know **where things stand right now** | [STATUS.md](STATUS.md) |
+| **Cite** it | [CITATION.cff](CITATION.cff) |
+| Report something **exploitable**, or read the trust boundaries | [SECURITY.md](SECURITY.md) |
+| **Report a bug** or propose a change | the issue forms, or [CONTRIBUTING.md](CONTRIBUTING.md) to send a PR |
+
+## Two things worth knowing before you read anything else
+
+**The contract is falsifiable, on purpose.** `tests/test_exactness.py` exists to
+break the library's own exactness claim, not to confirm it. That claim was
+published in a weaker form, measured false and retracted, and the suite is what
+came out of it. When a document and a test disagree, the test is right.
+
+**Where documents disagree with each other, [THEORY.md](docs/THEORY.md) §9
+wins.** It says so itself, and it is the section to fix first when something is
+found wrong.