Zed Editor - Collaboration Architecture
=======================================

https://zed.dev/docs/collaboration/overview
https://zed.dev/blog/crdts


PHILOSOPHY
----------

Collaboration is "part of Zed's DNA" - not bolted on.
Built from ground up with multiplayer in mind.
Uses CRDTs instead of Operational Transformation.


WHY CRDT OVER OT
----------------

Operational Transformation (OT):
  - Transform concurrent operations to apply in different orders
  - Requires central server to sequence operations
  - Complex correctness proofs
  - What Google Docs uses

CRDT approach:
  - Structure data so operations are inherently commutative
  - No transformation needed - apply directly on any replica
  - Express edits in terms of logical locations, not absolute offsets
  - Decentralized by nature


CRDT IMPLEMENTATION DETAILS
---------------------------

Anchors (logical positions):
  - Each position is (insertion_id, offset) pair
  - insertion_id = replica_id + sequence_number
  - Replicas get unique IDs from server, then generate IDs locally
  - No collision risk for concurrent operations

Fragments:
  - Text organized into fragments
  - Each fragment knows its insertion ID and offset
  - Remote operations can find insertion points regardless of local changes

Immutable insertions:
  - Every piece of inserted text is immutable forever
  - Edits mark deletions, they don't remove content
  - This is key to conflict-free merging


DELETION HANDLING
-----------------

Tombstones:
  - Deleted text gets tombstone marker
  - Text is hidden, not removed
  - Allows insertions within deleted ranges to resolve correctly
  - "the deleted text is merely hidden rather than actually thrown away"

Version vectors:
  - Each deletion has version vector
  - Encodes "latest observed sequence number for each replica"
  - Prevents concurrent insertions from being incorrectly tombstoned


CONFLICT RESOLUTION
-------------------

Concurrent insertions at same location:
  - Sorted by Lamport timestamps (descending)
  - Preserves user intent
  - Guarantees same ordering on all replicas

Lamport clocks:
  - Logical timestamps for causal ordering
  - Each operation increments local clock
  - Receiving operation updates clock to max(local, received) + 1


UNDO/REDO
---------

Undo map:
  - Associates operation IDs with counts
  - Odd count = undone
  - Even count = redone (or never undone)
  - Enables arbitrary-order undo in collaborative context
  - Your undo doesn't affect others' operations


DATA STRUCTURES
---------------

SumTree (the "soul of Zed"):
  - Thread-safe, snapshot-friendly, copy-on-write B+ tree
  - Leaf nodes contain items + summaries
  - Internal nodes contain summary of subtree
  - Used EVERYWHERE in Zed (20+ uses)

Rope:
  - B-tree of 128-byte string chunks (fixed size)
  - Summaries enable fast offset-to-line/column conversion
  - Concurrent access safe via copy-on-write snapshots

Where SumTree is used:
  - Text buffers (via Rope)
  - File lists in project
  - Git blame info
  - Chat messages
  - Diagnostics
  - Syntax trees


SERVER ARCHITECTURE
-------------------

Components:
  - Collaboration server (Rust)
  - PostgreSQL database
  - LiveKit for voice/screenshare (optional)

Protocol:
  - Protocol buffers (proto/zed.proto)
  - RPC over WebSocket
  - Server routes messages, manages rooms, auth

Key crates:
  - crates/proto/ - message definitions
  - crates/rpc/ - generic RPC framework
  - crates/collab/ - collaboration server


CHANNELS
--------

IRC-like but for code:
  - Each channel = ongoing project or work-stream
  - Join channel = enter shared room
  - See what everyone is working on (ambient awareness)
  - Easy to jump into someone's context

Features:
  - Shared cursors with zero latency
  - Following (your view follows their navigation)
  - Voice chat built-in
  - Text chat in editor
  - Screen sharing


WHAT A CLI VERSION WOULD NEED
-----------------------------

From Zed's approach:
  1. CRDT text buffer (like Cola)
  2. Anchor-based positions instead of offsets
  3. Tombstone deletions with version vectors
  4. Lamport timestamps for ordering
  5. Undo map for per-user undo
  6. Some transport (WebSocket, WebRTC, etc)
  7. Optional: server for discovery/auth, or pure P2P

The SumTree/Rope is optional but helps with:
  - Large file performance
  - Efficient snapshot creation for background tasks


LINKS
-----

CRDT blog:     https://zed.dev/blog/crdts
Rope/SumTree:  https://zed.dev/blog/zed-decoded-rope-sumtree
Channels:      https://zed.dev/blog/channels
Collab docs:   https://zed.dev/docs/collaboration/overview
Local dev:     https://zed.dev/docs/development/local-collaboration