fix: harden cache-envelope framing and compression config resolution

[27Bslash6]

Summary

Follow-up to #152, which was merged before its review feedback was applied. This re-applies the six review comments — 2 robustness fixes + 4 test/typing hygiene — against the now-merged code.

Changes

Robustness (observable behavior)

• wrapper.py: validate v3 frame bounds before parsing. Truncated/corrupt b"CK" frames now raise a clean ValueError (Truncated cache envelope frame / Invalid cache envelope header length) instead of a low-level IndexError/JSON error.
• arrow_serializer.py: narrow the compression auto-resolution except to ImportError. Invalid CACHEKIT_ARROW_COMPRESSION values now surface as a pydantic ValidationError instead of being silently masked into a zstd fallback (silent config drift).

Typing / test hygiene

• wrapper.py: wrap()/unwrap() use dict[str, Any] in their public signatures.
• test_arrow_serializer.py: test_default_is_auto_zstd is now env-independent (monkeypatch.delenv + reset_settings in finally).
• test_serialization_wrapper.py: the encryption fixture uses monkeypatch.setenv so a pre-existing CACHEKIT_MASTER_KEY is restored on teardown (no cross-test env leakage).
• test_l1_memory_bounds.py: add a same-key oversized-update test (the stale smaller entry is evicted, not served).

Verification

• ruff check / ruff format --check: clean
• basedpyright: 0 errors
• pytest (affected unit tests + wrapper.py doctest): 77 passed, 2 skipped

Summary by CodeRabbit

• Bug Fixes

  • Clarified compression fallback so the default fallback to zstd occurs only when the configuration module cannot be imported; misconfiguration errors now surface instead of being masked.
  • Stricter cache-envelope parsing to reject malformed or truncated frames with clearer errors.
  • Cache now drops stale smaller entries when oversized updates occur.

• Tests

  • Added and hardened tests to isolate environment state and verify the new fallback, parsing and eviction behaviours.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 74e1ec7b-ca49-4f49-8205-d01b2f10bd68

📥 Commits

Reviewing files that changed from the base of the PR and between c9cea01 and 75e2c57.

📒 Files selected for processing (2)

• tests/unit/test_arrow_serializer.py
• tests/unit/test_serialization_wrapper.py

---

Walkthrough

Tightens SerializationWrapper type hints and adds stricter v3 envelope bounds checks, narrows ArrowSerializer’s fallback to only catch ImportError when resolving "auto" compression, and updates tests to use pytest monkeypatch plus adds an oversized-update eviction test.

Changes

Serialization and Envelope Validation Improvements

Layer / File(s)	Summary
Serialization wrapper type hints and v3 frame validation src/cachekit/serializers/wrapper.py	Type hints for wrap and unwrap now use dict[str, Any] for metadata. Adds bounds checking for v3 binary cache frames: rejects frames shorter than the minimum prefix and validates declared header length does not exceed buffer.
Arrow serializer exception handling refinement src/cachekit/serializers/arrow_serializer.py	_resolve_compression("auto") now catches only ImportError when importing the settings singleton so configuration/validation errors are not masked.
Test isolation, env handling, and oversized-entry test tests/unit/test_arrow_serializer.py, tests/unit/test_serialization_wrapper.py, tests/unit/test_l1_memory_bounds.py	Tests now use monkeypatch for environment variables and reset settings appropriately; added negative unwrap tests for truncated/invalid frames and a test ensuring oversized put evicts stale smaller entries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• cachekit-io/cachekit-py#152: Overlapping changes to ArrowSerializer compression fallback and SerializationWrapper v3 frame parsing/validation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarises the main changes: hardening cache-envelope framing validation and compression configuration resolution, which are the two core robustness fixes.
Description check	✅ Passed	The PR description is comprehensive and covers all required template sections: summary, detailed changes (robustness and typing), verification steps, and type of change is clearly indicated.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/coderabbit-152-followup

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!