jonnify·persistence /echo-persistence/champ-accept-tier/the-in-heap-structure

Module 2 · Dive 2.1

The in-heap structure.

Champ keeps the outbox in a persistent map — a hash-array-mapped trie, the BEAM’s native immutable kind. Updating it does not mutate; it returns a new version that shares almost everything with the old one. That one property is why a snapshot costs nearly nothing: keep the old root. Click a slot and watch the sharing.

§1

One write, one new path

interactive
Structural sharing. The top node has eight branches, each to a subtree. Click a slot to write it: a new version appears that copies only that branch and shares the other seven by reference.
v0
readout · Click any slot. A write copies the path to the changed branch and nothing else; the untouched branches are shared by reference. v0 stays valid — which is all a snapshot is.

A real trie is deeper, so a write copies the nodes along one root-to-leaf path — on the order of the tree’s height, not its size. Everything off that path is the same memory, pointed at by both versions. The old version is never disturbed, so it remains a perfectly good thing to read — or to write to disk.

§2

Why the accept tier wants this

graft.design.md

Two consequences fall straight out, and both serve the accept tier. A snapshot is a reference: to checkpoint, Champ keeps the current root and hands it to the writer that fsyncs it, while accepts keep producing newer roots — no copy, no stop-the-world. And readers are lock-free: a reader holds a root and sees a consistent version no matter how many writes follow. The next dive turns the checkpoint into a dial; this is the property that makes it cheap.

§3

References & sources