Module serialization 

Postcard-based cache serialization with versioned envelopes.

This module provides the canonical serialization format for all cache storage in cache-kit. It uses Postcard for performance and wraps all cache entries in versioned envelopes for schema evolution safety.

Architecture

Every cache entry follows this format:

┌─────────────────┬─────────────────┬──────────────────────────┐
│  MAGIC (4 bytes)│VERSION (4 bytes)│POSTCARD PAYLOAD (N bytes)│
└─────────────────┴─────────────────┴──────────────────────────┘
  "CKIT"              u32 (LE)           postcard::to_allocvec(T)

Safety Guarantees

• Deterministic: Same value always produces identical bytes
• Validated: Magic and version checked on every deserialization
• Versioned: Schema changes force cache eviction, not silent migration
• Type-safe: Postcard preserves exact Rust types

Example

use cache_kit::serialization::{serialize_for_cache, deserialize_from_cache};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, PartialEq, Debug)]
struct User {
    id: u64,
    name: String,
}

let user = User { id: 1, name: "Alice".to_string() };

// Serialize with envelope
let bytes = serialize_for_cache(&user)?;

// Deserialize with validation
let deserialized: User = deserialize_from_cache(&bytes)?;
assert_eq!(user, deserialized);

Structs

CacheEnvelope

Versioned envelope for cache entries.

Constants

CACHE_MAGIC

Magic header for cache-kit entries: b“CKIT“

CURRENT_SCHEMA_VERSION

Current schema version.

Functions

deserialize_from_cache

Deserialize a value from cache storage with validation.

serialize_for_cache

Serialize a value with envelope for cache storage.