feat(lzw): LZWDecode + FlateDecode predictor refactor (PR #04, stacked on #6)

[rjzondervan]

Summary

Implements PDF 1.7 §7.4.4 LZWDecode — the fourth and final filter PR in the codec series. With this PR the chain dispatcher supports all five standard filters: FlateDecode (pre-existing) + ASCIIHexDecode + RunLengthDecode + ASCII85Decode + LZWDecode.

Stacked on #6 feat/ascii85-decode.

What landed

Refactor: PNG predictor extracted from FlateDecode

FlateDecode is now a one-line wrapper around the new applyPngPredictor helper. Behaviour is byte-for-byte identical for every existing caller (the PoC verify gate is the regression check). LZWDecode calls applyPngPredictor directly after its own decompression step. Done first so the LZW decoder doesn't duplicate the row-filter loop (D4).

LZW state machines

Helper (on PDFObject, protected static)	Purpose
LZWDecode($_stream, $params): string|false	Variable-width MSB-first decode (9-12 bits); clear (256), EOD (257), KwKwK special case; EarlyChange parameter; PNG predictor invocation
LZWEncode($_stream, $params): string	Variable-width encoder; leading CLEAR (Acrobat-compatible); 4096-entry dict overflow → emit CLEAR + reset
lzw_read_code($stream, &$bitPos, $codeWidth): int|null	MSB-first variable-width bit-stream reader
lzw_write_code(&$out, &$pending, &$pendingBits, $code, $codeWidth): void	Companion writer using a 32-bit pending register

Both wired into apply_filter_chain_decode / apply_filter_chain_encode via case 'LZWDecode':.

Spec contract

Pinned by openspec/changes/feat-lzw-decode/:

• REQ-1 — Decode per PDF 1.7 §7.4.4 (clear, EOD, KwKwK)
• REQ-2 — Honour the EarlyChange parameter (default 1; explicit 0)
• REQ-3 — Lossless round-trip on arbitrary binary input (2048 bytes default + EarlyChange=0)
• REQ-4 — Support the PNG predictor scheme via shared applyPngPredictor
• REQ-5 — Fail safely on dictionary overflow + chain integration (MODIFIED capability from feat(filter-chain): array-form /Filter dispatch in PDFObject (PR #05 — foundation) #3)

Implementation note worth surfacing in upstream review

Classical LZW has a one-entry off-by-one between encoder and decoder dictionary state: the decoder's first post-CLEAR read doesn't add an entry (because prev is null), so the decoder's nextCode lags by exactly one. To keep both sides synchronised on bit-width transitions, the decoder's threshold check uses ($nextCode + 1) >= $threshold instead of $nextCode >= $threshold. Without this compensation, the encoder advances to 10-bit codes one iteration before the decoder, and the round-trip fails on inputs > ~250 bytes. Surfaced during implementation by the 2048-byte round-trip test failing.

Test plan

• php examples/poc-filter-roundtrip-lzw.php — 5 REQs, 0 assertion failures
• All 5 prior gates still green after FlateDecode refactor (PoC, dispatcher, ASCIIHex, RunLength, ASCII85)
• php -l clean on touched files
• No new composer dependencies; PHP 7.4 compat preserved

Files changed (675 +, 64 −)

• src/PDFObject.php — LZWDecode + LZWEncode + bit-stream helpers + FlateDecode predictor extraction
• examples/poc-filter-roundtrip-lzw.php — new round-trip gate
• docs/upstream-prs/04-lzw-decode/{proposal,design,tasks}.md — implementation notes
• openspec/changes/feat-lzw-decode/tasks.md — 35/35 complete

Dependencies + ordering

• Depends on: feat(filter-chain): array-form /Filter dispatch in PDFObject (PR #05 — foundation) #3 (filter-chain-dispatch)
• Stacked on: feat(ascii85): ASCII85Decode encode + decode + chain wiring (PR #03, stacked on #5) #6 (ASCII85Decode — for clean linear history; orthogonal in code terms)
• Completes: the four-filter codec series. Next up in the text-replacement roadmap: feat(ascii85): ASCII85Decode encode + decode + chain wiring (PR #03, stacked on #5) #6 ToUnicode CMap resolution (the largest single piece).

Out of scope

• TIFF differencing predictor (Predictor=2/3 — applyPngPredictor rejects these with p_error; can be added if a real-world fixture demands it)
• Streaming / incremental decode (operates on full buffers per upstream convention)
• Optimal LZW dict pruning strategies on overflow (greedy CLEAR-and-reset)

[WilcoLouwerse]

Strict-mode review (REQUEST_CHANGES)

LZWDecode + FlateDecode predictor refactor with a working bit-stream codec, round-trip PoC, and chain wiring; the predictor refactor is mostly verbatim and parity-preserving, but several real defects exist: the LZWDecode error sentinel does not match the dispatcher's check, a documented predictor-failure branch is dead code due to a return-type contract drift, and EarlyChange wording vs implementation inconsistency.

Findings: 🔴 2 blockers · 🟡 6 concerns · 🟢 8 minors. All findings have been posted as inline comments above. Per Strict-mode rules, any 🟡 or 🔴 holds the verdict; address each thread before requesting re-review.

🔴 Blockers

• src/PDFObject.php:360 — LZWDecode error path returns encoded bytes, not false — chain dispatcher's === false check never fires
• src/PDFObject.php:420 — applyPngPredictor returns false on parameter rejection but its docblock + caller assume null — early-return branch in LZWDecode is dead

(Inline comments include **Impact:** and **Suggested fix:** sections per Strict-mode body template.)

[WilcoLouwerse]

✅ APPROVE — Strict re-review against a218023.

All 2 🔴 Blockers and 6 🟡 Concerns from the first-pass review resolved or acceptably deferred. Both blocker fixes verified at HEAD with the dispatcher's === false contract now honoured across all four LZW failure paths; applyPngPredictor docblock and propagation path corrected.

Verified locally on a fresh clone at a218023 — all 6 PoC gates pass:

• poc-filter-roundtrip-lzw (this PR — REQ-1..REQ-5 incl. new truncated / out-of-range / predictor-rejection / chain-failure tests)
• poc-replace-text, poc-filter-chain-roundtrip, poc-filter-roundtrip-{asciihex,runlength,ascii85} — confirms the FlateDecode → applyPngPredictor refactor is behaviour-preserving for every existing caller.

Resolutions (each verified at HEAD; reply posted on each thread before resolving):

Prior	Status	Where
🔴 #1 Dispatcher dead-code	✅	All 4 paths return false at PDFObject.php:381 / 400 / 412 / 419
🔴 #2 Return-type contract drift	✅	docblock + === false check at :158-165, :454
🟡 #3 EarlyChange / decoder-lag framing	✅	orthogonal-concerns block at :422-441
🟡 #4 Carried-over Flate limits	✅	enumerated in applyPngPredictor docblock
🟡 #5 PNG Sub-filter bug	✅	chr(ord+ord)%256 wrapping at :222-232 + new Sub-filter PoC test
🟡 #6 Docblock contradicts impl	✅	same fix as #2
🟡 #7 Asymmetric encode path	⚠️ deferred	Pre-existing FlateDecode/encoder concern (I originally noted "Pre-existing in FlateDecode too"). Acknowledged in commit body but not yet persisted to issue.md "Out of scope" — flagged as follow-up
🟡 #8 Triplicate Implementation Note	✅	all 3 docs files reduced to 1-line canonical-pointers
🟢 dealfonso#11 buildObj cosmetic redundancy	✅	chain-failure test now uses $rawStream parameter
🟢 dealfonso#12 Predictor coverage narrow	✅	new Sub-filter test at poc:154-175
🟢 dealfonso#13 REQ-5 conflates concerns	✅	spec.md REQ-005 + 4 new PoC scenarios
🟢 #9 / #10 / dealfonso#14 / dealfonso#15 / dealfonso#16	acknowledged	author's call — not blocking

Excellent fix-commit hygiene: structured by severity, code references in the commit body, all six PoC gates kept green. Ready to merge into feat/ascii85-decode.