Skip to content

6.4: PNG and APNG decoder (clazel-png) - #194

Draft
atiernan wants to merge 8 commits into
phase6/6.2-deflatefrom
phase6/6.4-png
Draft

atiernan wants to merge 8 commits into
phase6/6.2-deflatefrom
phase6/6.4-png

Conversation

@atiernan

Copy link
Copy Markdown
Member

Phase 6 item 6.4: the new crate clazel-png. Its tier stays 0 (target 1); nothing is raised.

What is built

  • Chunks and CRC-32. Every chunk's CRC is checked, ancillary ones too, which is stricter than png.
  • IHDR with every allowed colour type and bit depth; others are refused.
  • PLTE and tRNS.
  • IDAT across any number of chunks, through clazel-deflate's streaming zlib.
  • The five filters and Adam7.
  • 1, 2 and 4-bit samples expanded; 16-bit samples truncated to the high byte, as png does.
  • gAMA, cHRM, iCCP, sRGB and cICP are read and ignored (listed).
  • APNG acTL, fcTL and fdAT, with each frame composited by its dispose and blend ops.
  • The listed choices are in src/lib.rs.
  • The work buffer holds a copy of the canvas, so a still PNG costs twice its pixels.

Tests (native)

Suite Result
PngSuite (2017-07-19 archive) against png 0.18.1 176/176: the 14 x* files are refused by both, and the other 162 match png's RGBA8 exactly
The same files fed in chunks of 1 to 4096 bytes, with and without empty chunks 176/176 equal to the whole-file decode
9,720 mutated files No panic, and the invariant holds. 611 accepted by both and equal; 0 accepted by ours alone; 498 accepted by png alone
Generated images, png encoder output, random APNGs 1,080/1,080, 60/60, 600/600
Hand-made streams 180 chunk-grammar cases, 25 APNG cases, 17 pixel checks of listed choices

png 0.18.1 has a bug: an interlaced APNG frame narrower than the canvas is written with the canvas's row width. The test adapter works round it. It isn't reported upstream.

Not done or not proven

  • Kani: only paeth_is_the_spec has passed.
    • unfilter_any failed its first run (an unwinding assertion). It was then shrunk to 8-byte rows with unwind 10, but not re-run.
    • Eight more harnesses are written but have never run: adam7_geometry, sample_and_rgba_any, crc_update_any, control_any, begin_frame_any, finish_row_any, feed_any and data_any. WSL crashed on every attempt to run them.
    • The step harnesses use a stand-in zlib engine bound by the Engine contract in src/engine.rs.
  • Miri: in one real run all 26 tests passed, but five took over 300 s: animations 323 s, encoder 309 s, chunking 850 s, differential 690 s, mutations 778 s.
    • Their strides have since been cut but not re-measured; the estimates are 60 to 200 s each.
    • Miri ran about 25,000× slower than native here, so native timing badly under-predicts it.
  • cargo xtask verify --changed: in WSL it can't work from a Windows-linked worktree; it fails at "select changed crates" (git merge-base: not a git repository).
    • Run natively on Windows instead, it covered every crate (xtask/ changed). Static checks, rustfmt, clippy, tests and every crate's conformance passed.
    • It ended in RESULT: INCOMPLETE, with Miri, Kani and Verus skipped. That isn't CHANGED CRATES PASSED.
  • CI: its full verification hasn't run.
  • Colour management, and looping and frame timing (6.19), are out of scope.

Also in the diff

  • Vendored PngSuite: the 2017-07-19 archive, because the 2011 archive the plan names no longer exists. The site has no HTTPS, so SOURCE.md records its SHA-256 and that the hash authenticates it.
  • xtask: a pngsuite converter (xtask/src/testdata/pngsuite.rs) and the PLACES row.
  • Dependencies: seven new test rows in docs/DEPENDENCIES.md: png, fdeflate, flate2, miniz_oxide 0.8.9, crc32fast, simd-adler32 and zlib-rs.
  • Status: the 6.4 status row in docs/phases/phase-6.md.

🤖 Generated with Claude Code

atiernan and others added 6 commits November 17, 2026 12:20
…er (item 6.4)

All 176 PNG files byte for byte, the archive's licence notice, and a SOURCE.md
carrying the archive's and each file's SHA-256. xtask testdata checks each
file against it and writes the table that embeds them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Chunks and CRC-32, IHDR with every colour type and depth, PLTE, tRNS, IDAT
across chunks through clazel-deflate's streaming zlib (behind an Engine trait,
so the proofs can stand in for it), the five filters, Adam7, 1/2/4-bit
expansion and 16-bit truncation as the png crate does, and acTL, fcTL and fdAT
with every frame composited by dispose and blend. The ancillary colour chunks
are read and ignored. Every choice the standard leaves open is listed in
lib.rs. The png crate and its dependencies get test rows in DEPENDENCIES.md;
clazel-png is placed in the status images.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
PngSuite exact against png 0.18.1 (the 14 x* files refused by both), chunking,
mutations, generated images of every colour type and depth (Adam7, filters,
tRNS, palettes), the png encoder's streams, 600 random animations composited
against the test's own reference, and hand-made streams for each chunk rule,
refusal and listed choice. The reference adapter works round a png 0.18.1
fault: an interlaced APNG frame narrower than the canvas is written with the
canvas's stride.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…allies (item 6.4)

Each suite runs a stated stride under Miri, sized by timing it natively with
the Miri branch forced on (0.04 s a test or less). The mutation suite now
counts what only ours and what only png accepts: 0 and 498 of 9,720.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e palette clamp (item 6.4)

Ten harnesses over the filters, Adam7 for every size up to 2^14, samples and
OVER, CRC, and the step's parts with a stand-in zlib engine. Only
paeth_is_the_spec has been run to a result (passes); the batch could not be
completed (WSL restarted repeatedly). The README says so. Miri strides cut
after a first run found five tests over 300 s.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nd changed-crate CI)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd changed-crate CI)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch is waiting to be deployed

1 waiting deployment
full-verification — e1eecb27 Waiting Nov 20, 2026 by atiernan via Approve the proofs #599
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant