[libphf]

Summary

Fixes the issues found in a full review of libphf: two container bugs (one of them a possible out-of-bounds read on 32-bit/WASM), silent acceptance of corrupted files, OpenMP data races, CLI/web robustness gaps, and documentation that didn't match the code. Adds a byte-level spec, a test suite, a reproducible benchmark and CI.

Bug fixes

#	Issue	Fix
1	The MED flag bit was never set: (2 << 1) instead of (1 << 1), so RGB files got flags 0x04	Flags are now 0x0E (RGB) / 0x0F (RGBA)
2	phf_size < 20 + payload_size wraps on 32-bit targets (WASM), letting the decoder read past the input buffer	Rewritten as a subtraction. phf_read_file also validates the untrusted header before sizing its allocation, and the PHF header must agree with the inner NHF3 packet
3	No integrity check: in fuzzing, ~15% of corrupted files decoded "successfully" into wrong pixels	Optional CRC-32 trailer (flag bit 3) verified before decoding. With it, 0 of ~20k corrupted inputs get through
4	Data races on shared error flags inside omp parallel for	Each thread writes only its own slot; results are checked after the loop
5	Web viewer didn't check _malloc results	Checks allocations, validates dimensions/channels, shows readable errors
6	CLI was Windows-only, crashed on grayscale input, silently corrupted 16-bit input, and info printed a hardcoded "100% Bit-Exact"	Loads the library on any OS (or from PHF_LIB), converts grayscale to RGB, rejects 16-bit input, info actually decodes and verifies the CRC, returns proper exit codes

Compatibility

• Files without the CRC flag (including all files written so far) still decode.
• Older decoders, including the currently deployed phf.wasm, read new files fine and just ignore the 4-byte trailer.
• Error codes are now named PHF_ERR_* constants in phf.h and no longer collide with internal NHF3 codes. -1…-6 keep their documented meaning (-5 truncated, -6 stride), and new codes were added (-7 corrupt, -8 checksum, -9 memory, -10 I/O). Callers that compared the old overlapping raw numbers should switch to the constants.

Documentation

• SPEC.md rewritten byte by byte: NHF3 packet header, real plane order (R−G, G, B−G, A), prediction border rules, canonical code tables, the RLE mode, CRC and size limits. To validate it, an independent Python decoder was written only from the spec text; it matches libphf byte for byte (synthetic RGB/RGBA/gray images and a crop of the sample photo).
• README / MANIFESTO no longer claim features the code doesn't have (Package-Merge, AVX2, ESP32, P-frames in the .phf container). Streaming latencies are recomputed from the measured throughputs (1080p at 290 MB/s ≈ 21 ms, not 8 ms). A note says the benchmark conditions weren't recorded and points to bench/bench.py.
• Stale code comments are fixed (fast-table width, table format, the ignored delta parameter).

Tooling

• CMakeLists.txt for every platform (shared/static, optional OpenMP, PHF_SANITIZE).
• tests/test_phf.c with 470 checks: round-trips across sizes and image types (stride 3/4/0), header/limit/error paths, the overflow case, CRC detection, a corruption fuzz, file I/O, and decoding sample.phf.
• bench/bench.py: PHF vs WebP Lossless vs PNG-6/PNG-1, with a bit-exact check on every decode. While building it we found that WebP Lossless is not bit-exact on RGBA by default: it drops the RGB of fully transparent pixels. The script reports that case separately.
• GitHub Actions CI: Linux (OpenMP, and ASan+UBSan), macOS, Windows/MSVC.
• build.bat finds MSVC through vswhere (no hardcoded VS path). The WASM build writes straight to apps/web/, and there is now a build_wasm.sh.
• Generated binaries are no longer tracked in libphf/. sample.phf was re-encoded with correct flags and a CRC, with identical pixels.

Test plan

• ctest passes in Release, Debug + ASan/UBSan, and with OpenMP (macOS arm64, clang): 470/470, zero warnings (including -std=c99 -pedantic)
• CLI round-trip on RGB / RGBA / grayscale PNGs is bit-exact; 16-bit input is rejected; info detects a flipped payload byte
• Independent spec-only decoder matches libphf
• phf-view.js passes node --check
• CI on Linux / Windows (first run on this PR)
• Rebuild apps/web/phf.wasm with libphf/build_wasm.sh (Emscripten wasn't available while preparing this PR). Until then, the deployed viewer keeps the old binary without the overflow fix or the CRC check
• Windows: libphf/build.bat (untested here)

🤖 Generated with Claude Code