Index of every page on this site: llms.txt
All skills
domesticmouse avatar

/egui-cow-document-model

@606a5d5
Run it yourself

Use this skill when exploring, understanding, designing, or modifying an immutable/copy-on-write (Arc) document model, sparse chunked/tiled storage, O(1) snapshot undo/redo history, or compile-time complete content-addressed file persistence in an engine-first Rust and egui application.

  • 2 files
  • 6.8 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/domesticmouse/skills/egui-cow-document-model

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈78 tokens for metadata: the name and description. ≈763 when used: this file. ≈878 more on demand in 1 file.

Description uses 3.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈313 characters, or 3.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Pure Serializable Domain Model (L1):
    • Document and its child entities in crates/doc are pure data structures (Serialize, Deserialize, Clone) with no UI or rendering dependencies.
  2. 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.
  3. Whole-Document Snapshot History (O(chunks) pointer copy, zero data copy):
    • Because heavy data payloads are Arc-shared, cloning a Document costs only pointer copies.
    • History (crates/ops) stores VecDeque<HistoryState> where each HistoryState holds Arc<Document> plus SelectionTarget (the active/selected entity IDs when the state was created).
    • Memory is bounded by max_states and max_bytes (counting unique Arc<Chunk> addresses via Arc::as_ptr).
  4. Compile-Time Complete Native Format:
    • crates/format serializes Document into a bundle with manifest.json + content-addressed blobs/<blake3>.zst.
    • Struct conversions in crates/format/src/convert.rs deliberately destructure doc structs without .. so adding a field to doc fails compilation until format (with #[serde(default)]) explicitly handles it.

Workflow: Adding or Modifying Document State

  1. Add the field in crates/doc with Serialize, Deserialize (and #[serde(default)] where needed).
  2. Update crates/format/src/manifest.rs and convert.rs (which will fail to compile until you wire the new field) with #[serde(default)] so existing saved files continue to load.
  3. Mutate via Session::edit in crates/engine, which automatically snapshots before: Arc<Document>, applies the mutation closure, computes step_damage(&before, &after), records the undo state (or coalesces if the interactive egui "coalesce" key matches), and increments DocState::revision so the egui viewport knows to repaint.
  4. 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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 606a5d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for domesticmouse/skills/egui-cow-document-model