Module codec 

Serialization codecs for cache entries.

Implement CacheCodecImpl on concrete types, then use CacheCodec::from_impl to produce a type-erased codec for the cache.

Wire format

Every serialized entry begins with a small hand-framed envelope so the reader can validate it before trusting the body:

[magic: 4B = b"LCE1"]
[envelope_version: u8]
[type_id_len: u16 LE][type_id: utf8]   # stable, author-assigned
[type_version: u32 LE]                 # per-type body schema version
<body, written by the type's CacheCodecImpl::serialize>

The envelope is deliberately not protobuf: it is the most stability-critical part, must parse robustly against arbitrary bytes (including data written by older, pre-stabilization builds), and never changes shape. Bodies use protobuf headers, where field-number evolution pays off.

Decode outcome

Deserialization never propagates a parse failure as a hard error into the cache path. Anything the reader cannot confidently interpret — absent or wrong magic, an unknown envelope_version, a type_id mismatch, an unsupported type_version, or a body decode error — becomes CacheDecode::Miss. A backend turns Miss into a normal cache miss and recomputes the value. This is what lets data written by an older format self-heal: it simply fails the magic check and is regenerated.

Structs

CacheCodec

Type-erased codec for serializing and deserializing cache entries.

Enums

CacheDecode

Outcome of deserializing a cache entry.

CacheMissReason

Why a cache entry could not be decoded into the expected type.

Constants

MAGIC

Magic bytes that prefix every stabilized cache entry.

Traits

CacheCodecImpl

Serialization trait for cache entries.

CacheRangeReader

Bounded random reads from a persistent cache payload. Backends may coalesce and align physical I/O while codecs request logical byte ranges.

Functions

has_cache_envelope

Returns true if data begins with the cache-entry MAGIC.