The Rust binding of the language-independent schema model, and the check it performs at open.
Two layers
The split is deliberate and worth preserving in a port.
kladde-schema — the model.
The descriptor types, the canonical encoding, the fingerprint computation, and a SHA-256 implementation.
It has no connection to the store, to Durable, or to any Rust type system machinery, which is what makes it portable and testable on its own: the conformance vectors for encoding and fingerprints exercise this layer and nothing else.
The binding — where Rust types meet the model.
A Durable type declares its own descriptor in describe_local, and the derive macro generates that declaration.
The binding
A type contributes its descriptor by describing itself into a SchemaBuilder, which interns descriptors into a table and hands back references:
- Recursion terminates.
A type that refers to itself reserves its table slot, keyed by its
TypeId, before describing its fields. - Descriptors are deduplicated by type, so a type used in twenty places occupies one table entry.
- The table is built once, not per value.
What a type declares
A struct declares a Struct descriptor with its fields in declaration order; an enum declares an Enum with its variants canonically ordered by discriminant.
A hand-written implementation declares whatever descriptor matches the bytes it actually reads and writes — which is the rule that most often trips people up.
A hand-written implementation of a plain field-sum declares Struct, not Opaque; “hand-written” and “opaque” are different axes, see the guiding principle.
The containers declare structural descriptors, so that a tool can decode them: a Vec<T> and a DurableVec<T> alike a Sequence of the element type, a String Text, and a map a Map of its key type and its value type.
An enum’s variant holds one payload: (), the empty struct, for a unit variant, the field’s type for a variant of one unnamed field, and otherwise an anonymous struct of its fields named after the variant (the derive).
Option<T> declares an enum Option with a one-byte discriminant width, None = 0 holding () and Some = 1 holding a T; a tuple a struct TupleN with positional fields; Fixed<T> a Fixed of T’s descriptor; and Box<T> is schema-transparent, reusing T’s descriptor, as #[kladde(transparent)] types do.
Only DurableBlob declares Opaque, without a fixed size, since its serde payload is not decomposable.
At create and at open
Kladde::create encodes the root type’s descriptor table into the schema chain, which the header’s schema_head names, and writes the root’s fingerprint into the header.
Kladde::open compares the header’s fingerprint with the application’s and fails closed on a mismatch, with an error carrying both fingerprints.
It never parses the descriptor table on the matching path, which is the fast path the fingerprint exists for.
Resolution — decoding by the writer’s descriptors — does not exist yet, so a mismatch cannot be bridged; see Evolution.
Design invariants
Worth keeping in mind when changing anything here:
- The fingerprint must not depend on table layout. References are encoded structurally, so any renumbering or reordering produces the same hash; a test permutes the table and asserts equality.
- A type’s own name is not fingerprinted; its fields’ and variants’ names are.
- Determinism over everything. No hash-map iteration order, no addresses, nothing incidental may reach the hash.
- Encoding and fingerprinting are separate functions over the same model. They share the canonical order but not the code, because the fingerprint deliberately omits things the encoding includes.