fix(cctx): refines compression context sticky option behavior

[hellobertrand]

Reusable compression contexts (zxc_cctx) mishandled their sticky options: a zero level or block_size in a non-NULL opts reused the last call's value instead of a default, and a call that failed (e.g. ZXC_ERROR_DST_TOO_SMALL) still updated the remembered options. Fixing both exposed related defects in the block API.

Option resolution

• opts == NULL reuses the options of the last successful call, starting from the creation options. A failed call leaves them untouched.
• In a non-NULL opts, a zero level or block_size means the value the context was created with: the library defaults for zxc_create_cctx(NULL), otherwise what zxc_create_cctx or zxc_init_static_cctx received. It never depends on earlier calls. Static contexts therefore keep their pinned level and block size with no special case.
• checksum_enabled and seekable are taken as given (0 = off), as in zxc_compress().

Block API

• block_size is validated as requested: an invalid value returns ZXC_ERROR_BAD_BLOCK_SIZE whatever the source size, instead of being accepted and remembered (which then broke every frame call with NULL options).
• The remembered block_size is the requested one, not the carve grown to hold the source.
• The workspace is re-carved only when too small for the block; a larger carve encodes a block byte-for-byte identically, so alternating block sizes no longer reallocate on every call.

Behaviour changes

• A zero level / block_size no longer reuses the previous call's value.
• zxc_compress_block() now rejects a block_size that is not a power of two in range; main accepted some such values.
• Static workspace sizes are unchanged.

Fixes #532

Summary by CodeRabbit

• New Features
  • Reusable compression contexts retain settings from the last successful call when options are omitted. Zero-valued compression level or block size uses the context’s creation-time setting.
• Bug Fixes
  • Invalid block sizes are more clearly identified, and failed compression calls leave retained settings unchanged.
  • Heap-based contexts can reuse workspace after a larger block operation; static contexts continue to reject changes requiring more workspace.
• Documentation
  • Updated API and examples to explain option persistence, fallback behavior, and workspace handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: f4b5bcdf-fa58-4e75-927c-05489f990dd1

📥 Commits

Reviewing files that changed from the base of the PR and between 32db796 and 82417a2.

📒 Files selected for processing: 9

• README.md
• docs/API.md
• docs/EXAMPLES.md
• include/zxc_buffer.h
• src/lib/zxc_dispatch.c
• tests/test_common.h
• tests/test_context_api.c
• tests/test_main.c
• tests/test_static_ctx.c

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

📝 Walkthrough

Reusable compression contexts now resolve zero-valued level and block_size from creation settings. Calls with NULL options reuse settings from the last successful call. Frame and block compression update sticky settings only after success.

Changes: Reusable compression context options

Layer / File(s)	Summary
Option resolution and context initialization src/lib/zxc_dispatch.c, include/zxc_buffer.h, docs/API.md, README.md, docs/EXAMPLES.md	Contexts now store creation-time base options and sticky options. Zero level or block_size uses the creation value. Documentation describes these rules and NULL-option reuse.
Frame compression option handling src/lib/zxc_dispatch.c, tests/test_common.h, tests/test_context_api.c, tests/test_main.c, docs/API.md	Frame compression resolves options before processing and updates sticky options only after a positive result. Tests compare frame and block outputs after successful and failed calls, and check zero-valued options and creation-value fallbacks.
Block compression and static-context behavior src/lib/zxc_dispatch.c, include/zxc_buffer.h, tests/test_static_ctx.c	Block compression resolves options and adjusts workspace size to fit the source. Heap contexts can reuse a larger carve for smaller blocks. Static-context tests check that zero-valued options use pinned initialization values.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 82417

No issue requiring a change before merge was established; normal checks remain appropriate.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: refining sticky option behavior for reusable compression contexts.
Linked Issues check		Issue #532 requires creation-value defaults for zero level and block_size in non-NULL options, sticky reuse only for NULL options, and unchanged sticky settings after failed calls. The implementation …
Out of Scope Changes check		The block API fixes, documentation updates, implementation refactoring, and regression tests support the sticky option requirements in #532 or the current PR scope. The changes validate requested bloc…
Docstring Coverage		Docstring coverage is 82.35% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 6 files. (3 skipped: 3 …

Full details: Linked Issues check

Explanation

Issue #532 requires creation-value defaults for zero level and block_size in non-NULL options, sticky reuse only for NULL options, and unchanged sticky settings after failed calls. The implementation resolves these cases for frame and block compression, and updates sticky settings only after success. Tests cover successful calls, failed calls, NULL reuse, creation values, and invalid block sizes.

Full details: Out of Scope Changes check

Explanation

The block API fixes, documentation updates, implementation refactoring, and regression tests support the sticky option requirements in #532 or the current PR scope. The changes validate requested block sizes, preserve the requested sticky block size, and avoid unnecessary workspace re-carving. No unrelated change is established.

Full details: Docstring Coverage

Explanation

Docstring coverage is 82.35% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 6 files. (3 skipped: 3 unsupported.)

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• 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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[hellobertrand]

@coderabbitai review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[hellobertrand]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.