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.

Blob — an immutable file (image, PDF, attachment) held in an object storage adapter and referenced from document JSON by a server-minted opaque handle in a blobRef field. The handle syncs like any field; the bytes move over HTTP and never enter a sync lane or an event log. Reference-counted at the write boundary, swept after a grace period, read-gated like the documents that reference it. See Blobs.

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 owns one folder. In production that is a Durable Object per folder; on the Node backend, one process and one Postgres database hold many folders, each with its own server instance inside.

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

Generation — which incarnation of a docId a document is: an opaque token minted when the document is created or imported, unchanged by edits, delete and restore. Purge releases an id, so a later create under it is a new generation — which is how a reconnecting client tells its copy of the purged document from the new one. See Documents & folders.

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).

Object storage adapter — the optional byte store behind the server — R2, an S3-compatible store, a filesystem, or memory — holding blobs by opaque key. Bytes only; the catalog, the lifecycle and the authorization stay in the engine.

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 the getYDoc of the handle session.prepareDocument returns. 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.