Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions openspec/changes/fix-ot-client-convergence/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
## Bug

Two clients editing concurrently end up with different documents, and the server ends up with a third. Driving two `OTClient`s against a real `DocumentManager` reproduces it. Four defects combine, and two more surface once the first four are fixed:

- `OTClient` never puts a revision on the operations it sends. `Operation.rev` is unset on local operations, so the server's conflict filter (`op.rev >= undefined`) matches nothing, and the server applies every operation untransformed, in arrival order.
- The client's revision counter is off by one: it stores the last-seen history index, while the server expects the next one. It also ignores the revision in the handshake reply.
- An incoming operation is transformed against queued operations only, not against the one awaiting acknowledgement. Queued operations are never rebased against the incoming operation, and are later sent with a newer revision, so the server never rebases them either.
- Concurrent inserts at the same position both shift right, so each side orders them differently. The data-value last-writer-wins rule infers order from "the other operation has no revision", which stops holding once revisions are sent.
- An Insert transformed against a concurrent Insert compares its own effective range (the span its text will occupy) with the other's position. When the other Insert starts inside that span, the transform splices the other payload into its own, so the text is inserted twice. With `hello`, Y inserting `Z` at 3 and X inserting `abc` at 2 from the same revision, the server ends with `heaZbclZlo` instead of `heabclZlo`. Revisions don't help: the server makes exactly this transform.
- `DocumentManager` throws `Unknown operation type` on a `Neutral` operation, after it has already advanced the revision and stored the operation. The rejected promise stays as the operation in processing, so every later operation on that document fails, and the sender never gets an acknowledgement. Once revisions are sent the server really transforms, and overlapping deletions, deletions of the same block and same-key value conflicts all produce `Neutral`.

## Fix

- `OTClient` sends each operation with its base revision: the number of server operations the client has applied. It takes that number from the handshake reply, from every acknowledgement and from every remote operation.
- `OTClient` keeps the in-flight operation. An incoming operation is transformed through the in-flight operation and then each queued one, and each of those is rebased against it, so queued operations go out already accounting for it.
- `transform(against, againstIsLater = false)` makes the order explicit instead of inferring it from revisions. When `against` comes earlier (the default: server history, undo stacks, the open batch), the transformed operation shifts on a position tie and wins a same-key value conflict. When `against` comes later, it keeps its position and becomes `Neutral`. Only `OTClient` passes `true`, when it transforms an incoming operation against its own unacknowledged operations.
- An Insert transformed against an Insert compares start positions only and never merges payloads: an earlier Insert shifts it right, a later one leaves it unchanged, and a tie follows `againstIsLater`.
- `DocumentManager` treats `Neutral` as a no-op: it skips the model, stores the operation, advances the revision and returns it, so the server broadcasts it. That acknowledges it to the sender and lets every other client count the revision. `OTClient` advances its revision for a `Neutral` remote operation without surfacing it, and drops a queued operation that rebasing turns into `Neutral` instead of sending it. An in-flight operation can't be dropped, which is why the server has to handle `Neutral` either way.
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
## MODIFIED Requirements

### Requirement: OT WebSocket client
The system SHALL provide `OTClient`, which performs a handshake with the OT server, serializes outgoing operations behind an acknowledgement gate, stamps each outgoing operation with the number of server operations the client has applied, and transforms incoming remote operations against the in-flight operation and every queued local operation, rebasing those local operations against the incoming one, before delivering it.

#### Scenario: Serialized send with ack-gating
- **GIVEN** a local operation has been sent and is awaiting server acknowledgement
- **WHEN** a second operation is queued via `send()`
- **THEN** it remains queued and is not transmitted until the first operation's acknowledgement arrives, at which point the revision counter increments and the next queued operation is sent

#### Scenario: Stamping the base revision
- **GIVEN** the client has applied `n` server operations, counting the handshake revision, acknowledgements and remote operations
- **WHEN** it transmits a local operation
- **THEN** the message carries `rev: n`, so the server transforms it against exactly the operations the client has not seen

#### Scenario: Filtering and transforming incoming remote operations
- **GIVEN** a remote operation message arrives while a local operation is in flight and others are queued
- **WHEN** the message is processed
- **THEN** it is transformed against the in-flight operation and then each queued operation, those local operations are rebased against it, and it is surfaced via `onRemoteOperation`; if the transform reduces it to Neutral, the callback is not invoked; messages originating from the client's own `userId`, or of a non-`Operation` message type, are ignored outright

#### Scenario: Neutral remote operation still advances the revision
- **GIVEN** the server broadcasts a `Neutral` operation, or a remote operation is reduced to `Neutral` by the client's transform
- **WHEN** the message is processed
- **THEN** the client's revision counter advances as for any remote operation, and `onRemoteOperation` is not invoked

#### Scenario: Dropping a queued operation neutralized by rebasing
- **GIVEN** a queued local operation that becomes `Neutral` when rebased against an incoming remote operation
- **WHEN** it reaches the front of the queue
- **THEN** it is dropped instead of being sent, and the next queued operation is considered

#### Scenario: Concurrent clients converge
- **GIVEN** two clients insert text concurrently, at different positions or at the same position, including while one has an operation in flight and another queued
- **WHEN** the server has processed all operations and both clients have received them
- **THEN** both clients and the server hold the same text

#### Scenario: Cleanup
- **GIVEN** an active `CollaborationManager` with a connected `OTClient`
- **WHEN** `destroy()` is called
- **THEN** the WebSocket connection is closed and all model/event-bus listeners are unsubscribed

Implemented in `src/client/OTClient.ts`, `src/client/Message.ts`, `src/client/MessageType.ts`, validated by `src/client/OTClient.spec.ts` and `packages/ot-server/src/convergence.spec.ts`.

**Known limitation**: reconnect/retry on WebSocket disconnect is not implemented (`src/client/OTClient.ts` carries `@todo` markers for offline handling and retries); no test exercises reconnect behavior.

## ADDED Requirements

### Requirement: Explicit transform order
The system SHALL let the caller of `Operation.transform(against, againstIsLater)` state whether `against` is ordered before (default) or after the transformed operation, and SHALL NOT infer that order from revisions. When `against` comes earlier, an Insert at the same text position shifts after it and a value Modify on the same key is kept. When `against` comes later, the Insert keeps its position and the Modify becomes `Neutral`.

#### Scenario: Server rebases an incoming insert at the same position
- **GIVEN** an Insert at position 0 and a history Insert at position 0
- **WHEN** the incoming operation is transformed against the history operation with the default order
- **THEN** it is shifted past the inserted text

#### Scenario: Client keeps a remote insert at the same position
- **GIVEN** a remote Insert at position 0 and an unacknowledged local Insert at position 0
- **WHEN** the remote operation is transformed against the local one with `againstIsLater: true`
- **THEN** its position is unchanged

### Requirement: Insert against insert transforms by position
The system SHALL transform a text Insert against a concurrent text Insert in the same input by comparing their start positions only, and SHALL NOT merge the other Insert's payload into the transformed one. If the other Insert starts earlier, the transformed Insert shifts right by the other payload's length; if it starts later, the transformed Insert is unchanged; if both start at the same position, the order given by `againstIsLater` decides.

#### Scenario: Concurrent insert inside a multi-character insert's range
- **GIVEN** the text `hello`, an Insert of `abc` at position 2 and a concurrent Insert of `Z` at position 3, both based on the same revision
- **WHEN** the `abc` Insert is transformed against the `Z` Insert
- **THEN** it still inserts `abc` at position 2, and applying both yields `heabclZlo`

#### Scenario: Concurrent insert before the transformed insert
- **GIVEN** an Insert of `abc` at position 3 and a concurrent Insert of `Z` at position 1
- **WHEN** the `abc` Insert is transformed against the `Z` Insert
- **THEN** it inserts `abc` at position 4 with its payload unchanged
46 changes: 46 additions & 0 deletions openspec/changes/fix-ot-client-convergence/specs/ot-server/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
## MODIFIED Requirements

### Requirement: Operation transformation against history
The system SHALL apply incoming operations to the per-document `EditorJSModel` via `DocumentManager`, serializing concurrent `process()` calls through an internal promise chain, and transforming any operation whose revision is behind the current history against all operations submitted since that revision. A `Neutral` operation SHALL be stored and SHALL advance the revision without changing the model.

#### Scenario: Sequential same-user operations
- **GIVEN** three consecutive `Insert` operations from the same user with correctly incrementing `rev` values
- **WHEN** each is processed in order
- **THEN** they are applied in order, producing the concatenated result

