feat(cachet): add serialization support with BincodeEncoder/BincodeCodec

[schgoo]

Summary

Adds a serialization boundary for the cache pipeline, enabling typed <K, V> caches to automatically serialize keys and values into
BytesView for downstream tiers (e.g., Redis, Memcached, or any byte-oriented store).

Changes

Serialization codecs (cachet::transform::serialize)

• BincodeEncoder - one-directional T -> BytesView via bincode, writing directly into pool-backed BytesBuf memory
• BincodeCodec - bidirectional T <-> BytesView for value round-tripping

Builder API

• .serialize() on CacheBuilder and FallbackBuilder - applies a bincode serialization boundary, returning a TransformBuilder that accepts BytesView-typed fallback tiers
• promotion_policy() and time_to_refresh() on TransformBuilder - previously these were hardcoded to always() and None; now configurable at the transform boundary

Supporting changes

• DistributedCacheTier - new marker trait for tiers that operate on serialized BytesView data
• CacheEntry PartialEq - custom impl comparing only value + ttl (excludes cached_at), relaxed bound from V: PartialEq + Eq to V: PartialEq
• BytesView Hash - required for use as cache keys in hash-map-based tiers
• Add impl Into<CacheEntry<V>> for insert to simplify semantics

Documentation

• Added serialize feature to the Cargo features table in lib.rs
• Added "Serialization Boundary" example section in lib.rs module docs
• Added doc example on .serialize() builder method
• New examples/serialization.rs standalone example

Tests

• Integration test verifying full round-trip: insert typed values -> serialize to bincode bytes -> invalidate primary -> fetch from serialized fallback -> deserialize back to typed values
• Asserts exact bincode byte encoding to detect any serialization format changes

Usage

let redis = RedisCacheTier::new("redis://localhost:6379");

let cache = Cache::builder::<String, String>(clock)
    .memory()
    .serialize()
    .fallback(
        Cache::builder::<BytesView, BytesView>(clock)
            .storage(redis) // any DistributedCacheTier
    )
    .promotion_policy(FallbackPromotionPolicy::always())
    .build();

// Typed on the outside, serialized bytes on the inside.
cache.insert("user:1", "Alice").await?;
let val = cache.get("key").await?;

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a serialization boundary to the cache pipeline so typed <K, V> caches can transparently encode/decode into BytesView for byte-oriented fallback tiers (e.g., Redis/Memcached), plus exposes transform-boundary promotion/refresh configuration.

Changes:

• Introduces bincode-based serialization codecs (BincodeEncoder, BincodeCodec) and .serialize() builder methods.
• Makes TransformBuilder promotion policy + time-to-refresh configurable (previously hardcoded).
• Adds supporting traits/impls (DistributedCacheTier, BytesView: Hash, custom CacheEntry: PartialEq semantics) and an integration test/example.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
crates/cachet_tier/src/lib.rs	Gates and re-exports new DistributedCacheTier under a feature flag.
crates/cachet_tier/src/entry.rs	Changes CacheEntry equality semantics (ignore cached_at).
crates/cachet_tier/src/distributed.rs	Adds marker trait for BytesView-based distributed tiers.
crates/cachet_tier/Cargo.toml	Adds distributed feature and optional bytesbuf dep.
crates/cachet/tests/serialize.rs	Adds integration test for full serialize→fallback→deserialize round-trip.
crates/cachet/src/transform/serialize.rs	Implements bincode encode/decode codecs targeting BytesView.
crates/cachet/src/transform/mod.rs	Adds/gates serialize module and internal re-exports.
crates/cachet/src/lib.rs	Documents serialize feature and adds module docs example; tweaks InMemoryCache cfg.
crates/cachet/src/builder/transform.rs	Adds configurable promotion policy + refresh settings at transform boundary.
crates/cachet/src/builder/serialize.rs	Adds .serialize() builder methods for cache + fallback builders.
crates/cachet/src/builder/mod.rs	Gates builder serialization module.
crates/cachet/examples/serialization.rs	Adds standalone example demonstrating serialization boundary.
crates/cachet/Cargo.toml	Adds serialize feature and serde/bincode/bytesbuf optional deps.
crates/bytesbuf/src/view.rs	Implements Hash for BytesView for hashmap key use-cases.
Cargo.toml	Adds workspace dependency for bincode.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (b71990b) to head (21850c2).

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #377    +/-   ##
========================================
  Coverage   100.0%   100.0%            
========================================
  Files         224      226     +2     
  Lines       16187    16376   +189     
========================================
+ Hits        16187    16376   +189     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[afoxman]

This all looks good to me. Maybe look at using feature gates for things like serialization in this PR, which bring in more dependencies. This could be a future task - no need to hold up this PR.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.