diff options
| author | Josh Kingsley <josh@joshkingsley.me> | 2025-11-23 17:27:34 +0200 |
|---|---|---|
| committer | Josh Kingsley <josh@joshkingsley.me> | 2025-11-23 17:27:34 +0200 |
| commit | eb96b8eba0faf07adc5be4463759ec8b64ddc0e0 (patch) | |
| tree | 014b7405ca5d55066ca2bba4aba2caa561571970 /docs/design/README.md | |
| parent | be5cae1beb714680f56d7598b8f5c4816000cb1d (diff) | |
chore: remove docs
Diffstat (limited to 'docs/design/README.md')
| -rw-r--r-- | docs/design/README.md | 76 |
1 files changed, 0 insertions, 76 deletions
diff --git a/docs/design/README.md b/docs/design/README.md deleted file mode 100644 index 7486251..0000000 --- a/docs/design/README.md +++ /dev/null @@ -1,76 +0,0 @@ -# CRDT Design Documentation - -This directory contains the design documentation for Notive's collaborative music notation CRDT implementation. - -## Documents - -### [crdt-design.md](./crdt-design.md) -The foundational design document covering: -- Why we need a custom operation-based CRDT (not Automerge/Yjs) -- Core type definitions (Cell, Grid, Operations) -- Domain constraints (duration preservation, subdivisions) -- Initial conflict resolution options -- Related to existing TypeScript implementation - -### [fractional-indexing.md](./fractional-indexing.md) -Deep dive into stable position identifiers: -- Why array indices don't work for concurrent edits -- How fractional indexing provides stable cell references -- Implementation details and examples -- Handling position space exhaustion -- Production considerations - -### [branch-based-merge.md](./branch-based-merge.md) -Advanced conflict detection and resolution strategy: -- Detecting concurrent operations with vector clocks -- Grouping operations into causal branches -- Reconstructing per-actor views of state -- Smart conflict detection (overlapping subdivisions, lost edits, duration mismatches) -- User experience for merge conflicts -- Automatic resolution where safe, user control where ambiguous - -## Reading Order - -For someone new to the project: -1. Start with **crdt-design.md** for context and requirements -2. Read **fractional-indexing.md** to understand cell positioning -3. Review **branch-based-merge.md** for the conflict resolution strategy - -## Implementation Status - -The CRDT is being implemented as a Rust crate in `/crdt`: -- ✅ Vector clock implementation -- ✅ Basic Doc structure with operation log -- ✅ Core domain types (Cell, Row, Grid, DerivedId) -- ✅ CreateGrid operation -- ✅ ChangeSubdivisions operation -- ❌ Fractional indexing (decided not to use in operations) -- ⏳ Conflict detection -- ⏳ Branch-based merge - -## Design Principles - -1. **Causal Consistency** - Operations respect causality via vector clocks -2. **Deterministic Realization** - Each branch produces consistent state from its operation sequence -3. **No Silent Data Loss** - Conflicts are explicit, not silently resolved -4. **Domain Invariants** - Preserve musical constraints (e.g., row duration) -5. **User Control** - Explicit conflict resolution for ambiguous concurrent edits -6. **Simplicity Over Commutativity** - Branch-based resolution instead of forcing all operations to commute - -## Key Architectural Decisions - -- **Operation-based CRDT** (not state-based) for semantic operations -- **Vector clocks** for causality tracking (future: consider Hybrid Logical Clocks) -- **Deterministic IDs** using `DerivedId` (no fractional indexing in operations) -- **Range-based subdivision** instead of tombstones (simpler semantics) -- **Branch-based conflict resolution** rather than automatic commutativity -- **User-driven resolution** for ambiguous concurrent edits - -## Future Work - -- Hybrid Logical Clocks for wall-clock ordering -- Snapshot and compaction strategy -- Server-side operation validation -- Operational transformation for some conflicts -- Multi-grid support and cross-grid operations -- Undo/redo with CRDT semantics |
