jonnify·persistence /echo-persistence/foundations/persistence-concepts

Module 3 · Chapter I — Foundations

Persistence concepts.

Before either engine, the words. Both the native Elixir engine and the Rust one speak the same five — Volume, LSN, snapshot, the OCC commit, the conditional-write fence. Learn them engine-neutral here and the two engines later are the same idea twice. Tap a term in the anatomy to see where it lives.

Anatomy of a Volume. A Volume is an append-only log of commits, each stamped with a monotonic LSN. Tap a term to light up its part.
Volume · VOL0O5fmcxbds8 snapshot · read @ LSN 4 fence 7
readout · Tap a term. A Volume is an append-only log; an LSN names each commit; a snapshot is a read at an LSN; a commit appends the next LSN; the fence makes that append safe.
§1

Five words, one model

graft.design.md

A Volume is the unit of durable state — a branded id and an append-only log. Each entry is a commit named by a monotonic LSN, so “the state” is always “the log up to some LSN.” A snapshot is therefore just a read at an LSN, and because the log is append-only that read is consistent and lock-free. A commit appends the next LSN; the fence is what guarantees only one writer claims that next slot. Those last two are the subtle ones, so they each get a dive.

§2

The three dives

module 3
Dive 3.1

Volume, LSN, snapshot

The log as an immutable ribbon. Scrub to any past LSN and read the snapshot you would see — time travel for free, from append-only.

 Dive 3.2

The OCC commit

Two writers, one head LSN. Run the race and watch optimistic concurrency: one appends, the other is told {:conflict, head} and retries.

 Dive 3.3

The conditional-write fence

Two nodes write the same commit object. Create-if-not-exists lets one through and rejects the other — toggle the fence off and watch split-brain.
§3

Build & check

What you build

A five-line glossary in your own words: Volume, LSN, snapshot, commit, fence — each defined by what it is, not how it’s coded. If your snapshot definition mentions the LSN and your fence definition mentions “only one writer,” you have it.

Check

Answer two questions without code: why is a snapshot free if the log is append-only, and what is the difference between the OCC commit (Dive 3.2) and the fence (Dive 3.3)? They are both about “one writer wins,” at two different layers.

§4

References & sources