feat(png): measure the encoder end to end, then move what it exposed

AGENTS.md

@@ -70,7 +70,10 @@ Dependency edges (a crate depends on those to its right):
   hostile input, ancillary metadata surfaced as raw `MetadataBlock`-ready payloads
   (eXIf/iCCP/XMP/text) plus parsed gAMA/cHRM/sRGB/cICP. APNG out of scope (decodes as the
   default image). Differential oracle both directions: libpng, which also *generates* the
-  decoder's conformance fixtures. ← core, deflate (+ `miniz_oxide` for inflate).
+  decoder's conformance fixtures. ← core, deflate (+ `miniz_oxide` for inflate, and
+  **maintainer-approved `crc32fast`** for the chunk CRC that every encode pays on its critical
+  path — hardware CRC-32 on x86-64/aarch64, table fallback elsewhere including wasm32, and it
+  keeps its `unsafe` to itself, so gamut-png stays `#![deny(unsafe_code)]`).
 - **gamut-ifd** — TIFF/IFD container core (byte order, field types, IFD read/write); a
   low-level container primitive (sibling to bitstream), shared by `gamut-tiff` and EXIF
   metadata. ← core. Optional `bigtiff` feature adds 64-bit BigTIFF. Per-format metadata

README.md

@@ -214,6 +214,8 @@ cargo test --workspace
 | `mise run lint-fix`  | Lint and auto-fix                        |
 | `mise run check-commits` | Check commits are Conventional Commits |
 | `mise run coverage`  | Run tests with coverage (min 80%)        |
+| `mise run bench`     | Run performance benchmarks (Divan; see [docs/benchmarking.md](docs/benchmarking.md)) |
+| `mise run bench-test` | Run every bench once to prove it still executes (no timings) |
 | `mise run check-cross <triple>` | Cross-compile-check the libs for a target (extended CI; master/manual) |
 | `mise run check-msrv` | Check the libs compile on the documented MSRV (extended CI; master/manual) |
 | `mise run versions`  | List every crate's version               |

crates/gamut-cli/src/main.rs

@@ -62,7 +62,7 @@ struct Cli {
 enum Command {
     /// Decode an image (PNG/JPEG/PPM/WebP/JXL) and re-encode it as AVIF/WebP/TIFF/PNG/JXL/JPEG.
     Convert(commands::convert::ConvertArgs),
-    /// Strictly deconstruct a TIFF or DNG: account every byte and flag unknowns (gamut-tiff/gamut-dng).
+    /// Strictly deconstruct a TIFF, DNG or PNG: account every byte, flag unknowns, and for PNG report where the bytes went (gamut-tiff/gamut-dng/gamut-png).
     Inspect(commands::inspect::InspectArgs),
     /// Extract and inspect the embedded ICC colour profile of an image (gamut-icc).
     Icc(commands::icc::IccArgs),

crates/gamut-png/Cargo.toml

@@ -15,6 +15,14 @@ categories.workspace = true
 [lints]
 workspace = true
 
+[features]
+# Re-exports the encoder's pipeline stages (`src/stages.rs`) so `benches/encode.rs` -- an external
+# crate, which can only see `pub` -- can time them one at a time (issue #224). Additive,
+# `doc(hidden)`, no SemVer guarantee, and never enabled by the `gamut` umbrella, so the shipped
+# surface and `mise run check-ffi-features` are unaffected. The module is re-exports only, so it
+# adds no coverage regions and no mutants.
+test-support = []
+
 [dependencies]
 gamut-core.workspace = true
 # The shared codestream-backend seam (issue #272): the `repr(C)` vtable + fallback contract the
@@ -26,10 +34,24 @@ gamut-deflate.workspace = true
 # is deliberately encoder-only, and its docs bless miniz_oxide as the decode-side inflate (the same
 # choice gamut-dng made); revisiting an in-house inflater is tracked by issue #196.
 miniz_oxide = "0.8"
+# CRC-32 (ISO-HDLC) for every chunk, IDAT included, so it is on the critical path of every encode.
+# Hardware-accelerated (x86-64 PCLMULQDQ/AVX-512, aarch64 `crc32`) with a table fallback elsewhere,
+# including wasm32. MIT/Apache-2.0, pure Rust, and it keeps its `unsafe` to itself -- gamut-png
+# stays 100% safe Rust. Replaces a hand-written byte-at-a-time table loop; see `src/crc32.rs`.
+crc32fast = "1.5"
 
 [dev-dependencies]
 # Differential cross-check oracle: a vendored, statically-linked libpng (built from the
 # `third_party/libpng` submodule). Dev-only and excluded from the workspace. libpng proves both
 # directions: it decodes the gamut encoder's output, and it generates the fixture corpus (and the
 # reference pixels) the gamut decoder is differentially checked against.
 libpng-oracle = { path = "../../tooling/libpng-oracle" }
+# Benchmark harness (issue #149) plus this crate's own `test-support` feature, which the bench
+# target needs to reach the pipeline stages. A self dev-dependency is the standard way to enable an
+# own feature for tests and benches only; `mise run check-release-deps` skips self-edges.
+divan.workspace = true
+gamut-png = { path = ".", features = ["test-support"] }
+
+[[bench]]
+name = "encode"
+harness = false

crates/gamut-png/README.md

@@ -59,7 +59,12 @@ A differential oracle (`tooling/libpng-oracle`, a vendored static libpng) proves
 libpng decodes the encoder's output pixel-exact, and a libpng *reference encoder* generates the
 decoder's conformance fixtures (interlaced, sub-byte, forced-filter, metadata-laden) which both
 decoders must read identically — no vendored image corpus. A hand-crafted malformed-input corpus
-pins the rejection policy, and output size is benchmarked against libpng at maximum compression.
+pins the rejection policy. Output size is measured against libpng at zlib level 9 by
+`cargo bench -p gamut-png`, and **enforced** by `tests/size_contract.rs`, whose per-case budgets
+each carry a written justification — a regression in the crate's reason to exist fails the build.
+`STATUS.md` records the measured table; gamut is smaller than libpng-9 on every corpus entry, by
+28-85% wherever a reduction or a filter choice applies and by 0.2% on the incompressible noise row,
+where there is nothing for either encoder to find.
 
 ## License