Skip to content

docs(openspec): propose data node and value operations - #211

Open
gohabereg wants to merge 1 commit into
docs/openspec-fix-ot-client-convergencefrom
docs/openspec-add-data-node-operations
Open

gohabereg wants to merge 1 commit into
docs/openspec-fix-ot-client-convergencefrom
docs/openspec-add-data-node-operations

Conversation

@gohabereg

Copy link
Copy Markdown
Member

What

Planning only: the add-data-node-operations OpenSpec change. It is stacked on #210, so review that one first.

Why

Data-node and value changes (DataNodeAddedEvent, DataNodeRemovedEvent, ValueModifiedEvent) stay local today: they aren't sent to collaborators and can't be undone. The v3 List tool depends on all of them, because it stores items as one flat array: items: [{ content, depth, checked? }]. Tab and checkbox toggles are updateValue, Enter inserts an array element, and a Backspace merge removes one.

What changes (summary)

  • Model
    • Explicit createDataNode dispatches synchronously, with the author's userId. Today the event has none.
    • Data nodes created while a block is being built are marked isInitialization. Undo and collaboration skip them; adapters still get them, so data-first rendering keeps working.
    • modifyData handles DataIndex.
    • insertData on an existing object key replaces the node.
  • Collaboration
    • The three events become Insert/Delete (payload: [subtree]) and Modify (payload / prevPayload).
    • New transformer rules for array positions: numeric key segments are array indices. Data and text operations inside a shifted element are re-keyed; operations inside a deleted element become Neutral.
    • Same-position ties and same-key conflicts use the explicit transform order from docs(openspec): propose fix for OT client/server divergence #210.
  • Undo works in both the core and collaboration managers once the model replays these changes.

Out of scope

🤖 Generated with Claude Code

Sync and undo for DataNodeAdded/DataNodeRemoved/ValueModified, with
array-position transform rules. Depends on fix-ot-client-convergence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gohabereg
gohabereg force-pushed the docs/openspec-add-data-node-operations branch from e6d4bd2 to cf3df7f Compare October 17, 2026 18:11
### D6. Same-key conflicts that do not shift

- **Modify vs. Modify, same block and key.** Last-writer-wins in server order: `op` becomes `Neutral` iff `against` comes later (`againstIsLater`). Otherwise `op` is kept and applied after `against`. This is the rule `fix-ot-client-convergence` sets for values.
- **Insert vs. Insert on the same object key** (last segment not an integer). The same rule as Modify. With replace-on-insert (D4), the later write in server order wins on the server and on every client, exactly as for values.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For concurrent inserts at meta ({url: 'a'}) and meta.url ('b'), processing meta first leaves the server at b, but its broadcast overwrites the second client's pending b with a. Define ancestor/descendant conflicts for replace-on-insert as well as exact-key ties.


### D7. Undo/redo

`Operation.inverse()` already swaps Insert ↔ Delete with the same payload and swaps `payload` / `prevPayload` for Modify. With D3 and D4 in place, collaboration undo of a data operation works without new code. Core's `UndoRedoManager` replays `event.data` for Added/Removed (the raw subtree, which matches the model) and inverts Modified, so it works once D1 (skip the marker), D2 (attribution) and D4 (`modifyData`) are in place.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two local inserts at items.0, followed by a remote insert at items.1, leave both stored undo indexes at 0 under D5. Undoing twice then deletes the remote element and leaves the first local element; the stack needs rebasing in each entry's historical coordinates.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants