Copy-on-Write Document Model, Snapshot History & Persistence
This skill covers how application state is stored, mutated, undone, and persisted across L0 (containers/chunks), L1 (doc), L2 (ops), and L3 (format) so that an egui UI can render and mutate large documents with zero-copy undo/redo.
Core Rules
- Pure Serializable Domain Model (
L1):Documentand its child entities incrates/docare pure data structures (Serialize,Deserialize,Clone) with no UI or rendering dependencies.
- Sparse Copy-on-Write (
Arc) Storage:- Large buffers or collections are partitioned into fixed-size chunks/tiles stored in
BTreeMap<ChunkId, Arc<Chunk>>. - Mutating a chunk uses
Arc::make_mut, cloning only the touched chunk while sharing all untouched chunks across snapshots. - Allocating buffers from untrusted/external dimensions uses fallible reservation (
Vec::try_reserve_exact$\to$AllocationError) so huge/hostile inputs never abort the process.
- Large buffers or collections are partitioned into fixed-size chunks/tiles stored in
- Whole-Document Snapshot History (
O(chunks)pointer copy, zero data copy):- Because heavy data payloads are
Arc-shared, cloning aDocumentcosts only pointer copies. History(crates/ops) storesVecDeque<HistoryState>where eachHistoryStateholdsArc<Document>plusSelectionTarget(the active/selected entity IDs when the state was created).- Memory is bounded by
max_statesandmax_bytes(counting uniqueArc<Chunk>addresses viaArc::as_ptr).
- Because heavy data payloads are
- Compile-Time Complete Native Format:
crates/formatserializesDocumentinto a bundle withmanifest.json+ content-addressedblobs/<blake3>.zst.- Struct conversions in
crates/format/src/convert.rsdeliberately destructuredocstructs without..so adding a field todocfails compilation untilformat(with#[serde(default)]) explicitly handles it.
Workflow: Adding or Modifying Document State
- Add the field in
crates/docwithSerialize, Deserialize(and#[serde(default)]where needed). - Update
crates/format/src/manifest.rsandconvert.rs(which will fail to compile until you wire the new field) with#[serde(default)]so existing saved files continue to load. - Mutate via
Session::editincrates/engine, which automatically snapshotsbefore: Arc<Document>, applies the mutation closure, computesstep_damage(&before, &after), records the undo state (or coalesces if the interactiveegui"coalesce"key matches), and incrementsDocState::revisionso theeguiviewport knows to repaint. - See cow-tiles-and-history.md for concrete code patterns.
Validation Steps
See egui-testing-infrastructure for property-based (proptest!) COW chunk testing, round-trip corpus oracles, and memory/RSS benchmarking:
cargo test -p <app>-doc -p <app>-ops -p <app>-format --lib --tests
cargo clippy -p <app>-doc -p <app>-ops -p <app>-format --all-targets -- -D warnings