The Rust implementation of kladde: one of the two reference implementations of the specification, with kladde-cpp in C++.

Everything here is specific to Rust and should be expected to differ in a port. The file format and the algorithms are shared; the trait shapes, the mutation-capture mechanism, the macros, and the memory layout are not.

Two audiences

If you want to use kladde in an application, start with the tutorial. It assumes you know Rust and nothing about kladde, and works up from a first program to writing your own durable types.

If you want to work on kladde, or port it, read the specification and implementation notes first — they carry the parts that are not about Rust — and come back here for the rest.

What it is

A Rust workspace providing durable data structures: containers and derived types whose mutations are recorded durably as they happen.

use kladde::Kladde;
use kladde::Durable;
use kladde_types::DurableVec;
 
#[derive(Durable)]
struct Notes {
    title: String,
    lines: DurableVec<String>,
}
 
let mut notes = Kladde::new(Notes {
    title: String::from("today"),
    lines: DurableVec::new(),
});
 
notes.get_mut().lines_mut().push(String::from("wrote a doc"))?;

The push updates the in-memory vector and appends the change to the journal before it returns. There is no save call. Kladde::new keeps its file in memory, which suits examples and tests; Kladde::create and Kladde::open do the same on a real file.

The central problem

Rust has no way to intercept a field assignment.

Every comparable system relies on exactly such a hook: Python has __setattr__, Smalltalk has message dispatch, Swift has property wrappers. Those systems make persistence syntactically invisible — self.foo = bar just works — because the language hands them a place to stand.

Rust hands them nothing. So kladde-rs makes the recording point explicit and unforgeable instead: the only mutating API is the one that records, and it is reached through a Mut.

Everything idiosyncratic about this layer follows from that one constraint, and it is the single largest thing a port should expect to redesign. A Python implementation should use property hooks and have no Muts at all.

The documents

documentcontents
Crate layoutthe workspace, the dependency direction, and where the seam falls
Durable and Mutthe central traits, regions, Fixed, why mutation needs a Mut, and why it returns a Result
Containershow the built-in containers are encoded and indexed, and cuts
The derive macrowhat it generates, fixed forms, enums in place of trait objects, and why Muts are generated per type
Transactionsthe RAII types, and what happens on unwind
Schema bindinghow a Rust type declares its descriptor, and the check at open
The storethe Rust-specific half of the storage layer: interior mutability, I/O, and the in-memory structures
Tutorialfor application authors

Status

A prototype of the whole design exists; nothing is frozen. Where the implementation departs from the reference algorithms, or found them unclear, its implementation notes say so.

areastatus
Schema descriptors, encoding, fingerprints, rules of nestingimplemented and specified
The encoding of values; schema binding to Rust types; fingerprint check at openimplemented
Containers, derive macro, Muts, regions, Fixedimplemented
File format, span table, journal, recoveryimplemented, with a span table of two levels
Flush, span policy and consolidationimplemented
Transactions, batches, and cutsimplemented; cuts on the vector only
The private chainwritten and read, but nothing kept in it
Schema evolutiondesigned, not built

8 items under this folder.