Yjs

Yjs 14 CRDT Patterns

Reference Repositories

• Yjs: CRDT framework for shared editing and offline-first data
• Yjs Protocols: algorithmic grounding for sync and awareness

Upstream Grounding

When conflict semantics, transaction origins, shared-type behavior, update encoding, storage growth, or shared-type APIs affect correctness, use source-backed grounding before relying on memory. If DeepWiki MCP is available, ask a narrow question against yjs/yjs; for sync and awareness algorithms, ask against yjs/y-protocols. If DeepWiki is unavailable or the repo is not indexed, use upstream source or official docs directly. Treat DeepWiki as orientation, then verify decisive details against the locally pinned @y/y types and source before changing code.

Epicenter targets @y/y 14 only. Do not add yjs 13, y-indexeddb, a compatibility reader, a package alias, a dual wire, or a fallback. Existing Yjs 13 code is replacement material, not a compatibility surface.

Skip DeepWiki for stable basics and repo-local patterns already documented below.

Read references/document-design.md before choosing how a new row document is structured. Counters, user-controlled ordering, and nested shapes each have a conflict behavior that is expensive to change once data exists.

Read references/debugging.md when a document converges to unexpected state or grows faster than its content.

Related Skills: See svelte for reading store data into a component, and arktype for the expression strings a workspace is written in.

Transactions, Origins, And Undo

• Yjs updates are commutative and idempotent. A state vector describes what a replica HAS; it does not order what it owes. A delete moves no client clock, so two replicas can hold the same vector and differ, which is why obligation in this store is a log position rather than a vector. Both the cursor and the outbox are then DERIVED from one column on the update rows, MAX(authoritySeq) and authoritySeq IS NULL, so neither can disagree with the bytes it accounts for (packages/data/evidence/invariants.test.ts, ADR-0298).
• Use Y.encodeStateVector(doc) to describe local clocks, then Y.encodeStateAsUpdateV2(doc, remoteStateVector) to send only missing updates.
• Persist and transmit bytes from the updateV2 event. Replay them with Y.applyUpdateV2(doc, update, origin).
• Wrap multi-write user actions in doc.transact(() => { ... }, origin). This reduces observer churn and gives persistence, providers, and undo logic a useful origin.
• Treat transaction origins as the boundary for filtering provider echoes, app-authored operations, and undo tracking.
• Scope Y.UndoManager to concrete shared types. Set trackedOrigins, tune captureTimeout, and call stopCapturing() between logically separate commands.
• Use relative positions for collaborative cursor and selection anchors. Raw numeric indexes drift under remote edits.
• Y.snapshot() is a historical marker that depends on retained delete history. Y.encodeStateAsUpdateV2(doc) is the self-contained checkpoint format.
• Prefer separate top-level docs over Yjs subdocuments unless Epicenter owns the whole provider lifecycle for the subdoc path.

Store Connection

• Yjs is network-agnostic. It supplies CRDT state, state vectors, updates, and awareness behavior, not Epicenter's connection topology, authorization, or durability contract.
• One socket per application, not one per open document. A replica connects to STORE_SYNC_ROUTE.pattern (/api/store/v1/sync, in packages/sync/src/store-route.ts) with a namespace naming the workspace and a cursor naming its own durably applied position, so a reconnect is a catch-up rather than a fresh start (ADR-0222).
• Whose data it is never appears in the query. It comes from the resolved bearer, server-side, so there is no value a client can put in the URL that reaches another partition (ADR-0092).
• Browser upgrades authenticate through exactly one bearer.<token> subprotocol entry, because a browser upgrade cannot set Authorization; the mount echoes only the main subprotocol on the 101, so the token never round-trips. Non-browser clients may use an Authorization header. Do not use cookie-only upgrades, query-string credentials, or post-accept authentication frames.
• The wire is framing and nothing else: push, ack, refuse, entry, offer, snapshot, wanted (packages/data/src/sync/frames.ts). No frame knows what an update means, what a row is, or what Yjs is, which is exactly why chunking is safe at that layer.
• Large updates are chunked at CHUNK_BYTES, set by Cloudflare's documented Durable Object SQLite value cap rather than by anything about Yjs. Do not raise it to the measured wall; the documented limit is the one Cloudflare is entitled to enforce.
• Presence is deliberately absent until a concrete consumer earns awareness state and disconnect cleanup. If added later, awareness is ephemeral and must never be persisted into the Y.Doc or the SQLite update log as canonical data.

One Document Per Application

An application is ONE Y.Doc. Roots are tables:<name> and kv. A row is a nested Y.Type attribute on its table root, a field holding a value is a JSON attribute on the row, and the one field holding a node is a nested Y.Type at the row's reserved content key (ADR-0295, ADR-0309). Holding the attribute is what it means to exist; removing it is what deletion does, and it reclaims the row's whole subtree in one operation.

Those two words are the vocabulary. A value is replaced whole on write, so two devices writing one converge on a winner. A node is edited in place, so two devices editing one both keep every keystroke.

Their retired names are scalar and prose; both belong in no new code or documentation (ADR-0309).

The nesting is not stylistic. Item.write calls findRootTypeKey, a linear scan of doc.share, so one root per row makes encoding quadratic in rows (5,417 ms for 20,000 rows against 13 ms nested).

