LAB-347: perf: release the GIL during ByteStorage compress/hash

[27Bslash6]

Problem

ByteStorage.store()/retrieve() ran the entire LZ4 compress + xxh3 hash + msgpack serialize core under the GIL. A large payload (up to 512MB) froze every other Python thread for the full duration — ~1.8s for a 256MB incompressible payload. (cachekit-io/cachekit-core#45, LAB-347)

Fix

Wrap the pure-Rust core of store, retrieve, estimate_compression and validate in Python::detach (pyo3 0.29's name for allow_threads). Sound because &[u8] args borrow immutable bytes buffers kept alive by the call frame. estimate_compression/validate do the same full-payload compression/decompression work, so they get the identical one-line treatment.

The companion full-payload data.to_vec() copy named in core#45 was already eliminated in cachekit-core 0.3.0 (cachekit-io/cachekit-core#48), which this repo already pins — verified: StorageEnvelope::new takes &[u8], and Cargo.lock resolves cachekit-core 0.3.0 from crates.io.

Acceptance criteria → evidence

• GIL released, concurrent thread makes progress: tests/critical/test_byte_storage_gil.py — a ticker thread must timestamp inside the middle 50% of a large store/retrieve call window (margins dwarf the ~5ms GIL switch interval, so this is deterministic in both directions). Verified to FAIL against the previous bindings (rebuilt without detach: both tests fail; with it: pass).
• Redundant copy eliminated / single unavoidable copy: core-side copy gone since 0.3.0 (inspection). New subprocess peak-RSS invariant in tests/performance/test_large_object_memory.py guards the whole FFI stack: 512MB compressible store peaks at 1.24× payload (the old copy would push ~2.2×; bound set at 1.7×). Runs in the existing CI memory-invariant step. Remaining copies are the unavoidable ones: Rust buffer → PyBytes on return.
• Round-trip correctness: byte-for-byte roundtrip test at 64MB + full unit (1685) / critical (259) suites green, including serializer backward-compat.
• Format-neutral (AC chore(main): release cachekit 0.1.0 #4): diff touches only GIL handling in rust/src/python_bindings.rs — zero changes to envelope layout, AAD, key derivation, or wire format, so the crypto/protocol review gate is not triggered. Encryption bindings deliberately untouched.

Also verified locally

cargo fmt --check, cargo clippy --locked -D warnings, ruff format/check ., basedpyright --level error, rust unit tests, and all three CI pytest selections (unit -m "not slow" -n auto, critical -m "not slow", performance -m "performance and slow").

Follow-up observed (out of scope)

The msgpack envelope encodes compressed_data: Vec<u8> as an array of integers (no serde_bytes), inflating incompressible payload envelopes to ~1.58× and dominating store cost (~150MB/s). Fixing it changes the wire format → protocol-gated, separate issue.

Closes cachekit-io/cachekit-core#45

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 58 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 015c05db-6e33-43c7-bc62-7684397b52a3

📥 Commits

Reviewing files that changed from the base of the PR and between e45106e and 980de83.

📒 Files selected for processing (4)

• rust/src/python_bindings.rs
• tests/critical/conftest.py
• tests/critical/test_byte_storage_gil.py
• tests/performance/test_large_object_memory.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/winston/fbcf2f4c

---

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

[27Bslash6]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

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.

[27Bslash6]

Expert-panel crypto/protocol gate — ByteStorage GIL release (automated review-signoff sweep, deep-executor)

Ran the mandatory expert panel (high-stakes; the ByteStorage store/retrieve path sits beneath the AES-GCM encryption layer, so Ray's crypto/protocol gate applies to any change here). HEAD c1a9840.

Verdict: SHIP. The GIL-release change does NOT alter the wire format, encryption, AAD, key derivation, or cache-key format — it is a pure concurrency change with byte-identical output (verified by test_roundtrip_unchanged_by_gil_release).

• bug-hunter-supreme — NO FINDINGS. Verified against PyO3 0.29 source: &[u8] extraction binds only to immutable bytes (rejects bytearray), so no mutable-buffer race during the GIL-released window; no py token captured into any detach closure; closures return owned values (no escaping reference); ByteStorage is Sync (Arc metrics), so shared-instance concurrency is compiler-enforced-safe; map_err runs after GIL re-acquire; validate panic is not swallowed.
• security-specialist — NO FINDINGS. All memory-safety vectors (UAF, mutable-buffer TOCTOU, shared-state race, panic-across-FFI) refuted against actual PyO3 0.29 source + panic="abort" release profile. Envelope/checksum/AES-GCM plaintext byte-identical. Pure concurrency change confirmed.
• catchphrase-agent — NO CUTS. 14 lines of required FFI change + 4 tests each pinning a distinct invariant (GIL-released / byte-identity / concurrency / no-copy peak-RSS). Appropriately calibrated for the stakes.
• code-craftsman — 2 MIN (both in the test file; dispositions below). Independently confirmed the interior-window GIL proof is sound and discriminating (a continuous GIL hold yields zero interior ticker stamps → deterministic failure; a false pass is impossible).

Finding dispositions (both non-blocking, test-diagnostics only)

• [MIN] tests/critical/test_byte_storage_gil.py:12 — docstring claims "margins are >=25ms" but _MIN_CALL_SECONDS = 0.05 enforces only a 50ms floor → 12.5ms margins (the 25ms figure assumes the ~100ms design payload). Accepted, non-blocking — a maintainer who trims _PAYLOAD_BYTES would trust a margin the floor doesn't enforce. Suggest bumping the floor to 0.1 or rewording. Flagged for your judgment at merge.
• [MIN] tests/critical/test_byte_storage_gil.py:112 — a worker that raises or deadlocks never sets results[idx], so the assertions raise KeyError instead of a clear "worker N did not complete" (a deadlock is exactly what this concurrency test guards against). Accepted, non-blocking — the test still fails on deadlock, just with poor context; hardening the post-join assert would improve diagnostics. Flagged for your judgment at merge.

Neither MIN touches production code; the 14-line binding change is unanimously clean. Not re-opening CI convergence for two test-comment/diagnostics nits.

CI green.

[27Bslash6]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

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.

[27Bslash6]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

---

You're currently rate limited under our Fair Usage Limits Policy. Your recent PR review activity is in the 95th percentile or higher among CodeRabbit users, so adaptive limits apply. Your next review will be available in 24 minutes.