Glossary

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

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, stored as patches. 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 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.

Lane — one of the two ordered record sets of staged changes in a changeset: changes (JSON Patch) or yjsUpdates (Yjs binary).

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

Provenance — metadata on a staged change linking it to its origin (message id, tool-call id).

Sequence — the per-document, server-assigned, monotonically increasing version number.

Session — a staging layer over the live client: accumulate changes, preview conflicts, commit atomically. See The session client.

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 session’s record for one touched document: base sequence, base snapshot, type, create flag.

sys: documents — documents maintained or synthesized by the engine: sys:index, sys:trash, sys:schema:<type>, sys:session, sys:stage:<docId>, sys:client-docs-status. Read like any other document.

Three-way preview — a derived conflict view comparing base (staged from), head (live now), and staged (base + staged changes). See Conflict preview & resolution.

Yjs reference — a { "$yjs": "<id>" } value in document data pointing at an embedded Yjs document. See Rich text with Yjs.