# Y.js vs Automerge: Decision for rStack + Fileverse Integration

## Current State

rSpace uses **both** frameworks in a layered architecture:

```
┌─────────────────────────────────────────┐
│  TipTap Editor                          │
│  ↕ y-prosemirror binding                │
│  ↕ Y.js (editor collaboration)          │  ← Fileverse integrates HERE
├─────────────────────────────────────────┤
│  Automerge (document state + sync)      │  ← State management stays HERE
│  ↕ WebSocket binary sync protocol       │
│  ↕ IndexedDB encrypted persistence      │
└─────────────────────────────────────────┘
```

## Why This Dual Approach Works

### Y.js Layer (Editor)
- `y-prosemirror`: Official TipTap/ProseMirror binding for real-time editing
- `y-indexeddb`: Client-side persistence for editor state
- Awareness protocol: Cursor positions, user presence
- **This is what Fileverse's ddoc and collaboration-server use**

### Automerge Layer (State)
- Document metadata, permissions, notebook structure
- Binary sync protocol over WebSocket
- Encrypted storage with DocCrypto
- Migration path from PostgreSQL

### Integration Surface

Fileverse components connect at the Y.js layer:
- `collaboration-server` speaks Y.js sync protocol over WebSocket
- `@fileverse-dev/ddoc` uses `y-prosemirror` internally
- `@fileverse-dev/dsheet` uses Y.js for cell sync

The Automerge layer is invisible to Fileverse — it handles higher-level state that Fileverse doesn't need to know about.

## Decision

**Keep the dual architecture.** No migration needed.

### Rationale

1. **No conflict** — Y.js and Automerge operate at different levels
2. **Fileverse compatibility** — Their components plug into the Y.js layer directly
3. **Automerge strengths preserved** — Better merge semantics for structured data, Rust/WASM performance for large documents
4. **Migration cost: zero** — No existing code needs to change

### What This Means for Each Integration

| Integration | CRDT Layer | Notes |
|-------------|-----------|-------|
| E2E encryption | Neither (operates on raw bytes) | Encrypts before CRDT, decrypts after |
| IPFS storage | Neither (file blobs) | CIDs stored in Automerge metadata |
| Collab server | Y.js | Handles editor sync + awareness |
| dSheet | Y.js | Self-contained Y.js-based component |
| UCAN auth | Neither (auth layer) | Wraps transport, not CRDTs |

## Alternative Considered: Full Y.js Migration

If we were starting fresh, using Y.js for everything would be simpler. But the migration cost outweighs the benefit:
- Automerge schemas, storage, and sync code in rSpace would all need rewriting
- The PostgreSQL → Automerge migration tool would be wasted
- Automerge's typed document schemas are more ergonomic than Y.js's untyped maps/arrays

## Conclusion

The existing architecture is already well-positioned for Fileverse integration. No CRDT migration needed. Focus integration efforts on the Y.js/TipTap layer where Fileverse components naturally connect.