feat: checksum FFI binding + benchmark (cachekit-core#13 Phase 2)

[27Bslash6]

Closes the cachekit-py half of cachekit-io/cachekit-core#13 (Phase 2 of the checksum-only API plan; Phase 1 shipped in cachekit-core 0.3.0 via cachekit-io/cachekit-core#50).

What

• Bump cachekit-core 0.2.0 → 0.3.0 — verified live on crates.io (cargo add --dry-run) before flipping the pin; Cargo.lock updated, cargo build --locked resolves from the registry.
• Expose checksum / verify_checksum via PyO3 — free functions registered unconditionally in the _rust_serializer pymodule (they must not vanish when the encryption feature is off). verify_checksum rejects a non-8-byte expected value with ValueError instead of panicking or returning a wrong verdict. Docstrings carry the non-cryptographic warning.
• Byte-verification (interop criterion): unit tests assert the FFI output equals the KAT vectors pinned in cachekit-core src/checksum.rs (checksum(b"cachekit-kat"), checksum(b"")) and equals xxhash.xxh3_64_digest — three independent implementations agreeing on the exact wire bytes. No wire format change (the primitive produces the same bytes already embedded in every StorageEnvelope).
• Benchmark (deliverable artifact) — py-xxhash vs Rust FFI at 64 B / 1 KB / 64 KB / 1 MB, ≥30 rounds, per-size groups; results in the module docstring. Verdict: performance-neutral (worst gap ~65 ns/call at 1 KB compute; FFI wins small-payload verify 2.5×). The deferred serializer migration to FFI is a dependency-hygiene call, not a perf one.
• CI guards — fail on a leftover path = dep for cachekit-core (would let maturin build public wheels from the local workspace); clippy --locked so a stale lockfile fails loudly.
• Docs — standalone checksum API documented with an executable (markdown-docs) example on the ByteStorage feature page; corrected that page's false "Blake3" claims (checksums have been xxHash3-64 since core 0.1.0). Repo-wide docs sweep stays with Documentation accuracy sweep: mmap, Blake3, pickle, orjson, master-key env var #168.

Verification

• pytest tests/unit → 1620 passed; pytest tests/critical → 255 passed (suites run separately, as CI does)
• ruff format --check . / ruff check . / basedpyright --level error → clean
• cargo fmt --check / cargo clippy --locked -- -D warnings → clean
• pytest --markdown-docs docs/features/rust-serialization.md → the new doc example executes

Out of scope (per plan)

Migrating the Arrow/orjson envelope internals from the xxhash package to the FFI, and dropping the blake3 dependency (still used by hash_utils.py for cache keys — a separate, security-relevant concern).

Summary by CodeRabbit

• New Features
  • Added standalone checksum and verification APIs for raw byte data via the Rust-backed Python interface.
  • Checksums now use xxHash3-64 and always return an 8-byte digest.
  • Verification returns a boolean result and strictly validates the expected digest is exactly 8 bytes.
• Documentation
  • Updated ByteStorage docs and pipeline diagrams to reflect LZ4 + xxHash3-64 integrity, including non-cryptographic checksum notes.
• Bug Fixes
  • Improved CI lint reproducibility by enforcing --locked clippy checks.
  • Added a CI guard to prevent non-crates.io lock resolutions for core components.
• Tests
  • Added unit tests with deterministic vectors plus buffer-protocol compatibility, and new checksum FFI benchmarks.

[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: e30617bd-b8ac-4844-b03b-5bf765b44725

📥 Commits

Reviewing files that changed from the base of the PR and between a260705 and d699dd8.

📒 Files selected for processing (4)

• .github/workflows/ci.yml
• docs/features/rust-serialization.md
• rust/src/python_bindings.rs
• tests/unit/test_checksum_ffi.py

---

Walkthrough

The PR upgrades cachekit-core to 0.3.0, exposes standalone xxHash3-64 checksum functions through PyO3, updates Rust serialization documentation, adds unit and benchmark coverage, and enforces locked dependency resolution in CI.

Changes

Checksum FFI and integration

Layer / File(s)	Summary
Core dependency and Python checksum API rust/Cargo.toml, rust/src/python_bindings.rs, rust/src/lib.rs	Upgrades cachekit-core, exposes checksum and verify_checksum, and registers them independently of encryption.
Checksum contract documentation and tests docs/features/rust-serialization.md, tests/unit/test_checksum_ffi.py	Documents and tests the 8-byte xxHash3-64 format, buffer-protocol support, verification, tampering, and invalid lengths.
Performance coverage and reproducible CI checks tests/benchmarks/benchmark_checksum_ffi.py, .github/workflows/ci.yml	Compares Python and Rust checksum performance and enforces crates.io dependency resolution with locked Cargo execution in CI.

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

Sequence Diagram(s)

sequenceDiagram
  participant PythonCaller
  participant checksum_py
  participant cachekit_core
  PythonCaller->>checksum_py: checksum(data)
  checksum_py->>cachekit_core: compute xxHash3-64
  cachekit_core-->>checksum_py: 8-byte digest
  checksum_py-->>PythonCaller: bytes digest
  PythonCaller->>checksum_py: verify_checksum(data, expected)
  checksum_py->>cachekit_core: verify checksum
  cachekit_core-->>checksum_py: boolean result
  checksum_py-->>PythonCaller: verification result

Loading

Possibly related issues

• cachekit-io/cachekit-core issue 13 — Covers the checksum-only API, PyO3 bindings, documentation, and Rust FFI benchmarks.
• cachekit-io/cachekit-core issue 46 — Covers the related Blake3-to-xxHash3-64 description updates.

Possibly related PRs

• cachekit-io/cachekit-py#140 — Updates the same cachekit-core dependency path.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the changes and verification, but omits several required template sections like Motivation, Type of Change, and the security/testing checklists.	Add the missing template sections, especially Motivation, Type of Change, Security Checklist, Documentation Validation, Testing, and Backward Compatibility.
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: checksum FFI bindings plus benchmark work for cachekit-core phase 2.
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.

✨ 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 agent/winston/cd3e781b

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/rust-serialization.md`:
- Line 41: Update the pipeline diagram in rust-serialization.md to replace
“Blake3 integrity hash” with “xxHash3-64” while preserving the existing
corruption-detection description and diagram formatting, so it matches the
checksum name in the comparison table.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2c1d1a9c-2352-4352-9359-5ea81a9434e5

📥 Commits

Reviewing files that changed from the base of the PR and between eac5098 and 2f575bb.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• .github/workflows/ci.yml
• docs/features/rust-serialization.md
• rust/Cargo.toml
• rust/src/lib.rs
• rust/src/python_bindings.rs
• tests/benchmarks/benchmark_checksum_ffi.py
• tests/unit/test_checksum_ffi.py

[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!