@vuer-ai/vuer-rtc-server 0.2.0 → 0.2.2

package/src/journal/COALESCING.md

@@ -0,0 +1,267 @@
+# Operation Coalescing Design
+
+## Overview
+
+Coalescing reduces journal size by merging compatible operations. This improves:
+- Storage efficiency (fewer operations stored)
+- Replay performance (fewer operations to apply)
+- State serialization depth (fewer items in B-trees)
+
+## Session Boundaries and Causality Preservation
+
+**Critical constraint**: Coalescing MUST preserve the **interleaved order** of operations across sessions to maintain causality.
+
+### The Problem
+
+Given messages in timestamp order:
+```
+msg1: sessionA [op1, op2]
+msg2: sessionA [op3]
+msg3: sessionB [op4]
+msg4: sessionA [op5]
+```
+
+**WRONG** - Grouping all operations by session:
+```
+coalesced-A: [op1, op2, op3, op5]  // ❌ Lost causality
+coalesced-B: [op4]
+```
+This violates causality because `op5` happened after `op4` was received. If `op5` was created in response to seeing `op4`, reordering them breaks the happened-before relation.
+
+**CORRECT** - Preserve interleaved order, coalesce consecutive runs:
+```
+run1-A: [op1, op2, op3]  // Consecutive messages from A
+run2-B: [op4]            // Session switch to B
+run3-A: [op5]            // Back to A (preserves that op5 came AFTER op4)
+```
+
+### Implementation Strategy
+
+1. Process messages in timestamp order
+2. Detect "session switches" (when `msg[i].sessionId !== msg[i-1].sessionId`)
+3. Coalesce each consecutive run from the same session
+4. Emit coalesced messages in the same order as the runs
+
+This approach preserves Lamport's "happened-before" relation while still achieving compression benefits.
+
+## Types of Coalescing
+
+### 1. Client-Side Edit Batching (Optional, UI-Level)
+
+**Status**: Optional feature controlled by UI toggle
+
+**Current behavior**: Operations are batched with a timer (default 300ms), but each edit creates a separate operation in the batch.
+
+**Purpose**: Reduces network traffic by delaying commits during rapid editing.
+
+**Implementation location**: `packages/vuer-rtc/src/client/createGraph.ts`
+
+### 2. Server-Side TextRope Coalescing (Automatic)
+
+**Status**: ✅ **Implemented** (automatically runs during compaction)
+
+**How it works**: When the server compacts the journal, it merges single-character TextRope items into multi-character spans, preventing B-tree depth explosion.
+
+**Performance impact**: Up to 5000x speedup on real editing traces (based on "CRDTs Go Brrr")
+
+**Implementation location**: `packages/vuer-rtc-server/src/journal/JournalService.ts` (compactTextRopes function)
+
+### 3. Server-Side Operation Coalescing (Journal-Level)
+
+**Status**: Partially implemented via CoalescingService
+
+Merges historical operations in the journal. Called via `POST /api/documents/:id/coalesce`.
+
+## Coalescing Rules
+
+### Rule 1: Text Insert Coalescing
+
+Consecutive `text.insert` operations from the same session, where each insert's position follows the previous insert, are merged into a single multi-character insert.
+
+```
+Before:
+  { otype: "text.insert", position: 0, value: "a" }
+  { otype: "text.insert", position: 1, value: "b" }
+  { otype: "text.insert", position: 2, value: "c" }
+
+After:
+  { otype: "text.insert", position: 0, value: "abc" }
+```
+
+**Constraints**:
+- Same session ID
+- Positions are sequential (insert_n.position === insert_n-1.position + len(insert_n-1.value))
+- Same target node and path
+
+### Rule 1b: Text Delete Coalescing ✅ **NEW**
+
+Consecutive `text.delete` operations are merged based on deletion direction:
+
+**Forward deletion (Delete key)** - Same position:
+```
+Before:
+  { otype: "text.delete", position: 10, length: 1 }
+  { otype: "text.delete", position: 10, length: 1 }
+  { otype: "text.delete", position: 10, length: 1 }
+
+After:
+  { otype: "text.delete", position: 10, length: 3 }
+```
+
+**Backward deletion (Backspace)** - Position moves left:
+```
+Before:
+  { otype: "text.delete", position: 10, length: 1 }
+  { otype: "text.delete", position: 9, length: 1 }
+  { otype: "text.delete", position: 8, length: 1 }
+
+After:
+  { otype: "text.delete", position: 8, length: 3 }
+```
+
+**Constraints**:
+- Same session ID, key, and path
+- Either: same position (forward) OR position decreases by previous length (backward)
+
+### Rule 2: Set Operation Coalescing (with Time Threshold)
+
+Multiple `set` operations on the same `(key, path)` are merged, keeping only the latest value.
+
+**Time Threshold**: If the gap between two operations exceeds `SET_COALESCE_THRESHOLD_MS` (default: 5000ms), they are NOT coalesced. This preserves meaningful state changes while coalescing rapid updates (like dragging a slider).
+
+```
+Before (within threshold):
+  { otype: "set", key: "cube", path: "opacity", value: 0.5, ts: 1000 }
+  { otype: "set", key: "cube", path: "opacity", value: 0.6, ts: 1200 }
+  { otype: "set", key: "cube", path: "opacity", value: 0.7, ts: 1400 }
+
+After:
+  { otype: "set", key: "cube", path: "opacity", value: 0.7, ts: 1400 }
+
+Before (exceeds threshold):
+  { otype: "set", key: "cube", path: "opacity", value: 0.5, ts: 1000 }
+  { otype: "set", key: "cube", path: "opacity", value: 0.9, ts: 7000 }  // Gap > 5s
+
+After (no coalescing):
+  { otype: "set", key: "cube", path: "opacity", value: 0.5, ts: 1000 }
+  { otype: "set", key: "cube", path: "opacity", value: 0.9, ts: 7000 }
+```
+
+### Rule 3: Vector Add Coalescing
+
+Multiple `vector3.add` operations on the same `(key, path)` are summed.
+
+```
+Before:
+  { otype: "vector3.add", key: "cube", path: "position", value: [1, 0, 0] }
+  { otype: "vector3.add", key: "cube", path: "position", value: [0, 1, 0] }
+
+After:
+  { otype: "vector3.add", key: "cube", path: "position", value: [1, 1, 0] }
+```
+
+**Constraints**: Same time threshold as `set` operations.
+
+## Configuration
+
+```typescript
+interface CoalescingConfig {
+  // Time threshold for set/vector operations (ms)
+  setThresholdMs: number;  // default: 5000
+
+  // Enable/disable specific rules
+  enableTextCoalesce: boolean;   // default: true
+  enableSetCoalesce: boolean;    // default: true
+  enableVectorCoalesce: boolean; // default: true
+}
+```
+
+## API
+
+### Client-Side
+
+Already exists in `createGraph`:
+```typescript
+store.setCoalescingEnabled(true);
+store.setCoalescingDelay(300);  // Batch window in ms
+```
+
+**Enhancement needed**: Actually merge operations in the edit buffer, not just batch them.
+
+### Server-Side
+
+```http
+POST /api/documents/:id/coalesce
+Content-Type: application/json
+
+{
+  "setThresholdMs": 5000,
+  "dryRun": false
+}
+
+Response:
+{
+  "ok": true,
+  "before": { "journalBatches": 100, "operations": 5000 },
+  "after": { "journalBatches": 50, "operations": 1200 },
+  "reduction": { "journalBatches": 50, "operations": 3800 }
+}
+```
+
+## Implementation Plan
+
+1. **Client-side op merging** (`vuer-rtc/src/client/actions.ts`)
+   - Add `mergeOperations()` function that merges compatible ops in edit buffer
+   - Call before `commitEdits()` when coalescing is enabled
+
+2. **Server-side coalescing** (`vuer-rtc-server/src/journal/CoalescingService.ts`)
+   - New service that processes journal batches
+   - Merges operations within each batch
+   - Re-computes snapshot after coalescing
+   - Updates database atomically
+
+3. **Text CRDT depth fix** (`vuer-rtc/src/crdt/Rope.ts`)
+   - Multi-char inserts create fewer B-tree nodes
+   - Each insert operation adds one item, not N items for N characters
+
+## Metrics & Debugging
+
+Add logging for coalescing effectiveness:
+```
+[coalesce] document=demo-room ops_before=5000 ops_after=1200 reduction=76%
+```
+
+## Known Issues
+
+### B-Tree Depth Explosion
+
+The text CRDT B-tree (`_textRope.content._tree`) grows very deep with many single-char inserts. Each character becomes a separate node in the tree. With thousands of characters, the tree exceeds msgpack's depth limit.
+
+**Root cause**: Each `text.insert` with single char creates a separate item in the B-tree.
+
+**Solution**:
+1. Short-term: Increase msgpack `maxDepth` (done: 100 → 500, need more)
+2. Long-term: Coalesce inserts client-side to create multi-char operations
+3. Alternative: Refactor B-tree serialization to use flat structure
+
+## Testing
+
+1. Type rapidly in text CRDT demo
+2. Verify message log shows fewer, larger operations
+3. Verify journal in DB Viewer shows coalesced operations
+4. Test undo/redo still works after coalescing
+5. Test multi-client conflict resolution after coalescing
+
+## References
+
+### Causality and Operation Ordering
+
+- [Peritext: A CRDT for Collaborative Rich Text Editing](https://dspace.mit.edu/bitstream/handle/1721.1/147641/3555644.pdf?sequence=1&isAllowed=y) - MIT research on collaborative text editing with CRDTs
+- [Real-time collaborative editing using CRDTs](http://www.diva-portal.org/smash/get/diva2:1304659/FULLTEXT01.pdf) - Comprehensive study on CRDT-based collaborative editing
+- [Geometry-Aware CRDTs for Efficient Collaborative Geospatial Editing](https://www.mdpi.com/2220-9964/14/12/468) - Research on preserving both temporal causality and spatial dependencies, includes discussion of operation batching and causality preservation
+
+### Key Concepts
+
+- **Lamport's "happened-before" relation**: Operations must maintain causality - if op B was created after seeing op A, that ordering must be preserved
+- **Interleaving**: When operations from different sessions are interspersed, coalescing must not reorder them
+- **Vector clocks**: Track causality across distributed sessions