From bc3186f3c3f6ae95c64ca9290dac18380b6676c7 Mon Sep 17 00:00:00 2001 From: gohabereg Date: Sat, 17 Oct 2026 19:05:18 +0100 Subject: [PATCH 1/4] docs(openspec): propose fix for OT client/server divergence 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 --- .../fix-ot-client-convergence/proposal.md | 14 + .../specs/collaboration-manager/spec.md | 48 +++ .../fix-ot-client-convergence/tasks.md | 15 + packages/ot-server/src/convergence.spec.ts | 291 ++++++++++++++++++ 4 files changed, 368 insertions(+) create mode 100644 openspec/changes/fix-ot-client-convergence/proposal.md create mode 100644 openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md create mode 100644 openspec/changes/fix-ot-client-convergence/tasks.md create mode 100644 packages/ot-server/src/convergence.spec.ts diff --git a/openspec/changes/fix-ot-client-convergence/proposal.md b/openspec/changes/fix-ot-client-convergence/proposal.md new file mode 100644 index 00000000..1a2384dc --- /dev/null +++ b/openspec/changes/fix-ot-client-convergence/proposal.md @@ -0,0 +1,14 @@ +## Bug + +Two clients editing concurrently end up with different documents, and the server ends up with a third. `packages/ot-server/src/convergence.spec.ts` reproduces it with two `OTClient`s and a real `DocumentManager`. Four defects combine: + +- `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. + +## 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. diff --git a/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md b/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md new file mode 100644 index 00000000..a871bbf1 --- /dev/null +++ b/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md @@ -0,0 +1,48 @@ +## 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: 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 diff --git a/openspec/changes/fix-ot-client-convergence/tasks.md b/openspec/changes/fix-ot-client-convergence/tasks.md new file mode 100644 index 00000000..046334b0 --- /dev/null +++ b/openspec/changes/fix-ot-client-convergence/tasks.md @@ -0,0 +1,15 @@ +## 1. Tests + +- [ ] 1.1 Keep `packages/ot-server/src/convergence.spec.ts` (two clients and a real `DocumentManager`: insert during an in-flight op, same-position inserts, queued op rebased against a remote insert), currently failing +- [ ] 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" + +## 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 +- [ ] 2.3 Remove the unused `#resolvedOperations` + +## 3. Verify + +- [ ] 3.1 `yarn build`, `yarn lint:ci`, `yarn test` for `collaboration-manager` and `ot-server`; update `docs/collaboration.md` where it describes the client steps; `openspec validate fix-ot-client-convergence --type change` passes diff --git a/packages/ot-server/src/convergence.spec.ts b/packages/ot-server/src/convergence.spec.ts new file mode 100644 index 00000000..c7f2015c --- /dev/null +++ b/packages/ot-server/src/convergence.spec.ts @@ -0,0 +1,291 @@ +/* eslint-disable @typescript-eslint/no-magic-numbers */ +import { MessageType, Operation, OperationType, OTClient, type SerializedOperation } from '@editorjs/collaboration-manager'; +import { EditorJSModel } from '@editorjs/model'; +import { createDataKey, type DocumentId, Index } from '@editorjs/sdk'; +import { afterEach, beforeEach, describe, expect, it } from '@jest/globals'; +import { DocumentManager } from './DocumentManager.js'; + +const documentId = 'document' as DocumentId; + +/** + * Serialized document every participant starts from: one paragraph holding "hello" + */ +const initialDocument = { + identifier: documentId, + properties: {}, + blocks: [{ + name: 'paragraph', + data: { + text: { + $t: 't', + value: 'hello', + fragments: [], + }, + }, + }], +}; + +type Listener = (event: { data: string }) => void; + +/** + * In-memory stand-in for the OT server and its sockets. + * Messages are queued and delivered only when the test says so, so interleavings are explicit. + */ +class Hub { + public readonly manager = new DocumentManager(documentId); + + public readonly sockets: HubSocket[] = []; + + public readonly serverInbox: SerializedOperation[] = []; + + /** + * Processes the next operation the server received and broadcasts it to every socket + */ + public async deliverToServer(): Promise { + const payload = this.serverInbox.shift()!; + const processed = await this.manager.process(Operation.from(payload)); + + if (processed === null) { + throw new Error('Server rejected the operation'); + } + + this.sockets.forEach(socket => socket.inbox.push(JSON.stringify({ + type: MessageType.Operation, + payload: processed.serialize(), + }))); + } + + /** + * Delivers every queued server message to the socket of the given client + * @param i - client number + */ + public deliverToClient(i: number): void { + const socket = this.sockets[i]; + + while (socket.inbox.length > 0) { + socket.emit('message', { data: socket.inbox.shift()! }); + } + } +} + +let hub: Hub; + +/** + * WebSocket double routed through the hub + */ +class HubSocket { + public readonly inbox: string[] = []; + + readonly #listeners = new Map>(); + + /** + * Registers the socket in the hub and opens it asynchronously, like a real WebSocket + */ + constructor() { + hub.sockets.push(this); + // eslint-disable-next-line no-undef -- queueMicrotask is available in Node runtime + queueMicrotask(() => this.emit('open', { data: '' })); + } + + /** + * @param type - event type + * @param listener - listener + */ + public addEventListener(type: string, listener: Listener): void { + if (!this.#listeners.has(type)) { + this.#listeners.set(type, new Set()); + } + + this.#listeners.get(type)!.add(listener); + } + + /** + * @param type - event type + * @param listener - listener + */ + public removeEventListener(type: string, listener: Listener): void { + this.#listeners.get(type)?.delete(listener); + } + + /** + * Handshakes are answered immediately; operations are queued for the server + * @param raw - serialized message + */ + public send(raw: string): void { + const message = JSON.parse(raw) as { type: MessageType; payload: unknown }; + + if (message.type === MessageType.Handshake) { + const payload = message.payload as Record; + + // eslint-disable-next-line no-undef -- queueMicrotask is available in Node runtime + queueMicrotask(() => this.emit('message', { + data: JSON.stringify({ + type: MessageType.Handshake, + payload: { ...payload, + rev: hub.manager.currentRev }, + }), + })); + + return; + } + + hub.serverInbox.push(message.payload as SerializedOperation); + } + + /** + * No-op + */ + public close(): void {} + + /** + * @param type - event type + * @param event - event + */ + public emit(type: string, event: { data: string }): void { + Array.from(this.#listeners.get(type) ?? []).forEach(fn => fn(event)); + } +} + +/** + * A collaborating client: its own model plus an OTClient applying remote operations to it + */ +class Participant { + public readonly model: EditorJSModel; + + public readonly client: OTClient; + + /** + * @param userId - participant's user id + */ + constructor(public readonly userId: string) { + this.model = new EditorJSModel(userId, { identifier: documentId }); + this.model.initializeDocument(initialDocument); + this.client = new OTClient('ws://hub.invalid', userId, () => {}, (op) => { + this.model.insertData(op.userId, op.index, op.data.payload as string); + }); + } + + /** + * Inserts text locally and sends the operation, as CollaborationManager would + * @param text - text to insert + * @param at - char position + */ + public async type(text: string, at: number): Promise { + this.model.insertText(this.userId, 0, createDataKey('text'), text, at); + + const index = Index.text([{ blockIndex: 0, + dataKey: createDataKey('text'), + textRange: [at, at], + documentId }]); + + await this.client.send(new Operation(OperationType.Insert, index, { payload: text }, this.userId)); + } + + /** + * Current paragraph text + */ + public get text(): string { + return (this.model.serialized.blocks[0].data.text as { value: string }).value; + } +} + +/** + * Lets queued microtasks (socket open, handshake, sends) settle + */ +async function settle(): Promise { + for (let i = 0; i < 10; i++) { + await Promise.resolve(); + } +} + +/** + * Text of the paragraph in the server's model + */ +function serverText(): string { + return (hub.manager.currentModelState().blocks[0].data.text as { value: string }).value; +} + +describe('OT convergence between two clients and the server', () => { + let OriginalWebSocket: typeof WebSocket; + let x: Participant; + let y: Participant; + + beforeEach(async () => { + OriginalWebSocket = globalThis.WebSocket; + globalThis.WebSocket = HubSocket as unknown as typeof WebSocket; + hub = new Hub(); + hub.manager.initializeDocument(initialDocument); + + x = new Participant('x'); + y = new Participant('y'); + + await x.client.connectDocument(x.model.serialized); + await y.client.connectDocument(y.model.serialized); + await settle(); + }); + + afterEach(() => { + globalThis.WebSocket = OriginalWebSocket; + }); + + it('should converge when a remote insert arrives while the local insert is unacknowledged', async () => { + await x.type('xx', 0); + await y.type('y', 5); + await settle(); + + // Server orders X first, then Y + await hub.deliverToServer(); + await hub.deliverToServer(); + + hub.deliverToClient(0); + hub.deliverToClient(1); + await settle(); + + expect(serverText()).toBe('xxhelloy'); + expect(x.text).toBe('xxhelloy'); + expect(y.text).toBe('xxhelloy'); + }); + + it('should converge when both clients insert at the same position', async () => { + await x.type('x', 0); + await y.type('y', 0); + await settle(); + + await hub.deliverToServer(); + await hub.deliverToServer(); + + hub.deliverToClient(0); + hub.deliverToClient(1); + await settle(); + + expect(x.text).toBe(serverText()); + expect(y.text).toBe(serverText()); + }); + + it('should converge when a queued local insert is sent after a remote insert landed before it', async () => { + // X: first op in flight, second op queued behind it + await x.type('a', 5); + await x.type('b', 6); + // Y inserts at the start, ordered by the server before any of X's operations + await y.type('yy', 0); + await settle(); + + // Y's operation was sent before X's first one reaches the server + hub.serverInbox.unshift(hub.serverInbox.pop()!); + + await hub.deliverToServer(); // Y + hub.deliverToClient(0); // X sees Y while 'a' is in flight and 'b' is queued + await hub.deliverToServer(); // X 'a' + hub.deliverToClient(0); // ack for 'a' → X sends 'b' + await settle(); + await hub.deliverToServer(); // X 'b' + + hub.deliverToClient(0); + hub.deliverToClient(1); + await settle(); + + expect(serverText()).toBe('yyhelloab'); + expect(x.text).toBe('yyhelloab'); + expect(y.text).toBe('yyhelloab'); + }); +}); From 2e69da0605ab8ebbc5709c4650ba16df2be33b52 Mon Sep 17 00:00:00 2001 From: gohabereg Date: Sat, 17 Oct 2026 19:11:38 +0100 Subject: [PATCH 2/4] test(ot-server): mark convergence reproduction as it.failing Keeps CI green until the fix lands; task 1.1 flips them back. Co-Authored-By: Claude Opus 5.5 --- .../fix-ot-client-convergence/tasks.md | 2 +- packages/ot-server/src/convergence.spec.ts | 72 ++++++++++++++----- 2 files changed, 55 insertions(+), 19 deletions(-) diff --git a/openspec/changes/fix-ot-client-convergence/tasks.md b/openspec/changes/fix-ot-client-convergence/tasks.md index 046334b0..20948e90 100644 --- a/openspec/changes/fix-ot-client-convergence/tasks.md +++ b/openspec/changes/fix-ot-client-convergence/tasks.md @@ -1,6 +1,6 @@ ## 1. Tests -- [ ] 1.1 Keep `packages/ot-server/src/convergence.spec.ts` (two clients and a real `DocumentManager`: insert during an in-flight op, same-position inserts, queued op rebased against a remote insert), currently failing +- [ ] 1.1 Flip the three `it.failing` tests in `packages/ot-server/src/convergence.spec.ts` (two clients and a real `DocumentManager`: insert during an in-flight op, same-position inserts, queued op rebased against a remote insert) back to `it` once the fix makes them pass - [ ] 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" diff --git a/packages/ot-server/src/convergence.spec.ts b/packages/ot-server/src/convergence.spec.ts index c7f2015c..7392d840 100644 --- a/packages/ot-server/src/convergence.spec.ts +++ b/packages/ot-server/src/convergence.spec.ts @@ -2,7 +2,6 @@ import { MessageType, Operation, OperationType, OTClient, type SerializedOperation } from '@editorjs/collaboration-manager'; import { EditorJSModel } from '@editorjs/model'; import { createDataKey, type DocumentId, Index } from '@editorjs/sdk'; -import { afterEach, beforeEach, describe, expect, it } from '@jest/globals'; import { DocumentManager } from './DocumentManager.js'; const documentId = 'document' as DocumentId; @@ -25,7 +24,45 @@ const initialDocument = { }], }; -type Listener = (event: { data: string }) => void; +/** + * Event a socket delivers to its listeners + */ +interface SocketMessage { + /** + * Serialized message + */ + data: string; +} + +/** + * Message envelope exchanged over the socket + */ +interface Envelope { + /** + * Message type + */ + type: MessageType; + + /** + * Message body + */ + payload: unknown; +} + +/** + * Serialized text node of the paragraph + */ +interface TextValue { + /** + * Text content + */ + value: string; +} + +/** + * Callback subscribed to socket events + */ +type Listener = (event: SocketMessage) => void; /** * In-memory stand-in for the OT server and its sockets. @@ -83,13 +120,13 @@ class HubSocket { */ constructor() { hub.sockets.push(this); - // eslint-disable-next-line no-undef -- queueMicrotask is available in Node runtime + queueMicrotask(() => this.emit('open', { data: '' })); } /** - * @param type - event type - * @param listener - listener + * @param type - socket event name, e.g. 'open' or 'message' + * @param listener - callback to subscribe */ public addEventListener(type: string, listener: Listener): void { if (!this.#listeners.has(type)) { @@ -100,8 +137,8 @@ class HubSocket { } /** - * @param type - event type - * @param listener - listener + * @param type - socket event name, e.g. 'open' or 'message' + * @param listener - callback to unsubscribe */ public removeEventListener(type: string, listener: Listener): void { this.#listeners.get(type)?.delete(listener); @@ -112,12 +149,11 @@ class HubSocket { * @param raw - serialized message */ public send(raw: string): void { - const message = JSON.parse(raw) as { type: MessageType; payload: unknown }; + const message = JSON.parse(raw) as Envelope; if (message.type === MessageType.Handshake) { const payload = message.payload as Record; - // eslint-disable-next-line no-undef -- queueMicrotask is available in Node runtime queueMicrotask(() => this.emit('message', { data: JSON.stringify({ type: MessageType.Handshake, @@ -138,10 +174,10 @@ class HubSocket { public close(): void {} /** - * @param type - event type - * @param event - event + * @param type - socket event name to dispatch + * @param event - payload handed to every listener */ - public emit(type: string, event: { data: string }): void { + public emit(type: string, event: SocketMessage): void { Array.from(this.#listeners.get(type) ?? []).forEach(fn => fn(event)); } } @@ -155,7 +191,7 @@ class Participant { public readonly client: OTClient; /** - * @param userId - participant's user id + * @param userId - id the participant edits and sends operations as */ constructor(public readonly userId: string) { this.model = new EditorJSModel(userId, { identifier: documentId }); @@ -185,7 +221,7 @@ class Participant { * Current paragraph text */ public get text(): string { - return (this.model.serialized.blocks[0].data.text as { value: string }).value; + return (this.model.serialized.blocks[0].data.text as TextValue).value; } } @@ -202,7 +238,7 @@ async function settle(): Promise { * Text of the paragraph in the server's model */ function serverText(): string { - return (hub.manager.currentModelState().blocks[0].data.text as { value: string }).value; + return (hub.manager.currentModelState().blocks[0].data.text as TextValue).value; } describe('OT convergence between two clients and the server', () => { @@ -228,7 +264,7 @@ describe('OT convergence between two clients and the server', () => { globalThis.WebSocket = OriginalWebSocket; }); - it('should converge when a remote insert arrives while the local insert is unacknowledged', async () => { + it.failing('should converge when a remote insert arrives while the local insert is unacknowledged', async () => { await x.type('xx', 0); await y.type('y', 5); await settle(); @@ -246,7 +282,7 @@ describe('OT convergence between two clients and the server', () => { expect(y.text).toBe('xxhelloy'); }); - it('should converge when both clients insert at the same position', async () => { + it.failing('should converge when both clients insert at the same position', async () => { await x.type('x', 0); await y.type('y', 0); await settle(); @@ -262,7 +298,7 @@ describe('OT convergence between two clients and the server', () => { expect(y.text).toBe(serverText()); }); - it('should converge when a queued local insert is sent after a remote insert landed before it', async () => { + it.failing('should converge when a queued local insert is sent after a remote insert landed before it', async () => { // X: first op in flight, second op queued behind it await x.type('a', 5); await x.type('b', 6); From 9caf9e8c971b7f3f1eff8d303a1e7cf8c5e9d5a1 Mon Sep 17 00:00:00 2001 From: gohabereg Date: Wed, 11 Nov 2026 17:41:37 +0000 Subject: [PATCH 3/4] docs(openspec): cover insert-vs-insert merge and Neutral on the server 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 Claude-Session: https://claude.ai/code/session_01TffpCm82NH5xXR1yeBew6Q --- .../fix-ot-client-convergence/proposal.md | 6 ++- .../specs/collaboration-manager/spec.md | 23 ++++++++++ .../specs/ot-server/spec.md | 46 +++++++++++++++++++ .../fix-ot-client-convergence/tasks.md | 10 +++- 4 files changed, 82 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/fix-ot-client-convergence/specs/ot-server/spec.md diff --git a/openspec/changes/fix-ot-client-convergence/proposal.md b/openspec/changes/fix-ot-client-convergence/proposal.md index 1a2384dc..359c8c75 100644 --- a/openspec/changes/fix-ot-client-convergence/proposal.md +++ b/openspec/changes/fix-ot-client-convergence/proposal.md @@ -1,14 +1,18 @@ ## Bug -Two clients editing concurrently end up with different documents, and the server ends up with a third. `packages/ot-server/src/convergence.spec.ts` reproduces it with two `OTClient`s and a real `DocumentManager`. Four defects combine: +Two clients editing concurrently end up with different documents, and the server ends up with a third. `packages/ot-server/src/convergence.spec.ts` reproduces it with two `OTClient`s and a real `DocumentManager`. 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. diff --git a/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md b/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md index a871bbf1..4b00b18c 100644 --- a/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md +++ b/openspec/changes/fix-ot-client-convergence/specs/collaboration-manager/spec.md @@ -18,6 +18,16 @@ The system SHALL provide `OTClient`, which performs a handshake with the OT serv - **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 @@ -46,3 +56,16 @@ The system SHALL let the caller of `Operation.transform(against, againstIsLater) - **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 diff --git a/openspec/changes/fix-ot-client-convergence/specs/ot-server/spec.md b/openspec/changes/fix-ot-client-convergence/specs/ot-server/spec.md new file mode 100644 index 00000000..e99b0244 --- /dev/null +++ b/openspec/changes/fix-ot-client-convergence/specs/ot-server/spec.md @@ -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`. diff --git a/openspec/changes/fix-ot-client-convergence/tasks.md b/openspec/changes/fix-ot-client-convergence/tasks.md index 20948e90..8258941b 100644 --- a/openspec/changes/fix-ot-client-convergence/tasks.md +++ b/openspec/changes/fix-ot-client-convergence/tasks.md @@ -3,13 +3,19 @@ - [ ] 1.1 Flip the three `it.failing` tests in `packages/ot-server/src/convergence.spec.ts` (two clients and a real `DocumentManager`: insert during an in-flight op, same-position inserts, queued op rebased against a remote insert) back to `it` once the fix makes them pass - [ ] 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 - [ ] 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 -- [ ] 2.3 Remove the unused `#resolvedOperations` +- [ ] 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`; update `docs/collaboration.md` where it describes the client steps; `openspec validate fix-ot-client-convergence --type change` passes +- [ ] 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 From c524be4e9a8fa7886a24a39748c8ce665ce635ab Mon Sep 17 00:00:00 2001 From: gohabereg Date: Wed, 11 Nov 2026 17:45:01 +0000 Subject: [PATCH 4/4] chore(ot-server): drop convergence reproduction from the proposal PR 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 Claude-Session: https://claude.ai/code/session_01TffpCm82NH5xXR1yeBew6Q --- .../fix-ot-client-convergence/proposal.md | 2 +- .../fix-ot-client-convergence/tasks.md | 2 +- packages/ot-server/src/convergence.spec.ts | 327 ------------------ 3 files changed, 2 insertions(+), 329 deletions(-) delete mode 100644 packages/ot-server/src/convergence.spec.ts diff --git a/openspec/changes/fix-ot-client-convergence/proposal.md b/openspec/changes/fix-ot-client-convergence/proposal.md index 359c8c75..e7e94ac5 100644 --- a/openspec/changes/fix-ot-client-convergence/proposal.md +++ b/openspec/changes/fix-ot-client-convergence/proposal.md @@ -1,6 +1,6 @@ ## Bug -Two clients editing concurrently end up with different documents, and the server ends up with a third. `packages/ot-server/src/convergence.spec.ts` reproduces it with two `OTClient`s and a real `DocumentManager`. Four defects combine, and two more surface once the first four are fixed: +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. diff --git a/openspec/changes/fix-ot-client-convergence/tasks.md b/openspec/changes/fix-ot-client-convergence/tasks.md index 8258941b..48432123 100644 --- a/openspec/changes/fix-ot-client-convergence/tasks.md +++ b/openspec/changes/fix-ot-client-convergence/tasks.md @@ -1,6 +1,6 @@ ## 1. Tests -- [ ] 1.1 Flip the three `it.failing` tests in `packages/ot-server/src/convergence.spec.ts` (two clients and a real `DocumentManager`: insert during an in-flight op, same-position inserts, queued op rebased against a remote insert) back to `it` once the fix makes them pass +- [ ] 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` diff --git a/packages/ot-server/src/convergence.spec.ts b/packages/ot-server/src/convergence.spec.ts deleted file mode 100644 index 7392d840..00000000 --- a/packages/ot-server/src/convergence.spec.ts +++ /dev/null @@ -1,327 +0,0 @@ -/* eslint-disable @typescript-eslint/no-magic-numbers */ -import { MessageType, Operation, OperationType, OTClient, type SerializedOperation } from '@editorjs/collaboration-manager'; -import { EditorJSModel } from '@editorjs/model'; -import { createDataKey, type DocumentId, Index } from '@editorjs/sdk'; -import { DocumentManager } from './DocumentManager.js'; - -const documentId = 'document' as DocumentId; - -/** - * Serialized document every participant starts from: one paragraph holding "hello" - */ -const initialDocument = { - identifier: documentId, - properties: {}, - blocks: [{ - name: 'paragraph', - data: { - text: { - $t: 't', - value: 'hello', - fragments: [], - }, - }, - }], -}; - -/** - * Event a socket delivers to its listeners - */ -interface SocketMessage { - /** - * Serialized message - */ - data: string; -} - -/** - * Message envelope exchanged over the socket - */ -interface Envelope { - /** - * Message type - */ - type: MessageType; - - /** - * Message body - */ - payload: unknown; -} - -/** - * Serialized text node of the paragraph - */ -interface TextValue { - /** - * Text content - */ - value: string; -} - -/** - * Callback subscribed to socket events - */ -type Listener = (event: SocketMessage) => void; - -/** - * In-memory stand-in for the OT server and its sockets. - * Messages are queued and delivered only when the test says so, so interleavings are explicit. - */ -class Hub { - public readonly manager = new DocumentManager(documentId); - - public readonly sockets: HubSocket[] = []; - - public readonly serverInbox: SerializedOperation[] = []; - - /** - * Processes the next operation the server received and broadcasts it to every socket - */ - public async deliverToServer(): Promise { - const payload = this.serverInbox.shift()!; - const processed = await this.manager.process(Operation.from(payload)); - - if (processed === null) { - throw new Error('Server rejected the operation'); - } - - this.sockets.forEach(socket => socket.inbox.push(JSON.stringify({ - type: MessageType.Operation, - payload: processed.serialize(), - }))); - } - - /** - * Delivers every queued server message to the socket of the given client - * @param i - client number - */ - public deliverToClient(i: number): void { - const socket = this.sockets[i]; - - while (socket.inbox.length > 0) { - socket.emit('message', { data: socket.inbox.shift()! }); - } - } -} - -let hub: Hub; - -/** - * WebSocket double routed through the hub - */ -class HubSocket { - public readonly inbox: string[] = []; - - readonly #listeners = new Map>(); - - /** - * Registers the socket in the hub and opens it asynchronously, like a real WebSocket - */ - constructor() { - hub.sockets.push(this); - - queueMicrotask(() => this.emit('open', { data: '' })); - } - - /** - * @param type - socket event name, e.g. 'open' or 'message' - * @param listener - callback to subscribe - */ - public addEventListener(type: string, listener: Listener): void { - if (!this.#listeners.has(type)) { - this.#listeners.set(type, new Set()); - } - - this.#listeners.get(type)!.add(listener); - } - - /** - * @param type - socket event name, e.g. 'open' or 'message' - * @param listener - callback to unsubscribe - */ - public removeEventListener(type: string, listener: Listener): void { - this.#listeners.get(type)?.delete(listener); - } - - /** - * Handshakes are answered immediately; operations are queued for the server - * @param raw - serialized message - */ - public send(raw: string): void { - const message = JSON.parse(raw) as Envelope; - - if (message.type === MessageType.Handshake) { - const payload = message.payload as Record; - - queueMicrotask(() => this.emit('message', { - data: JSON.stringify({ - type: MessageType.Handshake, - payload: { ...payload, - rev: hub.manager.currentRev }, - }), - })); - - return; - } - - hub.serverInbox.push(message.payload as SerializedOperation); - } - - /** - * No-op - */ - public close(): void {} - - /** - * @param type - socket event name to dispatch - * @param event - payload handed to every listener - */ - public emit(type: string, event: SocketMessage): void { - Array.from(this.#listeners.get(type) ?? []).forEach(fn => fn(event)); - } -} - -/** - * A collaborating client: its own model plus an OTClient applying remote operations to it - */ -class Participant { - public readonly model: EditorJSModel; - - public readonly client: OTClient; - - /** - * @param userId - id the participant edits and sends operations as - */ - constructor(public readonly userId: string) { - this.model = new EditorJSModel(userId, { identifier: documentId }); - this.model.initializeDocument(initialDocument); - this.client = new OTClient('ws://hub.invalid', userId, () => {}, (op) => { - this.model.insertData(op.userId, op.index, op.data.payload as string); - }); - } - - /** - * Inserts text locally and sends the operation, as CollaborationManager would - * @param text - text to insert - * @param at - char position - */ - public async type(text: string, at: number): Promise { - this.model.insertText(this.userId, 0, createDataKey('text'), text, at); - - const index = Index.text([{ blockIndex: 0, - dataKey: createDataKey('text'), - textRange: [at, at], - documentId }]); - - await this.client.send(new Operation(OperationType.Insert, index, { payload: text }, this.userId)); - } - - /** - * Current paragraph text - */ - public get text(): string { - return (this.model.serialized.blocks[0].data.text as TextValue).value; - } -} - -/** - * Lets queued microtasks (socket open, handshake, sends) settle - */ -async function settle(): Promise { - for (let i = 0; i < 10; i++) { - await Promise.resolve(); - } -} - -/** - * Text of the paragraph in the server's model - */ -function serverText(): string { - return (hub.manager.currentModelState().blocks[0].data.text as TextValue).value; -} - -describe('OT convergence between two clients and the server', () => { - let OriginalWebSocket: typeof WebSocket; - let x: Participant; - let y: Participant; - - beforeEach(async () => { - OriginalWebSocket = globalThis.WebSocket; - globalThis.WebSocket = HubSocket as unknown as typeof WebSocket; - hub = new Hub(); - hub.manager.initializeDocument(initialDocument); - - x = new Participant('x'); - y = new Participant('y'); - - await x.client.connectDocument(x.model.serialized); - await y.client.connectDocument(y.model.serialized); - await settle(); - }); - - afterEach(() => { - globalThis.WebSocket = OriginalWebSocket; - }); - - it.failing('should converge when a remote insert arrives while the local insert is unacknowledged', async () => { - await x.type('xx', 0); - await y.type('y', 5); - await settle(); - - // Server orders X first, then Y - await hub.deliverToServer(); - await hub.deliverToServer(); - - hub.deliverToClient(0); - hub.deliverToClient(1); - await settle(); - - expect(serverText()).toBe('xxhelloy'); - expect(x.text).toBe('xxhelloy'); - expect(y.text).toBe('xxhelloy'); - }); - - it.failing('should converge when both clients insert at the same position', async () => { - await x.type('x', 0); - await y.type('y', 0); - await settle(); - - await hub.deliverToServer(); - await hub.deliverToServer(); - - hub.deliverToClient(0); - hub.deliverToClient(1); - await settle(); - - expect(x.text).toBe(serverText()); - expect(y.text).toBe(serverText()); - }); - - it.failing('should converge when a queued local insert is sent after a remote insert landed before it', async () => { - // X: first op in flight, second op queued behind it - await x.type('a', 5); - await x.type('b', 6); - // Y inserts at the start, ordered by the server before any of X's operations - await y.type('yy', 0); - await settle(); - - // Y's operation was sent before X's first one reaches the server - hub.serverInbox.unshift(hub.serverInbox.pop()!); - - await hub.deliverToServer(); // Y - hub.deliverToClient(0); // X sees Y while 'a' is in flight and 'b' is queued - await hub.deliverToServer(); // X 'a' - hub.deliverToClient(0); // ack for 'a' → X sends 'b' - await settle(); - await hub.deliverToServer(); // X 'b' - - hub.deliverToClient(0); - hub.deliverToClient(1); - await settle(); - - expect(serverText()).toBe('yyhelloab'); - expect(x.text).toBe('yyhelloab'); - expect(y.text).toBe('yyhelloab'); - }); -});