Skip to content

docs(openspec): propose fix for OT client/server divergence - #210

Open
gohabereg wants to merge 4 commits into
mainfrom
docs/openspec-fix-ot-client-convergence
Open

gohabereg wants to merge 4 commits into
mainfrom
docs/openspec-fix-ot-client-convergence

Conversation

@gohabereg

@gohabereg gohabereg commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

What

Planning only: the fix-ot-client-convergence OpenSpec bug change, plus a reproduction spec. This is the bottom of a stack; the data-node operations proposal sits on top of it.

Why

When two clients edit concurrently, the clients and the server end up with three different documents. Four defects combine:

  • OTClient never stamps a revision on the operations it sends. The server's conflict filter (op.rev >= undefined) then matches nothing, so the server never transforms any operation and applies them in arrival order.
  • The client's revision counter is off by one, and it ignores the revision in the handshake reply.
  • Incoming operations are transformed against queued ops only, never against the in-flight one. The queue is never rebased against incoming ops.
  • Concurrent inserts at the same position shift on both sides, so each side orders them differently.

Fix (summary)

  • The client stamps each sent operation with its base revision, tracks its in-flight operation, and transforms incoming operations through the in-flight op and then the queue, rebasing each.
  • transform(against, againstIsLater = false) makes transform order explicit. Order can't be inferred from revisions, because remote ops reach the undo stacks rebuilt from model events and carry none.

Notes for review

  • packages/ot-server/src/convergence.spec.ts is the reproduction. It runs two OTClients against a real DocumentManager, and its three tests are marked it.failing so CI stays green until the fix lands; task 1.1 flips them back to it. A throwaway prototype of the fix made all three pass. Only one existing spec changes under it: the one pinning "the other op has no revision → Neutral".

🤖 Generated with Claude Code

Adds the fix-ot-client-convergence bug change and a failing
convergence spec (two OTClients + DocumentManager) reproducing it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Unit Tests

Package Coverage Delta
@editorjs/ot-server N/A N/A

Mutation Tests

Package Mutation score Dashboard URL

Keeps CI green until the fix lands; task 1.1 flips them back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

## 2. Implementation

- [ ] 2.1 Thread `againstIsLater` through `Operation.transform`, `BatchedOperation.transform` and `OperationsTransformer`, and use it for the text-insert tie and the data last-writer-wins rule

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.

Include a regression test for concurrent inserts at different positions, and transform these inserts by position without merging their payloads. With a multi-character insert, #transformAgainstTextInsert can duplicate the other insert when its position falls inside the effective range, even after the planned client rebasing.

## 2. Implementation

- [ ] 2.1 Thread `againstIsLater` through `Operation.transform`, `BatchedOperation.transform` and `OperationsTransformer`, and use it for the text-insert tie and the data last-writer-wins rule
- [ ] 2.2 In `OTClient`: set the revision from the handshake, ack (`rev + 1`) and remote operations (`rev + 1`); stamp it on sent operations; track the in-flight operation; transform incoming operations through in-flight then queued operations and rebase them

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.

Handle Neutral as a no-op on the server while advancing the revision and acknowledging it, including when client rebasing neutralizes a queued operation. Revision stamping lets overlapping deletions produce Neutral, which currently throws and leaves the server rejecting all further operations for that document.

gohabereg and others added 2 commits November 11, 2026 17:41
Address review on fix-ot-client-convergence:

- An Insert transformed against a concurrent Insert that starts inside
  its effective range splices the other payload into its own, so the
  text lands twice. Transform Insert against Insert by start position
  only, and add regression specs for inserts at different positions.
- DocumentManager throws on a Neutral operation after advancing the
  revision, which wedges every later operation on the document and
  leaves the sender unacknowledged. Treat Neutral as a no-op that is
  stored, advances the revision and is broadcast; OTClient counts the
  revision for Neutral remote operations and drops queued operations
  that rebasing neutralizes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TffpCm82NH5xXR1yeBew6Q
Keep this PR spec-only. Task 1.1 now adds convergence.spec.ts as part
of the implementation instead of flipping tests that already exist, and
the proposal no longer points at the file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TffpCm82NH5xXR1yeBew6Q
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