#### Scenario: Concurrent operations at the same revision
- **GIVEN** two `Insert` operations both submitted at the same revision
- **WHEN** both are processed
- **THEN** they are transformed against each other rather than one being rejected — the second is shifted to insert after the first

#### Scenario: Late-arriving older operation
- **GIVEN** an operation submitted with an older revision arrives after a newer operation has already been processed
- **WHEN** it is processed
- **THEN** it is transformed against all operations in the history with revision greater than or equal to its own, producing a correctly ordered result

#### Scenario: Overlapping process() calls stay ordered
- **GIVEN** multiple `process()` calls are fired without awaiting each other
- **WHEN** they are handled internally
- **THEN** they are serialized via promise chaining (`#operationInProcessing`) so operations still apply in submission order deterministically

#### Scenario: Rejecting an operation ahead of server revision
- **GIVEN** an operation whose `rev` is greater than the server's `#currentRev`
- **WHEN** `#processNextOperation` evaluates it
- **THEN** processing resolves to `null` and the error is logged, which `OTServer` surfaces as closing the socket with code `4400`

#### Scenario: Document initialization
- **GIVEN** a `DocumentManager` created for a new document
- **WHEN** `initializeDocument(data)` is called with the first client's handshake data
- **THEN** the internal `EditorJSModel` is seeded from `data`, and `currentModelState()` returns its serialized form for late-joining clients

#### Scenario: Neutral operation is a no-op that still advances the revision
- **GIVEN** an operation that is `Neutral` on arrival, or that transforming against history reduces to `Neutral` (for example a deletion inside a range another client already deleted)
- **WHEN** it is processed
- **THEN** the model is left unchanged, the operation is stored in the history, the revision advances, and `process()` resolves with it, so `OTServer` broadcasts it, acknowledging it to the sender

#### Scenario: Operations after a Neutral one keep being processed
- **GIVEN** a document whose history contains a `Neutral` operation
- **WHEN** a later operation is processed
- **THEN** it is transformed and applied normally

Implemented in `src/DocumentManager.ts`, validated by `src/DocumentManager.spec.ts`.
21 changes: 21 additions & 0 deletions openspec/changes/fix-ot-client-convergence/tasks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
## 1. Tests

- [ ] 1.1 Add `packages/ot-server/src/convergence.spec.ts`, which drives two `OTClient`s against a real `DocumentManager`, with three failing tests: insert during an in-flight op, same-position inserts, and a queued op rebased against a remote insert
- [ ] 1.2 Add failing `OTClient` specs: sent operations carry the base revision taken from the handshake, acks and remote operations; an incoming operation is transformed against the in-flight one
- [ ] 1.3 Add failing `OperationsTransformer` specs for `againstIsLater` on text-insert ties and same-key value conflicts, and replace the spec pinning "against op has no revision → Neutral"
- [ ] 1.4 Add failing regression specs for concurrent inserts at different positions: an `OperationsTransformer` spec where an Insert of `abc` at 2 is transformed against an Insert of `Z` at 3 and keeps its position and payload, and a `convergence.spec.ts` case where both clients and the server end with `heabclZlo`
- [ ] 1.5 Add failing `DocumentManager` specs for `Neutral`: overlapping deletions from two clients leave the model as the first deletion left it, advance the revision by two and resolve both operations, and a later operation is still applied
- [ ] 1.6 Add failing `OTClient` specs: a `Neutral` remote operation advances the revision without calling `onRemoteOperation`, and a queued operation neutralized by rebasing is dropped instead of sent

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

- [ ] 2.3 In `OperationsTransformer`, transform Insert against Insert by start position only (earlier shifts, later leaves it unchanged, tie follows `againstIsLater`) and stop merging the other payload; base the early-exit check in `#transformAgainstTextOperation` on the start position for Inserts instead of the effective range
- [ ] 2.4 In `DocumentManager`, treat `Neutral` as a no-op: skip the model, store it, advance the revision and resolve with it so `OTServer` broadcasts it
- [ ] 2.5 In `OTClient`, advance the revision for `Neutral` remote operations and drop queued operations that rebasing neutralizes
- [ ] 2.6 Remove the unused `#resolvedOperations`

## 3. Verify

- [ ] 3.1 `yarn build`, `yarn lint:ci`, `yarn test` for `collaboration-manager` and `ot-server`; flip the 1.4–1.6 specs to passing; update `docs/collaboration.md` where it describes the client steps; `openspec validate fix-ot-client-convergence --type change` passes
Loading