@epicenter/sync 0.1.0 → 0.3.0

package/src/protocol.test.ts

@@ -1,212 +1,29 @@
 /**
  * Protocol Unit Tests
  *
- * Tests y-websocket-compatible protocol helpers used by the server sync endpoint.
- * Coverage focuses on message encoding/decoding, compatibility with y-protocols,
- * and end-to-end synchronization behavior under common and edge conditions.
+ * Tests the Yjs sync protocol helpers used by the server sync endpoint:
+ * the frame encoders (`encodeSyncStep1` / `encodeSyncUpdate`), the
+ * dispatcher (`handleSyncPayload`), and end-to-end synchronization.
  *
- * Key behaviors:
- * - Sync and awareness frames encode/decode with expected wire formats.
- * - Handshake and incremental updates converge document state across peers.
+ * A binary frame is `[sync sub-type varint][payload]`; `readFrame` below
+ * is the test-side decoder (production decodes inline at the transport).
  */
 
 import { describe, expect, test } from 'bun:test';
-import {
-	Awareness,
-	applyAwarenessUpdate,
-	encodeAwarenessUpdate,
-} from 'y-protocols/awareness';
+import * as decoding from 'lib0/decoding';
 import * as Y from 'yjs';
-import { RpcError } from './rpc-errors';
 import {
-	decodeMessageType,
-	decodeRpcMessage,
-	decodeSyncMessage,
-	decodeSyncStatus,
-	encodeAwareness,
-	encodeAwarenessStates,
-	encodeQueryAwareness,
-	encodeRpcRequest,
-	encodeRpcResponse,
-	encodeSyncStatus,
 	encodeSyncStep1,
-	encodeSyncStep2,
 	encodeSyncUpdate,
 	handleSyncPayload,
-	MESSAGE_TYPE,
-	RPC_TYPE,
 	SYNC_MESSAGE_TYPE,
+	type SyncMessageType,
 } from './protocol';
 
 // ============================================================================
-// MESSAGE_TYPE Constants
-// ============================================================================
-
-describe('MESSAGE_TYPE constants', () => {
-	test('match y-websocket protocol values', () => {
-		// These values are defined by y-websocket and must not change
-		expect(MESSAGE_TYPE.SYNC).toBe(0);
-		expect(MESSAGE_TYPE.AWARENESS).toBe(1);
-		expect(MESSAGE_TYPE.AUTH).toBe(2);
-		expect(MESSAGE_TYPE.QUERY_AWARENESS).toBe(3);
-	});
-
-	test('SYNC_STATUS is 100 (custom extension for version tracking)', () => {
-		expect(MESSAGE_TYPE.SYNC_STATUS).toBe(100);
-	});
-});
-
-// ============================================================================
-// SYNC_STATUS Encode/Decode Tests
-// ============================================================================
-
-describe('SYNC_STATUS encode/decode', () => {
-	test('encodeSyncStatus produces correct message type', () => {
-		const message = encodeSyncStatus(42);
-		expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.SYNC_STATUS);
-	});
-
-	test('round-trip: encode then decode preserves localVersion', () => {
-		const version = 12345;
-		const encoded = encodeSyncStatus(version);
-		const decoded = decodeSyncStatus(encoded);
-		expect(decoded).toBe(version);
-	});
-
-	test('round-trip with version 0', () => {
-		const encoded = encodeSyncStatus(0);
-		const decoded = decodeSyncStatus(encoded);
-		expect(decoded).toBe(0);
-	});
-
-	test('round-trip with large version number', () => {
-		const version = 1_000_000;
-		const encoded = encodeSyncStatus(version);
-		const decoded = decodeSyncStatus(encoded);
-		expect(decoded).toBe(version);
-	});
-
-	test('decodeSyncStatus throws on non-SYNC_STATUS message', () => {
-		const doc = createDoc();
-		const syncMessage = encodeSyncStep1({ doc });
-		expect(() => decodeSyncStatus(syncMessage)).toThrow(
-			'Expected SYNC_STATUS message (100), got 0',
-		);
-	});
-});
-
-// ============================================================================
-// RPC Encode/Decode Tests
+// SYNC_MESSAGE_TYPE Constants
 // ============================================================================
 
