Skip to content

lumen-image: an inflate (zlib) decoder (#195) - #272

Draft
flyingrobots wants to merge 2 commits into
mainfrom
feat/lumen-image-inflate
Draft

flyingrobots wants to merge 2 commits into
mainfrom
feat/lumen-image-inflate

Conversation

@flyingrobots

Copy link
Copy Markdown
Owner

Closes #195

Work in progress: the lumen-image crate with a zlib (RFC 1950/1951) decoder. The description will hold the acceptance evidence and test plan before this leaves draft.

Opens the work on the zlib decoder of ADR 0012; the entry is refined as the
code lands.

Issue: #195
Agent-Session: 7659171b-5ea2-4675-adcf-cb84ac79c847
Agent-Tool: Claude Code
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

…built)

Checkpoint at the maintainer's pause. The crate is not yet a workspace
member nor a dependency of lumen, so nothing compiles it; no test or gate
has run on it.

Issue: #195
Agent-Session: 7659171b-5ea2-4675-adcf-cb84ac79c847
Agent-Tool: Claude Code
@flyingrobots

Copy link
Copy Markdown
Owner Author

Handoff (paused)

Done (commit 24511df, pushed):

  • A changelog entry under Unreleased/Added.
  • The lumen-image crate source: Cargo.toml (it inherits the workspace lints and has no dependencies), and lib.rs with #![deny(clippy::float_arithmetic)]. In src/inflate* there are the zlib framing, the bit reader over several chunks, canonical Huffman decoding, stored, fixed and dynamic blocks, output that honours the caller's limit and the declared window, Adler-32 and typed errors that carry offsets. There is also INFLATE_ID = "lumen-zlib-inflate/1". The public API is inflate_zlib(&[u8], OutputLimit) and inflate_zlib_chunks(&[&[u8]], OutputLimit); the second is meant for PNG IDAT chunks.
  • Rules stated in inflate.rs: a preset dictionary is refused by name. A distance is checked against the output so far and against the window that CINFO declares. An incomplete code is refused, except two cases: an alphabet with exactly one symbol of length 1 (literal/length or distance), and a distance alphabet with no codes. The code-length code must be complete. Bytes after the trailer are an error.
  • The corpus is in crates/lumen-image/tests/corpus/. It was built by make_corpus.py, run with python3 -I and CPython 3.9.6 zlib. Every stream was checked with zlib.decompress. The SHA-256 values and block types (read back by an independent walker) are in corpus.table. hand_streams.py packs the two hand-assembled streams.
  • tests/hand.rs and tests/writer/mod.rs hold the hand-assembled fixed and dynamic streams and one test per error kind, with tests exactly on each limit and one step past it.

Not done, and none of it compiled yet:

  1. The crate has not been added to the workspace members, and lumen does not yet declare lumen-image = { path = "../lumen-image" }.
  2. cargo test, clippy and fmt have never run. Expect clippy and compile fixes; tests/hand.rs also has a leftover unused literals[0] = 0 line.
  3. Not yet written: tests/corpus.rs (each case decodes to its .raw, split at chunk boundaries, capacity at most the limit, the limit exactly and one byte less), tests/robustness.rs (every truncation gives Truncated at the prefix length, every single-bit flip in the first N bytes, every header-byte replacement), and unit tests in src/inflate/tests.rs (published Adler-32 vectors and the RFC 1951 §3.2.2 ABCDEFGH example). inflate.rs declares mod tests, so that file must exist before the crate compiles.
  4. A README for the corpus with the hash table, written from corpus.table.
  5. Documentation: a row in the CONTRIBUTING table ("two targets in one crate" is now stale), the core description in docs/explanation.md and the R-NDET-1 row, and a dated Clarification in ADR 0012. Its Consequences section says the crate is not a lumen dependency until something uses it, which the issue overrides.
  6. The full gate in the container, then the PR description with evidence.

Open question for the coordinator: acceptance item 2 says every single-byte corruption of the header is refused. Some corruptions still leave a valid header, for example 78 9c changed to 78 01, which only changes FLEVEL. Such a stream decodes correctly, because the header is outside the Adler-32. The planned test asserts "typed error, or a decode equal to the original".

Uncommitted: nothing.

Next commands: add the member and the dependency, write the missing test files, then run
python3 ~/git/devcontainers/bin/devrun lumen ~/git/lumen-195 --worktree --fetch --cpus 4 --memory 8g --timeout 2400 -- cargo test --locked -p lumen-image, followed by the full gate in CONTRIBUTING.md.

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.

lumen-image: an inflate (zlib) decoder

1 participant