Changesets & lanes
A session’s persisted state is a changeset: a structured value stored in a field of the host document. Its shape mirrors the hybrid change model of datadata itself.
Stages
Section titled “Stages”For every document touched by the session, the changeset holds a stage:
- the document’s base sequence — the version the edits were computed against,
- a base snapshot of its data at staging time,
- the document type, and whether the stage creates the document.
The base snapshot is what makes conflict previews cheap: conflicts are derived by comparing base, live head, and staged result — no event replay needed.
Two lanes
Section titled “Two lanes”Staged edits accumulate in two parallel, ordered lanes of records:
changes— JSON Patch operations against structured data.yjsUpdates— binary Yjs updates for collaborative text.
Both lanes are flat record sets ordered by fractional index — the same ordered-record pattern used for collections everywhere in datadata, which is what lets two authors append to the same changeset concurrently without trampling each other.
Individual staged changes are addressable: a change can be amended or dropped by id, not just wholesale.
Provenance
Section titled “Provenance”Every staged change can carry provenance — currently a message id and a tool-call id. For agent workflows this links each staged edit back to the exact conversation turn and tool call that produced it: “this change came from turn 42, tool call 3” is data, not archaeology.