-describe('RPC protocol', () => {
-	test('MESSAGE_TYPE.RPC is 101', () => {
-		expect(MESSAGE_TYPE.RPC).toBe(101);
-	});
-
-	test('RPC_TYPE constants', () => {
-		expect(RPC_TYPE.REQUEST).toBe(0);
-		expect(RPC_TYPE.RESPONSE).toBe(1);
-	});
-
-	test('round-trip: encode/decode RPC REQUEST', () => {
-		const encoded = encodeRpcRequest({
-			requestId: 42,
-			targetClientId: 100,
-			requesterClientId: 200,
-			action: 'tabs.close',
-			input: { tabIds: [1, 2, 3] },
-		});
-
-		expect(decodeMessageType(encoded)).toBe(MESSAGE_TYPE.RPC);
-
-		const decoded = decodeRpcMessage(encoded);
-		expect(decoded.type).toBe('request');
-		if (decoded.type === 'request') {
-			expect(decoded.requestId).toBe(42);
-			expect(decoded.targetClientId).toBe(100);
-			expect(decoded.requesterClientId).toBe(200);
-			expect(decoded.action).toBe('tabs.close');
-			expect(decoded.input).toEqual({ tabIds: [1, 2, 3] });
-		}
-	});
-
-	test('round-trip: encode/decode RPC RESPONSE', () => {
-		const encoded = encodeRpcResponse({
-			requestId: 42,
-			requesterClientId: 200,
-			result: { data: { closedCount: 3 }, error: null },
-		});
-
-		expect(decodeMessageType(encoded)).toBe(MESSAGE_TYPE.RPC);
-
-		const decoded = decodeRpcMessage(encoded);
-		expect(decoded.type).toBe('response');
-		if (decoded.type === 'response') {
-			expect(decoded.requestId).toBe(42);
-			expect(decoded.requesterClientId).toBe(200);
-			expect(decoded.result).toEqual({ data: { closedCount: 3 }, error: null });
-		}
-	});
-
-	test('REQUEST with null input', () => {
-		const encoded = encodeRpcRequest({
-			requestId: 0,
-			targetClientId: 50,
-			requesterClientId: 60,
-			action: 'devices.list',
-		});
-
-		const decoded = decodeRpcMessage(encoded);
-		expect(decoded.type).toBe('request');
-		if (decoded.type === 'request') {
-			expect(decoded.input).toBeNull();
-		}
-	});
-
-	test('RESPONSE with error', () => {
-		const encoded = encodeRpcResponse({
-			requestId: 7,
-			requesterClientId: 300,
-			result: RpcError.PeerOffline(),
-		});
-
-		const decoded = decodeRpcMessage(encoded);
-		expect(decoded.type).toBe('response');
-		if (decoded.type === 'response') {
-			expect(decoded.result.data).toBeNull();
-			expect(decoded.result.error).toMatchObject({
-				name: 'PeerOffline',
-				message: 'Target peer is not connected',
-			});
-		}
-	});
-
-	test('decodeRpcMessage discriminates REQUEST vs RESPONSE', () => {
-		const request = encodeRpcRequest({
-			requestId: 1,
-			targetClientId: 10,
-			requesterClientId: 20,
-			action: 'test',
-		});
-		const response = encodeRpcResponse({
-			requestId: 1,
-			requesterClientId: 20,
-			result: { data: 'ok', error: null },
-		});
-
-		expect(decodeRpcMessage(request).type).toBe('request');
-		expect(decodeRpcMessage(response).type).toBe('response');
-	});
-
-	test('decodeRpcMessage throws on non-RPC message', () => {
-		const syncMessage = encodeSyncStep1({ doc: new Y.Doc() });
-		expect(() => decodeRpcMessage(syncMessage)).toThrow(
-			'Expected RPC message (101), got 0',
-		);
-	});
-});
-
 describe('SYNC_MESSAGE_TYPE constants', () => {
 	test('have expected numeric values', () => {
 		expect(SYNC_MESSAGE_TYPE.STEP1).toBe(0);
@@ -216,416 +33,124 @@ describe('SYNC_MESSAGE_TYPE constants', () => {
 });
 
 // ============================================================================
-// MESSAGE_SYNC Tests
+// Frame Encoders
 // ============================================================================
 
-describe('MESSAGE_SYNC', () => {
-	describe('encodeSyncStep1', () => {
-		test('encodes empty document', () => {
-			const doc = createDoc();
-			const message = encodeSyncStep1({ doc });
-			const decoded = decodeSyncMessage(message);
-
-			expect(decoded.type).toBe('step1');
-		});
-
-		test('encodes document with content', () => {
-			const doc = createDoc((d) => {
-				d.getMap('data').set('key', 'value');
-			});
-			const message = encodeSyncStep1({ doc });
-			const decoded = decodeSyncMessage(message);
-
-			expect(decoded.type).toBe('step1');
-		});
-
-		test('state vector changes after modification', () => {
-			const doc = createDoc();
-			const message1 = encodeSyncStep1({ doc });
-
-			doc.getMap('data').set('key', 'value');
-			const message2 = encodeSyncStep1({ doc });
-
-			// Different state vectors = different messages
-			expect(message1).not.toEqual(message2);
-		});
-
-		test('can be decoded by y-protocols', () => {
-			const doc = createDoc((d) => {
-				d.getMap('test').set('foo', 'bar');
-			});
-			const message = encodeSyncStep1({ doc });
-			const decoded = decodeSyncMessage(message);
-
-			expect(decoded.type).toBe('step1');
-			if (decoded.type === 'step1') {
-				expect(decoded.stateVector).toBeInstanceOf(Uint8Array);
-				expect(decoded.stateVector.length).toBeGreaterThan(0);
-			}
-		});
-	});
-
-	describe('encodeSyncStep2', () => {
-		test('encodes document diff', () => {
-			const doc = createDoc((d) => {
-				d.getMap('data').set('key', 'value');
-			});
-			const message = encodeSyncStep2({ doc });
-			const decoded = decodeSyncMessage(message);
-
-			expect(decoded.type).toBe('step2');
-		});
-
-		test('contains update data', () => {
-			const doc = createDoc((d) => {
-				d.getMap('data').set('key', 'value');
-			});
-			const message = encodeSyncStep2({ doc });
-			const decoded = decodeSyncMessage(message);
+describe('encodeSyncStep1', () => {
+	test('produces a STEP1 frame carrying the document state vector', () => {
+		const doc = createDoc((d) => d.getMap('test').set('foo', 'bar'));
+		const { syncType, payload } = readFrame(encodeSyncStep1({ doc }));
 
-			expect(decoded.type).toBe('step2');
-			if (decoded.type === 'step2') {
-				expect(decoded.update.length).toBeGreaterThan(0);
-			}
-		});
+		expect(syncType).toBe(SYNC_MESSAGE_TYPE.STEP1);
+		expect(payload).toEqual(Y.encodeStateVector(doc));
 	});
+});
 
-	describe('encodeSyncUpdate', () => {
-		test('encodes incremental update', () => {
-			const doc = createDoc();
-			let capturedUpdate: Uint8Array | null = null;
-
-			doc.on('updateV2', (update: Uint8Array) => {
-				capturedUpdate = update;
-			});
-			doc.getMap('data').set('key', 'value');
-
-			expect(capturedUpdate).not.toBeNull();
-			if (!capturedUpdate) {
-				throw new Error('Expected captured update after document mutation');
-			}
-			const message = encodeSyncUpdate({ update: capturedUpdate });
-			const decoded = decodeSyncMessage(message);
-
-			expect(decoded.type).toBe('update');
+describe('encodeSyncUpdate', () => {
+	test('produces an UPDATE frame carrying the update bytes', () => {
+		const doc = createDoc();
+		let captured: Uint8Array | null = null;
+		doc.on('updateV2', (update: Uint8Array) => {
+			captured = update;
 		});
+		doc.getMap('data').set('key', 'value');
 
-		test('handles empty update', () => {
-			const message = encodeSyncUpdate({ update: new Uint8Array(0) });
+		if (!captured) {
+			throw new Error('Expected a captured update after document mutation');
+		}
+		const { syncType, payload } = readFrame(
+			encodeSyncUpdate({ update: captured }),
+		);
 
-			expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.SYNC);
-		});
+		expect(syncType).toBe(SYNC_MESSAGE_TYPE.UPDATE);
+		expect(payload).toEqual(captured);
 	});
 
-	describe('handleSyncPayload', () => {
-		test('responds to sync step 1 with sync step 2', () => {
-			const serverDoc = createDoc((d) => {
-				d.getMap('data').set('server', 'content');
-			});
-			const clientDoc = createDoc();
-
-			const response = handleSyncPayload({
-				syncType: SYNC_MESSAGE_TYPE.STEP1,
-				payload: Y.encodeStateVector(clientDoc),
-				doc: serverDoc,
-				origin: 'test-client',
-			});
-
-			expect(response).not.toBeNull();
-			if (!response) {
-				throw new Error(
-					'Expected sync step 2 response for sync step 1 payload',
-				);
-			}
-			const decoded = decodeSyncMessage(response);
-			expect(decoded.type).toBe('step2');
-		});
-
-		test('returns null for sync step 2 (no response needed)', () => {
-			const serverDoc = createDoc();
-			const clientDoc = createDoc((d) => {
-				d.getMap('data').set('client', 'content');
-			});
-
-			const response = handleSyncPayload({
-				syncType: SYNC_MESSAGE_TYPE.STEP2,
-				payload: Y.encodeStateAsUpdateV2(clientDoc),
-				doc: serverDoc,
-				origin: 'test-client',
-			});
-
-			expect(response).toBeNull();
-		});
-
-		test('returns null for sync update (no response needed)', () => {
-			const serverDoc = createDoc();
-			const updateV2 = Y.encodeStateAsUpdateV2(
-				createDoc((d) => d.getMap('data').set('key', 'value')),
-			);
-
-			const response = handleSyncPayload({
-				syncType: SYNC_MESSAGE_TYPE.UPDATE,
-				payload: updateV2,
-				doc: serverDoc,
-				origin: 'test-client',
-			});
-
-			expect(response).toBeNull();
-		});
-
-		test('applies update to document', () => {
-			const serverDoc = createDoc();
-			const clientDoc = createDoc((d) => {
-				d.getMap('data').set('key', 'value');
-			});
-
-			handleSyncPayload({
-				syncType: SYNC_MESSAGE_TYPE.UPDATE,
-				payload: Y.encodeStateAsUpdateV2(clientDoc),
-				doc: serverDoc,
-				origin: 'test-client',
-			});
+	test('handles an empty update', () => {
+		const { syncType, payload } = readFrame(
+			encodeSyncUpdate({ update: new Uint8Array(0) }),
+		);
 
-			expect(serverDoc.getMap('data').get('key')).toBe('value');
-		});
+		expect(syncType).toBe(SYNC_MESSAGE_TYPE.UPDATE);
+		expect(payload.length).toBe(0);
 	});
 });
 
 // ============================================================================
-// MESSAGE_AWARENESS Tests
+// handleSyncPayload
 // ============================================================================
 
-describe('MESSAGE_AWARENESS', () => {
-	describe('encodeAwarenessStates', () => {
-		test('encodes single client state', () => {
-			const doc = createDoc();
-			const awareness = new Awareness(doc);
-			awareness.setLocalState({ name: 'User 1', cursor: { x: 10, y: 20 } });
-
-			const message = encodeAwarenessStates({
-				awareness,
-				clients: [awareness.clientID],
-			});
-
-			expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.AWARENESS);
-		});
-
-		test('encodes complex nested state', () => {
-			const doc = createDoc();
-			const awareness = new Awareness(doc);
-			awareness.setLocalState({
-				user: { name: 'Test', color: '#ff0000' },
-				cursor: { position: { x: 100, y: 200 }, selection: [0, 10] },
-				metadata: { version: 1, flags: ['active'] },
-			});
-
-			const message = encodeAwarenessStates({
-				awareness,
-				clients: [awareness.clientID],
-			});
-
-			expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.AWARENESS);
-		});
-
-		test('handles special characters in state', () => {
-			const doc = createDoc();
-			const awareness = new Awareness(doc);
-			awareness.setLocalState({
-				name: 'User with "quotes" and \'apostrophes\'',
-				emoji: '🎉🚀',
-				newlines: 'line1\nline2',
-			});
-
-			const message = encodeAwarenessStates({
-				awareness,
-				clients: [awareness.clientID],
-			});
-
-			expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.AWARENESS);
-		});
-
-		test('handles large awareness state', () => {
-			const doc = createDoc();
-			const awareness = new Awareness(doc);
-			awareness.setLocalState({
-				largeArray: Array(1000).fill('item'),
-				largeString: 'x'.repeat(10000),
-			});
-
-			const message = encodeAwarenessStates({
-				awareness,
-				clients: [awareness.clientID],
-			});
-
-			expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.AWARENESS);
-			expect(message.length).toBeGreaterThan(10000);
-		});
-	});
-
-	describe('encodeAwareness', () => {
-		test('wraps raw awareness update', () => {
-			const doc = createDoc();
-			const awareness = new Awareness(doc);
-			awareness.setLocalState({ name: 'Test' });
-
-			const update = encodeAwarenessUpdate(awareness, [awareness.clientID]);
-			const message = encodeAwareness({ update });
-
-			expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.AWARENESS);
-		});
-	});
-
-	describe('awareness protocol compatibility', () => {
-		test('encoded awareness can be applied to another instance', () => {
-			const doc1 = createDoc();
-			const awareness1 = new Awareness(doc1);
-			awareness1.setLocalState({ name: 'User 1' });
-
-			const doc2 = createDoc();
-			const awareness2 = new Awareness(doc2);
-
-			// Encode from awareness1
-			const update = encodeAwarenessUpdate(awareness1, [awareness1.clientID]);
-
-			// Apply to awareness2
-			applyAwarenessUpdate(awareness2, update, 'remote');
-
-			// awareness2 should have awareness1's state
-			const states = awareness2.getStates();
-			expect(states.has(awareness1.clientID)).toBe(true);
-			expect(states.get(awareness1.clientID)).toEqual({ name: 'User 1' });
+describe('handleSyncPayload', () => {
+	test('responds to STEP1 with a STEP2 frame the client can apply', () => {
+		const serverDoc = createDoc((d) => {
+			d.getMap('data').set('server', 'content');
 		});
+		const clientDoc = createDoc();
 
-		test('null state removes client (disconnect)', () => {
-			const doc = createDoc();
-			const awareness = new Awareness(doc);
-			awareness.setLocalState({ name: 'User' });
-
-			expect(awareness.getStates().has(awareness.clientID)).toBe(true);
-
-			// Setting null removes the state
-			awareness.setLocalState(null);
-
-			expect(awareness.getStates().has(awareness.clientID)).toBe(false);
+		const response = handleSyncPayload({
+			syncType: SYNC_MESSAGE_TYPE.STEP1,
+			payload: Y.encodeStateVector(clientDoc),
+			doc: serverDoc,
+			origin: 'test-client',
 		});
-	});
-});
-
-// ============================================================================
-// MESSAGE_QUERY_AWARENESS Tests
-// ============================================================================
-
-describe('MESSAGE_QUERY_AWARENESS', () => {
-	test('query awareness message is single byte', () => {
-		const message = encodeQueryAwareness();
 
-		expect(message.length).toBe(1);
-		expect(message[0]).toBe(MESSAGE_TYPE.QUERY_AWARENESS);
-	});
-});
-
-// ============================================================================
-// Decoder Tests
-// ============================================================================
-
-describe('decodeSyncMessage', () => {
-	test('decodes sync step 1 message', () => {
-		const doc = createDoc((d) => d.getMap('test').set('key', 'value'));
-		const encoded = encodeSyncStep1({ doc });
-		const decoded = decodeSyncMessage(encoded);
-
-		expect(decoded.type).toBe('step1');
-		if (decoded.type === 'step1') {
-			expect(decoded.stateVector).toBeInstanceOf(Uint8Array);
-			expect(decoded.stateVector.length).toBeGreaterThan(0);
+		if (!response) {
+			throw new Error('Expected a STEP2 response for a STEP1 payload');
 		}
-	});
-
-	test('decodes sync step 2 message', () => {
-		const doc = createDoc((d) => d.getMap('test').set('key', 'value'));
-		const encoded = encodeSyncStep2({ doc });
-		const decoded = decodeSyncMessage(encoded);
+		const { syncType, payload } = readFrame(response);
+		expect(syncType).toBe(SYNC_MESSAGE_TYPE.STEP2);
 
-		expect(decoded.type).toBe('step2');
-		if (decoded.type === 'step2') {
-			expect(decoded.update).toBeInstanceOf(Uint8Array);
-			expect(decoded.update.length).toBeGreaterThan(0);
-		}
+		// The client applies the STEP2 payload and converges on server content.
+		Y.applyUpdateV2(clientDoc, payload);
+		expect(clientDoc.getMap('data').get('server')).toBe('content');
 	});
 
-	test('decodes sync update message', () => {
-		const doc = createDoc();
-		let capturedUpdate: Uint8Array | null = null;
-		doc.on('updateV2', (update: Uint8Array) => {
-			capturedUpdate = update;
+	test('returns null for sync step 2 (no response needed)', () => {
+		const serverDoc = createDoc();
+		const clientDoc = createDoc((d) => {
+			d.getMap('data').set('client', 'content');
 		});
-		doc.getMap('test').set('key', 'value');
 
-		if (!capturedUpdate) {
-			throw new Error('Expected captured update after document mutation');
-		}
-		const encoded = encodeSyncUpdate({ update: capturedUpdate });
-		const decoded = decodeSyncMessage(encoded);
+		const response = handleSyncPayload({
+			syncType: SYNC_MESSAGE_TYPE.STEP2,
+			payload: Y.encodeStateAsUpdateV2(clientDoc),
+			doc: serverDoc,
+			origin: 'test-client',
+		});
 
-		expect(decoded.type).toBe('update');
-		if (decoded.type === 'update') {
-			expect(decoded.update).toBeInstanceOf(Uint8Array);
-		}
+		expect(response).toBeNull();
 	});
 
-	test('throws on non-SYNC message type', () => {
-		const doc = createDoc();
-		const awareness = new Awareness(doc);
-		awareness.setLocalState({ name: 'Test' });
-		const awarenessMessage = encodeAwarenessStates({
-			awareness,
-			clients: [awareness.clientID],
-		});
-
-		expect(() => decodeSyncMessage(awarenessMessage)).toThrow(
-			'Expected SYNC message (0), got 1',
+	test('returns null for sync update (no response needed)', () => {
+		const serverDoc = createDoc();
+		const updateV2 = Y.encodeStateAsUpdateV2(
+			createDoc((d) => d.getMap('data').set('key', 'value')),
 		);
-	});
 
-	test('roundtrip: encode then decode preserves data', () => {
-		const doc = createDoc((d) => {
-			d.getMap('users').set('alice', { name: 'Alice', age: 30 });
-			d.getArray('items').push(['item1', 'item2']);
+		const response = handleSyncPayload({
+			syncType: SYNC_MESSAGE_TYPE.UPDATE,
+			payload: updateV2,
+			doc: serverDoc,
+			origin: 'test-client',
 		});
 
-		// Test step 1 roundtrip
-		const step1 = encodeSyncStep1({ doc });
-		const decodedStep1 = decodeSyncMessage(step1);
-		expect(decodedStep1.type).toBe('step1');
-
-		// Test step 2 roundtrip
-		const step2 = encodeSyncStep2({ doc });
-		const decodedStep2 = decodeSyncMessage(step2);
-		expect(decodedStep2.type).toBe('step2');
+		expect(response).toBeNull();
 	});
-});
 
-describe('decodeMessageType', () => {
-	test('decodes SYNC message type', () => {
-		const doc = createDoc();
-		const message = encodeSyncStep1({ doc });
-		expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.SYNC);
-	});
+	test('applies update to document', () => {
+		const serverDoc = createDoc();
+		const clientDoc = createDoc((d) => {
+			d.getMap('data').set('key', 'value');
+		});
 
-	test('decodes AWARENESS message type', () => {
-		const doc = createDoc();
-		const awareness = new Awareness(doc);
-		awareness.setLocalState({ name: 'Test' });
-		const message = encodeAwarenessStates({
-			awareness,
-			clients: [awareness.clientID],
+		handleSyncPayload({
+			syncType: SYNC_MESSAGE_TYPE.UPDATE,
+			payload: Y.encodeStateAsUpdateV2(clientDoc),
+			doc: serverDoc,
+			origin: 'test-client',
 		});
-		expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.AWARENESS);
-	});
 
-	test('decodes QUERY_AWARENESS message type', () => {
-		const message = encodeQueryAwareness();
-		expect(decodeMessageType(message)).toBe(MESSAGE_TYPE.QUERY_AWARENESS);
+		expect(serverDoc.getMap('data').get('key')).toBe('value');
 	});
 });
 
@@ -640,67 +165,24 @@ describe('full sync protocol', () => {
 		});
 		const clientDoc = createDoc();
 
-		// Server handles client's state vector and responds with sync step 2 (V2 update)
+		// Server handles the client's state vector and responds with STEP2.
 		const serverResponse = handleSyncPayload({
 			syncType: SYNC_MESSAGE_TYPE.STEP1,
 			payload: Y.encodeStateVector(clientDoc),
 			doc: serverDoc,
 			origin: 'client',
 		});
-
-		expect(serverResponse).not.toBeNull();
 		if (!serverResponse) {
-			throw new Error('Expected server sync response during handshake');
+			throw new Error('Expected a server sync response during handshake');
 		}
 
-		// Client applies server's V2 response
-		const decoded = decodeSyncMessage(serverResponse);
-		expect(decoded.type).toBe('step2');
-		if (decoded.type === 'step2') {
-			Y.applyUpdateV2(clientDoc, decoded.update, 'server');
-		}
+		// Client decodes the STEP2 frame and applies it through the same path.
+		const { syncType, payload } = readFrame(serverResponse);
+		expect(syncType).toBe(SYNC_MESSAGE_TYPE.STEP2);
+		handleSyncPayload({ syncType, payload, doc: clientDoc, origin: 'server' });
 
-		// Client should have server's content
 		expect(clientDoc.getMap('notes').get('note1')).toBe('Hello from server');
 	});
-
-	test('bidirectional sync merges both documents', () => {
-		const doc1 = createDoc((d) => d.getMap('data').set('from1', 'value1'));
-		const doc2 = createDoc((d) => d.getMap('data').set('from2', 'value2'));
-
-		// Full bidirectional sync using Yjs V2 pattern
-		syncDocs(doc1, doc2);
-
-		expect(doc1.getMap('data').get('from1')).toBe('value1');
-		expect(doc1.getMap('data').get('from2')).toBe('value2');
-		expect(doc2.getMap('data').get('from1')).toBe('value1');
-		expect(doc2.getMap('data').get('from2')).toBe('value2');
-	});
-
-	test('incremental updates are applied correctly', () => {
-		const doc1 = createDoc();
-		const doc2 = createDoc();
-
-		// Capture V2 updates from doc1
-		const updates: Uint8Array[] = [];
-		doc1.on('updateV2', (update: Uint8Array) => {
-			updates.push(update);
-		});
-
-		// Make changes
-		doc1.getMap('data').set('key1', 'value1');
-		doc1.getMap('data').set('key2', 'value2');
-		doc1.getArray('list').push(['item1', 'item2']);
-
-		// Apply V2 updates to doc2
-		for (const update of updates) {
-			Y.applyUpdateV2(doc2, update);
-		}
-
-		expect(doc2.getMap('data').get('key1')).toBe('value1');
-		expect(doc2.getMap('data').get('key2')).toBe('value2');
-		expect(doc2.getArray('list').toArray()).toEqual(['item1', 'item2']);
-	});
 });
 
 // ============================================================================
@@ -708,51 +190,28 @@ describe('full sync protocol', () => {
 // ============================================================================
 
 describe('edge cases', () => {
-	test('handles large document (1000+ operations)', () => {
-		const doc = createDoc((d) => {
+	test('handshake syncs a large document (1000+ operations)', () => {
+		const serverDoc = createDoc((d) => {
 			const arr = d.getArray<string>('items');
 			for (let i = 0; i < 1000; i++) {
 				arr.push([`item-${i}`]);
 			}
 		});
+		const clientDoc = createDoc();
 
-		// Sync step 1 contains state vector (compact), not full content
-		const syncStep1 = encodeSyncStep1({ doc });
-		expect(decodeSyncMessage(syncStep1).type).toBe('step1');
-
-		// Sync step 2 contains actual document content
-		const syncStep2 = encodeSyncStep2({ doc });
-		expect(decodeSyncMessage(syncStep2).type).toBe('step2');
-		expect(syncStep2.length).toBeGreaterThan(1000);
-	});
-
-	test('handles concurrent modifications (CRDT merge)', () => {
-		const doc1 = createDoc();
-		const doc2 = createDoc();
-
-		// Both modify same key concurrently
-		doc1.getMap('data').set('key', 'value1');
-		doc2.getMap('data').set('key', 'value2');
-
-		// Sync should resolve deterministically
-		syncDocs(doc1, doc2);
-
-		// Both should have same value (CRDT resolution)
-		const val1 = doc1.getMap('data').get('key');
-		const val2 = doc2.getMap('data').get('key');
-		expect(val1).toBe(val2);
-	});
-
-	test('empty document produces valid sync step 1', () => {
-		const doc = createDoc();
-		const message = encodeSyncStep1({ doc });
-		const decoded = decodeSyncMessage(message);
-
-		expect(decoded.type).toBe('step1');
-		if (decoded.type === 'step1') {
-			// Even empty docs have a state vector (contains clientID info)
-			expect(decoded.stateVector).toBeInstanceOf(Uint8Array);
+		const response = handleSyncPayload({
+			syncType: SYNC_MESSAGE_TYPE.STEP1,
+			payload: Y.encodeStateVector(clientDoc),
+			doc: serverDoc,
+			origin: 'client',
+		});
+		if (!response) {
+			throw new Error('Expected a STEP2 response for the handshake');
 		}
+		const { syncType, payload } = readFrame(response);
+		handleSyncPayload({ syncType, payload, doc: clientDoc, origin: 'server' });
+
+		expect(clientDoc.getArray('items').length).toBe(1000);
 	});
 });
 
@@ -767,10 +226,18 @@ function createDoc(init?: (doc: Y.Doc) => void): Y.Doc {
 	return doc;
 }
 
-/** Sync two documents bidirectionally (standard Yjs test pattern, V2) */
-function syncDocs(doc1: Y.Doc, doc2: Y.Doc): void {
-	const state1 = Y.encodeStateAsUpdateV2(doc1);
-	const state2 = Y.encodeStateAsUpdateV2(doc2);
-	Y.applyUpdateV2(doc1, state2);
-	Y.applyUpdateV2(doc2, state1);
+/**
+ * Decode a binary sync frame into its sub-type and payload. Mirrors the
+ * production transport decode (`Room.webSocketMessage` / `sync-supervisor`),
+ * which asserts the sub-type varint as `SyncMessageType`.
+ */
+function readFrame(data: Uint8Array): {
+	syncType: SyncMessageType;
+	payload: Uint8Array;
+} {
+	const decoder = decoding.createDecoder(data);
+	return {
+		syncType: decoding.readVarUint(decoder) as SyncMessageType,
+		payload: decoding.readVarUint8Array(decoder),
+	};
 }