fix(l1): guard SWR refresh commits against newer mutations (LAB-728)

[27Bslash6]

Summary

• make SWR refresh completion conditional on a per-key mutation token shared by a client and its clones
• invalidate stale tokens before explicit set/delete I/O, including cancellation and failure paths
• let still-valid slow refreshes repopulate after the original L1 entry expires or is evicted
• renew Moka hard expiry on refresh and draw freshness jitter once per entry instead of on every L1 hit
• cover plain, encrypted, set/delete race, clone-sharing, expiry-renewal, and slow-refresh scenarios

Root cause

The merged SWR task committed through the ordinary unconditional write path, so a slow background result could overwrite a newer explicit write or resurrect a deletion. Moka's custom expiry also lacked update handling, which retained the original hard-expiry deadline, and freshness jitter was sampled on each hit.

The mutation guard is deliberately process-local, matching LAB-728's L1 serving-policy scope. Cross-instance invalidation remains outside this ticket.

Validation

• cargo test --features cachekitio,redis,encryption,l1,macros,memcached,file
• cargo clippy --all-targets --features cachekitio,redis,encryption,l1,macros,memcached,file -- -D warnings
• wasm32 Workers + encryption check
• macros-only and macros+l1+unsync checks
• changed-file pre-commit hooks, including secret scan
• critical-stakes expert panel: SHIP (bug, security, craftsmanship, and pragmatism passes)

Key/AAD/wire construction is unchanged; encryption and cross-SDK vector tests pass.

Documentation

Rust README and rustdoc now describe guarded completion, full-TTL renewal, fixed per-entry jitter, and the process-local boundary. Companion docs PR cachekit-io/docs#20 was updated and its Astro production build passes. Protocol matrix PR cachekit-io/protocol#43 remains accurate at its feature-summary level.

[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: 16 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: 712e68ff-0ee1-4f3c-b311-855f91e20fbf

📥 Commits

Reviewing files that changed from the base of the PR and between 068b84a and a44d61d.

📒 Files selected for processing (8)

• README.md
• crates/cachekit-macros/src/lib.rs
• crates/cachekit/src/client.rs
• crates/cachekit/src/flight.rs
• crates/cachekit/src/l1/mod.rs
• crates/cachekit/src/lib.rs
• crates/cachekit/tests/l1_tests.rs
• crates/cachekit/tests/swr_tests.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/codex-sol/lab-728-swr-concurrency-fix

---

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

[kodus-27b]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​