There are no independent row documents. A row's content node used to live in its own top-level document at a derived address, with a document manager, a tombstone table and an openDocument verb (ADR-0248); ADR-0295 collapsed all of it into the row. Advice naming documents.ts, openDocument, _tombstones, or "hydrate the row's document" is describing a design that no longer exists.

// Values are attributes on the row, written through the table.
db.tables.notes.update(noteId, { title, pinned: true });

// The content node is ON the row, read synchronously with everything else.
const note = db.tables.notes.get(noteId);
const body = note?.content;           // a live Y.Type an editor binds to

Inside the application document only Doc.get mints, and every key reaching it must be a table name the database declares: reading an unknown ROW through getAttr costs nothing, while a misspelled TABLE name costs a permanent root.

Three Signals, And Which One Fires

• table.subscribe fires when a table's SHAPE changes: a row added, removed, or a value edited. It does NOT fire for an edit inside a content node. It hands the listener the ROW IDS the commit touched, so a consumer holding a projection rebuilds only what moved; a consumer that just re-reads may ignore them.
• table.watch(node) fires for edits inside one content node, keyed by the node's own identity.
• kv.subscribe fires when any declared key changes, and carries nothing. There are ten keys, so naming them would buy nothing.

The distinction is forced by the library. Delivery routes off transaction.changed, which Yjs fills with the types a transaction modified DIRECTLY, so a keystroke in a body puts the BODY's type there; its parent is the row, not the table root. Nothing bubbles to the table. A surface that watches a table for changes inside a node sees nothing.

Owner-Side Persistence

One document, so one chain: _updates (id, bytes, authoritySeq) in SQLite, and the matching object store in the browser's IndexedDB. There is no per-document partition, no _tombstones, and no separate _outbox — what a replica still owes is the rows with authoritySeq IS NULL, which is a partial index rather than a second table (ADR-0238). Do not add a separate IndexedDB provider or a second document store.

• Hydrate BEFORE attaching the updateV2 listener. Replaying stored bytes through the listener would re-append them; the engine applies its history first and then attaches, and throws if a foreign apply ever reaches the listener, so a mistake here fails the open loudly rather than duplicating a log (packages/data/src/store/store.ts).
• A locally authored append joins the durable queue owed. Authority-accepted bytes arrive on a remote origin and create no outbound obligation, which is what the one listener checks before appending.
• The chain compacts by ROW, and the row's authoritySeq picks which of two mechanisms applies (ADR-0301). Rows the authority has taken replay into a fresh gc: true document and rewrite as one complete V2 state update: replay rather than mergeUpdatesV2, because merging does not GC and collapsing tombstones is the point. encodeStateAsUpdateV2 folds buffered pending state back into its output, so a fold taken while dependencies are missing cannot silently drop them.
• Rows still OWED cannot take that path, and this is the one to get right. A whole-document re-encode is not a delta the authority could be offered, so owed rows collapse with mergeUpdatesV2 into one resendable row that takes a NEW id above every existing one. Folding them like acknowledged rows would offer the authority a whole document per keystroke; inheriting a lower id would let an earlier acknowledgement stamp bytes it never carried.
• Treat replay corruption as storage failure: a document that cannot hydrate refuses its open rather than handing out a half-hydrated handle.

Storage Optimization

v14 has ONE shared type, Y.Type, reached as doc.get(name) for a map-like root or doc.get(name, 'text') for a text one. There is no Y.Map, Y.Text, Y.Array or Y.XmlFragment; code or advice naming them is Yjs 13 and is replacement material.

Attribute tombstones retain the key forever, and every setAttr(key, value) creates a new internal item and tombstones the previous one, which is why gc: true is what collapses a field edited 5,000 times down to two structs.

Raw Types At The Boundary

A Y.Type handed out by a table handle is a live CRDT reference and is MEANT to be bound to an editor. That is the design: the store hands the editor the real thing rather than proxying it, because a copy would break the merge that makes it worth having.

What does not belong in a feature:

• Constructing the layout. A feature does not decide which attribute a row keeps its content node under. It asks the table for the row and reads the declared field.
• Casting into shape. as Y.Type outside packages/data/src/store/ means something is reading a document the store owns without going through it.
• Reaching the document. doc.get(...) in a feature bypasses the declaration, the conformance lens, and the durable queue at once.

The store's own boundary is packages/data/src/store/document.ts: it holds one cast, at rowType, and states why (a container whose attributes are themselves types has no expressible configuration, so a table root stays untyped while a ROW's shape is declared). Everything downstream of that line is typed.

References

• Learn Yjs - Interactive tutorials
• Yjs Documentation - API reference
• Yjs INTERNALS.md - How Yjs works internally
• GitHub issue #520 - Conflict resolution discussion with dmonad
• fractional-indexing - Production library
• YATA paper - Academic foundation
• packages/data/src/store/document.ts: the application-document grammar (roots, row types, field reads)
• packages/data/src/store/log.ts and packages/data/src/store/persistence.ts: the durable update log, the outbox, and the persistence queue
• packages/data/evidence/invariants.test.ts: the library behaviour this design rests on, pinned against the installed rc
• packages/data/src/sync/: the Yjs 14 wire (frames, connection, client, authority)
• ADR-0295: one document per application, and a row holds its rich content (supersedes ADR-0248)
• ADR-0309: a row is its id, its values, and one node at content; the table declares what the node means
• ADR-0221: what subscribe reports and when it fires
• ADR-0146: Yjs 14-only persistence decision
• ADR-0159: one owner-side SQLite update log and shared attachment seam