Collaborative Editing

Real-time multi-user editing with O-tree CRDT, Ed25519-signed author attribution, awareness state (cursors/selections), automatic three-way merge fallback, and LLM-assisted change narration.

1. Overview

Xudanu supports real-time collaborative editing: multiple users can edit the same document simultaneously, seeing each other's changes live. The system is built on an O-tree CRDT (Conflict-free Replicated Data Type) with Ed25519 cryptographic attribution for every character.

The implementation lives in src/server/otree_crdt.rs (~2,030 lines) and provides:

• Per-work CRDT state with concurrent session tracking
• Text delta application with automatic conflict resolution
• Awareness state (cursor positions, selections, typing indicators)
• Signed updates with Ed25519 author identity
• Automatic fallback to three-way merge when CRDT state diverges
• LLM-generated change narration (diff summaries)

2. O-Tree CRDT Model

The OtreeCrdt struct manages collaborative editing state for all works on the server. Each work has its own CRDT "document" that tracks:

• Current text — the canonical document content
• Revision history — every version, accessible by revision number
• Active sessions — which users are currently editing this work
• Author identity — public key + display name + club ID for each session

Text delta operations

When a client sends a text edit, the CRDT applies it as a delta:

1. Client sends TextDeltaOp with the full replacement text
2. Server computes the diff against the current text
3. A new revision is created with Ed25519 attribution
4. The update is relayed to all other sessions editing the same work

Revision storage

Every edit creates a new revision. The CRDT maintains:

• revisions: HashMap<BeId, Vec<String>> — per-work revision history
• cached_text: HashMap<BeId, String> — memoized current text
• work_authors: HashMap<BeId, HashMap<SessionId, OtreeAuthorIdentity>> — per-session author tracking

3. Awareness State

Awareness is the real-time presence system. Each editing session broadcasts its state to all other sessions on the same work:

When a session updates its awareness, the server relays it to all other sessions editing the same work via OtreeAwarenessRelayResult, which contains the list of (SessionId, OtreeSyncSessionId) pairs to notify.

4. Signed Updates & Author Identity

Every edit is cryptographically signed. The OtreeSignedUpdate contains:

• update_text — the new document content
• signature — Ed25519 signature over the text
• signer_public_key — the author's 32-byte public key

The OtreeAuthorIdentity struct ties the public key to a human-readable name and club:

• public_key: [u8; 32] — Ed25519 verifying key
• display_name: String — shown in attribution panel
• club_be_id: BeId — the author's personal club

Author type classification

Authors are classified into types that affect attribution coloring in the UI:

5. Three-Way Merge Fallback

When CRDT state diverges beyond what can be reconciled (e.g., two users make conflicting edits to the same paragraph), the system falls back to three-way merge:

1. The last common revision is identified as the base
2. Both divergent revisions are compared against the base
3. Non-conflicting changes are merged automatically
4. Conflicts are resolved using LastWriterWins strategy (based on timestamp)
5. The merged result becomes the new canonical revision

The three-way merge engine (src/edition/three_way.rs, ~1,889 lines) produces:

• A merged Edition combining both inputs
• Mapping objects showing how positions in each input map to the merged result
• Conflict regions flagged for potential user review

6. LLM Integration

The CRDT integrates with the LLM subsystem (src/server/ollama.rs) for:

• Auto-titling: When a new work is created, the LLM generates a title from the first few paragraphs
• Diff narration: After edits, the LLM summarizes the changes in natural language
• Writing feedback: Optional writing suggestions (future)

LLM-appended text is attributed with a separate OtreeAuthorIdentity marked as LLM type, ensuring the attribution panel correctly shows it in purple.

7. Protocol Flow

Figure 1: Collaborative editing protocol. Edits flow through the server with attribution; awareness is relayed between sessions.

8. Udanax-Gold Comparison