Glossary

Attribution — who wrote a stored event: the principal’s subject and actor, recorded on every event in both lanes and never rewritten. See Storage & event log.

Changeset — the persisted state of a staging session: stages plus two lanes of staged changes, stored in a field of the host document.

Client — the connection to one folder, owning reads, writes, subscriptions and the optimistic overlay. Live and staging sessions are opened on it. Connects over a socket or, in-process, by function calls.

Document — the unit of data: docId, type, server-assigned sequence, JSON data, optionally with embedded Yjs documents. See Documents & folders.

Event log — the append-only history of a document’s accepted changes: one log per sync lane — JSON Patch events under sequence, Yjs update events under yjs_sequence. See Storage & event log.

Folder — the unit of synchronization and authority; one server instance (one Durable Object, in production) owns one folder.

Fractional index — a string key that sorts between its neighbors, used to order records in collections without array indices.

Guard — a precondition on an update: either sequence (document unchanged since base) or patch (RFC 6902 test ops on the touched values). See Changes as JSON Patch.

Host document — the document whose field stores a staging session’s changeset — typically the document that motivates the changes (e.g. a conversation).

In-process client — a full client connected to the server by function calls instead of a socket. See In-process clients.

JSON lane — the half of document sync carrying structured changes as JSON Patch, versioned by sequence. See Two sync lanes.

Lane — in sync: the JSON lane or the Yjs lane. In a changeset: changes (an ordered record set of JSON Patch records) or yjsCopies (one staged Yjs copy per target Y.Doc).

Optimistic update — a change applied to the local view immediately, retired when the server confirms it (or discarded when rejected). See Sync & optimistic updates.

Presence — ephemeral participant state (cursor, selection, display name), carried in named channels: a sys:presence:<presenceType>:<docId> document riding the ordinary document wire — no bespoke protocol — read and written per-session through a synthetic sys:presence-view:<presenceType>:<docId> view. Never stored. See Presence.

Principal — who a client acts as: a subject (the user or service the write is on behalf of; null when anonymous) and an actor (what kind of code is acting — a user’s frontend, a named AI agent, server-side system code). The two are independent, and neither confers privilege: identity is never authority. Stamped onto every stored event as attribution. See Authorization.

Sequence — the per-document, server-assigned, monotonically increasing version number of the JSON snapshot. The Yjs lane has its own version, yjs_sequence. See Two sync lanes.

Session — a document-editing surface on a client. Two kinds share it: a live session, whose writes land on the document immediately, and a staging session, which accumulates the same calls into a changeset to preview and commit atomically. Commit, discard, stages and conflicts exist only on the latter. See Staged sessions.

Soft delete — removing a document from the index and read path while retaining its history, so it can be restored at the exact sequence it left. Deleted documents are listed in sys:trash. See Documents & folders.

Stage — a staging session’s record for one touched document: base sequence, type, create/delete kind, pending rename. No snapshot — the staged patches themselves live in the changeset’s lanes.

Staged Yjs copy — a staging session’s staged Yjs content: the live target Y.Doc forked into a host sub-document that editors bind to and collaborate on natively. Returned by session.getYDoc. Tracks the live target while the session runs, and is merged back into it at commit. See Changesets & lanes.

State vector — Yjs’s compact summary of the content a peer already holds. Subscribes carry one per embedded Y.Doc so the server can answer with exact diffs; the server’s answers carry its own so the client can push back what it lacks. See Two sync lanes.

System document — engine state exposed as a document under the reserved sys: prefix, read and subscribed to like any other. See System documents.

Three-way preview — a derived conflict view comparing base (staged from), head (live now), and staged (base + staged changes). The base is resolved on demand — live head, an in-memory pin, or an event-log replay on a cold client. See Conflict preview & resolution.

Write-behind burst — a run of streamed Yjs deltas buffered in memory and flushed as one merged transaction into the Yjs lane’s log. Single-author, so attribution stays correct. The fold shortens the log rather than perforating it: the surviving rows keep consecutive positions, and the document’s yjs_sequence follows them down, so coalescing is invisible from outside storage. See Storage & event log.

Yjs lane — the CRDT half of document sync: Yjs updates under their own per-document version and stored log, never advancing sequence. See Two sync lanes.

yjs_sequence — the Yjs lane’s per-document version, and each Yjs log row’s position: the document’s value is its latest Yjs event’s, exactly as sequence is its latest JSON event’s. 0 for a document with no Yjs history, fully independent of sequence, and server-side only — no wire event carries it, because a CRDT lane gives clients nothing to do with a version.