@abloatai/ablo 0.25.0 → 0.26.0

package/dist/sync/SyncWebSocket.js

@@ -9,11 +9,33 @@
  */
 import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
-import { flushOfflineQueueOnce } from './OfflineFlush.js';
-import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
-import { subscriptionAckPayloadSchema, staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
-import { formatClaim, formatConflict } from '../coordination/trace.js';
+import { AbloConnectionError, AbloError, SyncSessionError, toAbloError, } from '../errors.js';
+import { clientSyncDeltaSchema } from '../schema/sync-delta-wire.js';
+// Commit-path frame builders (pure) — extracted leaf; the host re-exports
+// `CommitAck` below so importers keep this module as their path.
+import { buildCommitFrame } from './commitFrames.js';
+// Inbound frame dispatch table + the minimal session slice it operates on.
+import { dispatchWsFrame, isRecord, isWsInboundFrame, } from './wsFrameHandlers.js';
+// Sync-position state (lastSyncId watermark, version vector, server cursor).
+import { SyncCursor } from './syncCursor.js';
+import { PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION } from '../wire/protocolVersion.js';
+// Application-level heartbeat timers (see heartbeat.ts for the rationale).
+import { HeartbeatController } from './heartbeat.js';
 import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
+// SyncObservability replaced by getContext().observability
+/**
+ * Periodic catch-up poll cadence — while connected, request any deltas
+ * whose fire-and-forget pub/sub broadcast was lost in transit. Deliberately
+ * LOCAL (not `wire/protocol.ts`): an SDK eventual-consistency knob, not a
+ * cross-boundary contract the server derives anything from. That it equals
+ * the 30s ping today is coincidence, not an invariant.
+ */
+const CATCHUP_POLL_INTERVAL_MS = 30_000;
+/**
+ * Ceiling for the exponential reconnect backoff (`reconnectDelay * 2^n`,
+ * ±15% jitter). Local for the same reason as the catch-up poll.
+ */
+const MAX_RECONNECT_DELAY_MS = 30_000;
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
 // Consumers pass their own event types as TCollaboration generic parameter.
@@ -47,20 +69,20 @@ export class SyncWebSocket extends EventEmitter {
     /** Periodic catchup interval — polls for missed deltas every 30s while connected */
     catchupInterval = null;
     /**
-     * Application-level heartbeat. The browser WebSocket API hides RFC 6455
-     * protocol-level ping/pong from JavaScript, so the server's `ws.ping()`
-     * keepalive can't be observed by client code — meaning the client cannot
-     * tell a healthy idle connection apart from a "zombie" socket where TCP
-     * silently broke (laptop sleep, NAT timeout, mobile handoff). We send an
-     * application-level `{ type: 'ping' }` every 30s and force-close the
-     * socket if no inbound traffic arrives within 10s. ANY inbound message
-     * counts as proof-of-life — the explicit `pong` is just a guarantee that
-     * something will arrive even on an idle stream.
+     * Application-level heartbeat — ping every 30s, force-close on a 10s
+     * silent watchdog. The full zombie-socket rationale lives with the
+     * timers in `sync/heartbeat.ts`; the transport closures below are the
+     * only socket access the controller gets.
      */
-    heartbeatTimer = null;
-    heartbeatTimeoutTimer = null;
-    static HEARTBEAT_INTERVAL_MS = 30_000;
-    static HEARTBEAT_TIMEOUT_MS = 10_000;
+    heartbeat = new HeartbeatController({
+        isSocketOpen: () => this.ws?.readyState === WebSocket.OPEN,
+        // Optional-chained rather than asserted: the controller only calls
+        // this synchronously after `isSocketOpen()`, so `ws` is present.
+        sendPing: () => {
+            this.ws?.send(JSON.stringify({ type: 'ping' }));
+        },
+        forceClose: (reason) => { this.forceClose(reason); },
+    });
     isConnecting = false;
     isManualClose = false;
     /** When true, a session error has been detected (from any path — WS close or HTTP bootstrap).
@@ -88,11 +110,23 @@ export class SyncWebSocket extends EventEmitter {
     lastCloseReason = null;
     lastForceCloseReason = null;
     sessionErrorAt = null;
-    lastSyncId;
-    versionVector;
-    syncCursor = null;
+    /**
+     * Sync-position state (lastSyncId watermark, version vector, server
+     * cursor). The advance discipline stays documented at `sendAck` /
+     * `handleDelta`; the state itself lives in `sync/syncCursor.ts`.
+     */
+    cursor;
     /** Registered collaboration event keys (colon format) for dispatch in onmessage */
     collaborationEventTypes;
+    /**
+     * Minimal session adapter handed to the frame dispatch table
+     * (`sync/wsFrameHandlers.ts`). Exposes ONLY the members the handlers
+     * touch; the closure members read live state so host-side reassignment
+     * (e.g. the `pendingSubscriptions` reset on close) can't strand the
+     * handlers on a stale reference. Built in the constructor, after the
+     * state it captures exists.
+     */
+    frameSession;
     /**
      * In-flight `commit` mutation requests keyed by clientTxId. Resolved when
      * a matching `mutation_result` frame arrives from the server, or rejected on
@@ -125,21 +159,10 @@ export class SyncWebSocket extends EventEmitter {
         this.options = {
             url: wsUrl,
             reconnectDelay: 1000,
-            maxReconnectDelay: 30000,
+            maxReconnectDelay: MAX_RECONNECT_DELAY_MS,
             collaborationEvents: ['sheet:selection', 'slide:selection', 'slide:cursor'],
             syncGroups: [],
             lastSyncId: 0,
-            versions: {
-                tasks: 0,
-                projects: 0,
-                users: 0,
-                events: 0,
-                inboxitems: 0,
-                teams: 0,
-                assignments: 0,
-                comments: 0,
-                threads: 0,
-            },
             capabilities: {
                 partialBootstrap: true,
                 compressedDeltas: true,
@@ -148,10 +171,25 @@ export class SyncWebSocket extends EventEmitter {
             },
             ...options,
         };
-        this.lastSyncId = this.options.lastSyncId;
-        this.versionVector = { ...this.options.versions };
-        this.syncCursor = null;
+        this.cursor = new SyncCursor(this.options.lastSyncId);
         this.collaborationEventTypes = new Set(options.collaborationEvents ?? ['sheet:selection', 'slide:selection', 'slide:cursor']);
+        // Session slice for the inbound frame dispatch table — see the field
+        // doc on `frameSession` for why members that the host reassigns are
+        // exposed through closures instead of captured references.
+        this.frameSession = {
+            emit: (event, ...args) => this.emit(event, ...args),
+            pendingMutations: this.pendingMutations,
+            pendingClaims: this.pendingClaims,
+            shiftPendingSubscription: () => this.pendingSubscriptions.shift(),
+            options: this.options,
+            collaborationEventTypes: this.collaborationEventTypes,
+            handleDelta: (delta) => { this.handleDelta(delta); },
+            handleSyncResponse: (payload) => { this.handleSyncResponse(payload); },
+            handleBootstrapResponse: (payload) => { this.handleBootstrapResponse(payload); },
+            handlePresenceUpdate: (message) => {
+                this.handlePresenceUpdate(message);
+            },
+        };
     }
     /**
      * Mark that a session error has been detected (e.g. 401 from HTTP bootstrap).
@@ -161,6 +199,17 @@ export class SyncWebSocket extends EventEmitter {
         this._sessionErrorDetected = true;
         this.sessionErrorAt = Date.now();
     }
+    /**
+     * Clear the session-error latch so `connect()` / `scheduleReconnect()`
+     * work again. Called by the store's access-credential recovery path when
+     * the close was a re-mintable `ek_`/`rk_` expiry (`4001 credential_expired`),
+     * not a login loss — see `isAccessCredentialExpiryCloseReason`. Genuine
+     * session losses never clear the latch; re-auth builds a fresh client.
+     */
+    clearSessionError() {
+        this._sessionErrorDetected = false;
+        this.sessionErrorAt = null;
+    }
     /**
      * Connect to the sync engine WebSocket
      */
@@ -169,8 +218,15 @@ export class SyncWebSocket extends EventEmitter {
             getContext().logger.debug('WebSocket connect suppressed — session error detected');
             return;
         }
-        if (this.ws?.readyState === WebSocket.OPEN || this.isConnecting) {
-            getContext().logger.debug('WebSocket already connected or connecting');
+        // CLOSING counts as busy: the socket's close teardown is still in
+        // flight and its `onclose` (which runs `scheduleReconnect`) hasn't
+        // fired yet. Overwriting `this.ws` mid-teardown is what produced the
+        // orphaned-socket race — see the stale-socket guards in
+        // `setupEventHandlers`.
+        if (this.ws?.readyState === WebSocket.OPEN ||
+            this.ws?.readyState === WebSocket.CLOSING ||
+            this.isConnecting) {
+            getContext().logger.debug('WebSocket already connected, connecting, or closing');
             return;
         }
         // Note: onlineStatus is advisory — we'll try to connect and let the WebSocket
@@ -187,9 +243,9 @@ export class SyncWebSocket extends EventEmitter {
         // server is bearer-only (`apiKeyProvider`) and resolves identity from the
         // verified token — userId/organizationId are NEVER read from URL params.
         const params = new URLSearchParams({
-            // Intentionally omit lastSyncId, versions, capabilities from URL; these are sent in sync_request
+            // Intentionally omit lastSyncId, capabilities from URL; these are sent in sync_request
             // and ack messages to avoid stale baselines on reconnect.
-            cursor: this.syncCursor || '',
+            cursor: this.cursor.syncCursor || '',
         });
         // Participant kind — defaults to `user` for backward compatibility
         // with web sessions. Agent runtimes pass `'agent'` so the server's
@@ -234,11 +290,22 @@ export class SyncWebSocket extends EventEmitter {
      * Setup WebSocket event handlers
      */
     setupEventHandlers() {
-        if (!this.ws)
+        // Capture the socket THIS call wires. Every handler below guards on
+        // `this.ws === socket` (onclose additionally tolerates a nulled host —
+        // see there) so a handler firing late, after `connect()` replaced the
+        // socket, can never clobber the NEW connection's shared state. Without
+        // this, an old socket's `onclose` ran `this.ws = null;
+        // stopCatchupInterval(); stopHeartbeat()` unconditionally — a reconnect
+        // during close teardown orphaned the fresh socket (zombie receiving
+        // deltas with no timers and broken send paths).
+        const socket = this.ws;
+        if (!socket)
             return;
-        this.ws.onopen = () => {
+        socket.onopen = () => {
+            if (this.ws !== socket)
+                return; // stale socket — a newer connect() owns the state
             getContext().observability.breadcrumb('WebSocket connected', 'sync.websocket', 'info', {
-                lastSyncId: this.lastSyncId,
+                lastSyncId: this.cursor.lastSyncId,
                 reconnectAttempts: this.reconnectAttempts,
             });
             this.isConnecting = false;
@@ -249,376 +316,71 @@ export class SyncWebSocket extends EventEmitter {
             // Send presence update with timezone (server sets presence to "online" on connect,
             // this improves localTime accuracy by providing the user's actual timezone)
             this.sendPresenceUpdate('online');
-            // Flush any queued offline mutations now that we're online
-            // Fire-and-forget; emit events for UI if desired in the future
-            (async () => {
-                try {
-                    const res = await flushOfflineQueueOnce();
-                    if (res.processed > 0) {
-                        getContext().logger.info('Flushed offline mutations', res);
-                    }
-                }
-                catch (e) {
-                    getContext().observability.captureOfflineFlushFailure({
-                        error: e instanceof Error ? e.message : String(e),
-                    });
-                }
-            })();
-            // Immediately request incremental sync based on our stored cursor/versions
+            // Immediately request incremental sync based on our stored cursor.
+            // `requestIncrementalSync` is async — a bare call inside try/catch is a
+            // rejection hole (the catch never sees it); route failures through
+            // `.catch` so they land in the same breadcrumb instead of an
+            // unhandled rejection.
+            const reportSyncRequestFailure = (e) => {
+                getContext().observability.breadcrumb('Failed to request incremental sync on open', 'sync.websocket', 'warning', {
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            };
             try {
-                if (this.lastSyncId && this.lastSyncId > 0) {
+                if (this.cursor.lastSyncId && this.cursor.lastSyncId > 0) {
                     // Let server know where we left off before requesting deltas
-                    this.sendAck(this.lastSyncId);
+                    this.sendAck(this.cursor.lastSyncId);
                 }
-                this.requestIncrementalSync();
             }
             catch (e) {
-                getContext().observability.breadcrumb('Failed to request incremental sync on open', 'sync.websocket', 'warning', {
-                    error: e instanceof Error ? e.message : String(e),
-                });
+                reportSyncRequestFailure(e);
             }
-            // Start periodic catchup — polls for missed deltas every 30s.
-            // Real-time WebSocket delivery is best-effort (fire-and-forget Redis pub/sub).
-            // This interval guarantees eventual consistency by fetching any deltas that
-            // were committed to the DB but whose broadcast was lost in transit.
+            this.requestIncrementalSync().catch(reportSyncRequestFailure);
+            // Start periodic catchup — polls for missed deltas every
+            // CATCHUP_POLL_INTERVAL_MS while connected. Real-time WebSocket
+            // delivery is best-effort (fire-and-forget Redis pub/sub). This
+            // interval guarantees eventual consistency by fetching any deltas
+            // that were committed to the DB but whose broadcast was lost in
+            // transit.
             this.stopCatchupInterval();
             this.catchupInterval = setInterval(() => {
                 if (this.ws?.readyState === WebSocket.OPEN) {
-                    this.requestIncrementalSync();
+                    // A rejected sync request must never surface as an unhandled
+                    // rejection from a background interval — log and let the next
+                    // poll retry.
+                    this.requestIncrementalSync().catch((e) => {
+                        getContext().observability.breadcrumb('Periodic catchup sync request failed', 'sync.websocket', 'warning', {
+                            error: e instanceof Error ? e.message : String(e),
+                        });
+                    });
                 }
-            }, 30_000);
-            // Start application-level heartbeat — see field declaration for rationale.
-            this.startHeartbeat();
+            }, CATCHUP_POLL_INTERVAL_MS);
+            // Start application-level heartbeat — see sync/heartbeat.ts for rationale.
+            this.heartbeat.start();
         };
-        this.ws.onmessage = (event) => {
+        socket.onmessage = (event) => {
+            if (this.ws !== socket)
+                return; // stale socket — drop, don't feed shared state
             try {
+                // Untrusted wire input: parse to `unknown`, then narrow through
+                // the frame-envelope guard before dispatch. Payload-level
+                // validation (deltas etc.) happens per-frame downstream.
                 const message = JSON.parse(event.data);
                 // ANY inbound frame proves the socket is alive — clear the
                 // heartbeat-timeout timer so we don't false-trip force-close
                 // during normal traffic.
-                this.clearHeartbeatTimeout();
-                // Handle different message types
-                if (message.type === 'pong' || message.type === 'ping') {
-                    // Ignore keepalive messages
-                    getContext().logger.debug('Received keepalive', { type: message.type });
+                this.heartbeat.clearHeartbeatTimeout();
+                if (!isWsInboundFrame(message)) {
+                    getContext().logger.debug('[SyncWebSocket] dropped malformed wire frame', {
+                        received: Array.isArray(message) ? 'array' : typeof message,
+                    });
                     return;
                 }
-                // Handle different message types
-                switch (message.type) {
-                    case 'sync_response':
-                        this.handleSyncResponse(message.payload);
-                        break;
-                    case 'bootstrap_response':
-                        this.handleBootstrapResponse(message.payload);
-                        break;
-                    case 'presence_update':
-                        this.handlePresenceUpdate(message);
-                        break;
-                    case 'mutation_result': {
-                        // Ack for a prior `commit` we sent. Canonical shape is
-                        // `MutationResultMessage` in `@abloatai/ablo/wire`. This stays a
-                        // DEFENSIVE parse (not a typed cast) because the payload is
-                        // untrusted wire data that may be malformed or from an older server.
-                        const p = message.payload ?? message;
-                        const { clientTxId, success, lastSyncId, error } = p ?? {};
-                        // Defensive: validate notifications against the canonical schema —
-                        // untrusted wire data from a possibly-older/newer server.
-                        const notifications = this.parseNotifications(p?.notifications);
-                        const pending = typeof clientTxId === 'string'
-                            ? this.pendingMutations.get(clientTxId)
-                            : undefined;
-                        if (!pending)
-                            break;
-                        clearTimeout(pending.timeout);
-                        this.pendingMutations.delete(clientTxId);
-                        if (success) {
-                            // Coerce defensively — bigint columns serialize as strings
-                            // from older servers (see normalizeWireDelta).
-                            const ackedSyncId = Number(lastSyncId);
-                            // Notify-instead-of-abort: a guarded write's premise moved. Emit
-                            // the advisory signal so an agent loop can self-heal, AND resolve
-                            // the receipt with it (the commit still succeeded).
-                            if (notifications && notifications.length > 0) {
-                                const txId = typeof clientTxId === 'string' ? clientTxId : '';
-                                const event = {
-                                    clientTxId: txId,
-                                    rows: notifications.map((n) => ({
-                                        model: n.model,
-                                        id: n.id,
-                                        fields: n.conflictingFields,
-                                        writtenBy: n.writtenBy?.kind,
-                                    })),
-                                };
-                                const message = formatConflict(event);
-                                const ctx = getContext();
-                                ctx.logger.warn(message);
-                                ctx.observability.breadcrumb(message, 'sync.coordination', 'warning');
-                                ctx.observability.captureConflict(event);
-                                this.emit('conflict:notified', {
-                                    clientTxId: txId,
-                                    notifications,
-                                });
-                            }
-                            pending.resolve({
-                                lastSyncId: Number.isFinite(ackedSyncId) ? ackedSyncId : 0,
-                                ...(notifications && notifications.length > 0
-                                    ? { notifications }
-                                    : {}),
-                            });
-                        }
-                        else {
-                            // Capture the FULL server error so the user can see what
-                            // actually rejected the mutation. Without this, every
-                            // rejection becomes the generic "mutation failed on
-                            // server" — useless when debugging chart batches that
-                            // tank 40+ ops at once. We stringify object errors so
-                            // structured server payloads (e.g., Zod issues, schema
-                            // violations) survive the trip through `new Error(...)`.
-                            let errorMessage;
-                            let errorCode;
-                            let requiredCapability;
-                            if (typeof error === 'string') {
-                                errorMessage = error;
-                            }
-                            else if (error != null && typeof error === 'object') {
-                                const obj = error;
-                                if (typeof obj.code === 'string')
-                                    errorCode = obj.code;
-                                if (typeof obj.message === 'string') {
-                                    errorMessage = obj.message;
-                                }
-                                else {
-                                    try {
-                                        errorMessage = JSON.stringify(error);
-                                    }
-                                    catch {
-                                        errorMessage = String(error);
-                                    }
-                                }
-                                if (obj.requiredCapability != null &&
-                                    typeof obj.requiredCapability === 'object' &&
-                                    typeof obj.requiredCapability.scope === 'string') {
-                                    requiredCapability = obj.requiredCapability;
-                                }
-                            }
-                            else {
-                                errorMessage = 'mutation failed on server';
-                            }
-                            // Coordination collision: a stale-context rejection (the write's
-                            // readAt premise moved underneath) or a foreign-claim conflict is
-                            // exactly the collision ClaimLog exists to surface. The notify
-                            // path (success + notifications) emits captureConflict above; a
-                            // HARD rejection must too — otherwise observability.collisions()
-                            // silently misses every rejected write. The conflicted rows ride
-                            // along on the typed error's `conflicts` detail (see
-                            // AbloStaleContextError.toJSON / errorEnvelope).
-                            if (errorCode === 'stale_context' ||
-                                errorCode === 'claim_conflict' ||
-                                errorCode === 'entity_claimed' ||
-                                errorCode?.startsWith('policy:') === true) {
-                                const rawConflicts = error != null &&
-                                    typeof error === 'object' &&
-                                    Array.isArray(error.conflicts)
-                                    ? error
-                                        .conflicts
-                                    : [];
-                                const conflictEvent = {
-                                    clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
-                                    rows: rawConflicts.map((r) => ({
-                                        model: typeof r.model === 'string' ? r.model : 'unknown',
-                                        id: typeof r.id === 'string' ? r.id : 'unknown',
-                                        fields: [],
-                                    })),
-                                };
-                                const ctx = getContext();
-                                ctx.observability.breadcrumb(formatConflict(conflictEvent), 'sync.coordination', 'warning');
-                                ctx.observability.captureConflict(conflictEvent);
-                            }
-                            // Build the proper typed AbloError from the wire code via the
-                            // shared factory — the same code→class mapping the HTTP commit
-                            // path uses (`translateHttpError`). This keeps rejected commits
-                            // inside the typed hierarchy (capability denials →
-                            // CapabilityError with `.requiredCapability`; foreign-claim
-                            // conflicts → AbloClaimedError; everything else → the subclass
-                            // its registry `httpStatus` implies) instead of a hand-rolled
-                            // `new Error`, so callers can `instanceof`/`e.type` it and
-                            // downstream retry logic can read the contract's retryability.
-                            pending.reject(errorFromWire(errorMessage, {
-                                code: errorCode,
-                                requiredCapability,
-                            }));
-                        }
-                        break;
-                    }
-                    case 'claim_ack': {
-                        // Ack for a prior `claim` we sent. Wire format mirrors
-                        // apps/sync-server/src/hub/types.ts ClaimAckMessage:
-                        //   { type: 'claim_ack',
-                        //     payload: { claimId, success, syncGroups?,
-                        //                ttlSeconds?, error? } }
-                        const p = message.payload ?? {};
-                        const { claimId, success, syncGroups, ttlSeconds, error } = p;
-                        const pending = typeof claimId === 'string'
-                            ? this.pendingClaims.get(claimId)
-                            : undefined;
-                        if (!pending)
-                            break;
-                        clearTimeout(pending.timeout);
-                        this.pendingClaims.delete(claimId);
-                        if (success) {
-                            pending.resolve({
-                                syncGroups: Array.isArray(syncGroups) ? syncGroups : [],
-                                ttlSeconds: typeof ttlSeconds === 'number' ? ttlSeconds : undefined,
-                            });
-                        }
-                        else {
-                            const code = error?.code && typeof error.code === 'string'
-                                ? error.code
-                                : 'claim_rejected';
-                            const msg = error?.message && typeof error.message === 'string'
-                                ? error.message
-                                : 'claim rejected by server';
-                            // Capability denials get the typed CapabilityError so
-                            // callers can read `.requiredCapability` and attenuate-
-                            // and-retry the claim with a narrower token.
-                            if (code === 'capability_scope_denied' ||
-                                code === 'capability_invalid') {
-                                const rc = error
-                                    ?.requiredCapability;
-                                const requiredCapability = rc != null &&
-                                    typeof rc === 'object' &&
-                                    typeof rc.scope === 'string'
-                                    ? rc
-                                    : undefined;
-                                pending.reject(new CapabilityError(code, msg, requiredCapability));
-                            }
-                            else {
-                                // Route through the shared factory so a failed claim_ack is a
-                                // typed AbloError (registry code → right subclass), symmetric
-                                // with the commit `mutation_result` path — never a bare Error.
-                                pending.reject(errorFromWire(msg, { code }));
-                            }
-                        }
-                        break;
-                    }
-                    case 'subscription_ack': {
-                        // Ack for a prior `update_subscription`. The wire carries no
-                        // correlation id, so FIFO-match against the oldest pending
-                        // request — the server applies and acks subscription updates
-                        // in receive order. Validated through the canonical zod schema
-                        // (mirrors how the Hub validates inbound frames).
-                        const pending = this.pendingSubscriptions.shift();
-                        if (!pending)
-                            break;
-                        clearTimeout(pending.timeout);
-                        const parsed = subscriptionAckPayloadSchema.safeParse(message.payload);
-                        if (!parsed.success) {
-                            // Unreadable ack — resolve the pending request as a failure
-                            // rather than hang it until timeout.
-                            pending.reject(errorFromWire('malformed subscription_ack from server', {
-                                code: 'malformed_subscription',
-                            }));
-                            break;
-                        }
-                        const ack = parsed.data;
-                        if (ack.success) {
-                            // Keep the reconnect URL aligned with current interest: a
-                            // reconnect re-subscribes from `this.options.syncGroups`.
-                            this.options.syncGroups = ack.syncGroups;
-                            pending.resolve({ syncGroups: ack.syncGroups });
-                        }
-                        else {
-                            pending.reject(errorFromWire(ack.error?.message ?? 'update_subscription rejected by server', { code: ack.error?.code ?? 'malformed_subscription' }));
-                        }
-                        break;
-                    }
-                    case 'claim_expired': {
-                        // Server-initiated expiry notification. Emit as a typed
-                        // event so consumers can react (re-claim with a fresh
-                        // capability, or accept the drop). The claim is already
-                        // inactive server-side by the time this arrives.
-                        const p = message.payload ?? {};
-                        if (typeof p.claimId === 'string') {
-                            this.recordClaim('expired', p);
-                            this.emit('claim_expired', { claimId: p.claimId });
-                        }
-                        break;
-                    }
-                    case 'claim_rejected': {
-                        // Server denied an `claim_begin` because the target is
-                        // already claimed by another participant. Forward the
-                        // payload as-is — the ClaimStream consumer interprets
-                        // the conflict shape (peerId, target, etc.).
-                        this.recordClaim('rejected', message.payload ?? {});
-                        this.emit('claim_rejected', message.payload ?? {});
-                        break;
-                    }
-                    case 'claim_acquired': {
-                        // Opt-in fair queue: the target was free, so the lease is ours
-                        // immediately (no waiting). Payload carries { claimId, target }.
-                        this.recordClaim('acquired', message.payload ?? {});
-                        this.emit('claim_acquired', message.payload ?? {});
-                        break;
-                    }
-                    case 'claim_queue': {
-                        // Per-entity wait-queue snapshot for reactive `queue(id)`. Not a
-                        // single claim's state change, so it isn't logged — the per-claim
-                        // `queued`/`granted` events already tell that story.
-                        this.emit('claim_queue', message.payload ?? {});
-                        break;
-                    }
-                    case 'claim_queued': {
-                        // Opt-in fair queue: our claim is waiting in line. Payload
-                        // carries { claimId, target, position }.
-                        this.recordClaim('queued', message.payload ?? {});
-                        this.emit('claim_queued', message.payload ?? {});
-                        break;
-                    }
-                    case 'claim_granted': {
-                        // Our queued claim reached the head — the lease is now ours.
-                        this.recordClaim('granted', message.payload ?? {});
-                        this.emit('claim_granted', message.payload ?? {});
-                        break;
-                    }
-                    case 'claim_lost': {
-                        // A held/granted claim was taken from us (TTL lapse, revoke).
-                        this.recordClaim('lost', message.payload ?? {});
-                        this.emit('claim_lost', message.payload ?? {});
-                        break;
-                    }
-                    case 'delta': {
-                        const p = message.payload;
-                        if (p?.actionType || p?.modelName) {
-                            this.handleDelta(p);
-                        }
-                        else if (Array.isArray(p?.deltas)) {
-                            for (const d of p.deltas) {
-                                if (d?.actionType || d?.modelName)
-                                    this.handleDelta(d);
-                            }
-                            if (p?.newVersions) {
-                                Object.assign(this.versionVector, p.newVersions);
-                            }
-                        }
-                        break;
-                    }
-                    case undefined: // Legacy support: bare delta
-                        if (message.actionType || message.modelName) {
-                            this.handleDelta(message);
-                        }
-                        break;
-                    default: {
-                        // Collaboration events use underscore wire format (e.g., 'sheet_selection')
-                        // Convert to colon format for the event map (e.g., 'sheet:selection')
-                        const eventKey = message.type?.replace(/_/g, ':');
-                        if (eventKey && this.collaborationEventTypes.has(eventKey)) {
-                            this.emit(eventKey, message.payload);
-                        }
-                        else {
-                            getContext().logger.debug('Received unknown message type', { message });
-                        }
-                    }
-                }
+                // Frame-type → handler dispatch (sync/wsFrameHandlers.ts). The
+                // session adapter exposes only the members the handlers touch;
+                // keepalives, the legacy bare-delta form, and collaboration
+                // events are all routed there too.
+                dispatchWsFrame(this.frameSession, message);
             }
             catch (error) {
                 getContext().observability.captureWebSocketError({
@@ -627,7 +389,9 @@ export class SyncWebSocket extends EventEmitter {
                 });
             }
         };
-        this.ws.onerror = (_event) => {
+        socket.onerror = (_event) => {
+            if (this.ws !== socket)
+                return; // stale socket — its errors are no longer ours
             // WebSocket errors are DOM Events, not Error objects
             // Check if we're offline first
             if (!getContext().onlineStatus.isOnline()) {
@@ -646,7 +410,17 @@ export class SyncWebSocket extends EventEmitter {
             }
             this.emit('error', error);
         };
-        this.ws.onclose = (event) => {
+        socket.onclose = (event) => {
+            // Stale-socket close: a NEWER socket already owns the connection
+            // state — don't null it, stop its timers, or schedule a duplicate
+            // reconnect (the orphaning race this guard exists for). The one
+            // deliberate asymmetry vs the other handlers: `this.ws === null`
+            // (manual `disconnect()` nulls the field before the close event
+            // lands) still runs the full body, so in-flight work is rejected
+            // promptly and 'disconnected' reaches consumers — the pre-guard
+            // behavior manual close always had.
+            if (this.ws !== null && this.ws !== socket)
+                return;
             const everOpened = this._everOpened;
             this.lastCloseAt = Date.now();
             this.lastCloseCode = event.code;
@@ -663,7 +437,7 @@ export class SyncWebSocket extends EventEmitter {
             this.isConnecting = false;
             this.ws = null;
             this.stopCatchupInterval();
-            this.stopHeartbeat();
+            this.heartbeat.stop();
             // Cancel in-flight mutations — the socket that was carrying them is
             // gone, and the server-side state may or may not have accepted each
             // one. Rejecting promptly is better than hanging the caller forever;
@@ -706,6 +480,20 @@ export class SyncWebSocket extends EventEmitter {
                 }
                 this.pendingSubscriptions = [];
             }
+            // Protocol-version rejection (4010): TERMINAL. Reconnecting cannot heal
+            // a version mismatch — only upgrading the SDK (or rolling the server
+            // forward) can — so a blind retry here would loop forever against the
+            // same typed close. Surface it and stop.
+            if (event.code === WS_CLOSE_PROTOCOL_VERSION) {
+                getContext().observability.captureWebSocketError({
+                    context: 'protocol-version-close',
+                    code: event.code,
+                    reason: event.reason,
+                });
+                this.emit('protocol_mismatch', event);
+                this.emit('disconnected', event);
+                return;
+            }
             // Check for session-related close codes
             // 1008 = Policy Violation (often auth)
             // 4001 = Unauthorized (custom)
@@ -723,7 +511,11 @@ export class SyncWebSocket extends EventEmitter {
                     reason: event.reason,
                 });
                 this.emit('session_error', new SyncSessionError(event.reason || 'Session expired', event.code));
-                // Don't reconnect for session errors - user needs to re-authenticate
+                // Don't reconnect from HERE. For a genuine session loss the user
+                // must re-authenticate; for an expired ACCESS credential
+                // (`credential_expired`) the store's session_error handler re-mints,
+                // clears the latch, and drives the reconnect — see
+                // BaseSyncedStore.setupWebSocketSync.
                 this.emit('disconnected', event);
                 return;
             }
@@ -756,39 +548,77 @@ export class SyncWebSocket extends EventEmitter {
         };
     }
     /**
-     * Normalize a wire delta at the receive boundary. The contract
-     * (`syncDeltaWireCoreSchema`) says `id: number`, but deployed servers
-     * have sent the raw Postgres BIGINT serialization — a STRING — and
-     * every downstream watermark gate (`typeof syncId === 'number'` in
-     * `Database.processDeltaBatch`, the metadata-cursor update, numeric
-     * `>=` threshold comparisons in TransactionQueue) silently breaks on
-     * strings: acks are withheld, the resume cursor never advances, and
-     * every reconnect replays from 0 (or force-bootstraps once the gap
-     * exceeds maxDeltaGapForPartial). Coerce ONCE here so the rest of the
-     * client can trust the declared type — and old servers stay compatible.
+     * Validate + normalize a wire delta at the receive boundary — the ONE
+     * seam every inbound delta (`delta` frame, batch element, `sync_response`
+     * replay, legacy bare frame) passes through before it is emitted,
+     * persisted to IDB, or allowed to advance any watermark.
+     *
+     * Normalization (older/deployed servers stay compatible):
+     *  - `id`: the contract says `number`, but deployed servers have sent the
+     *    raw Postgres BIGINT serialization — a STRING — and every downstream
+     *    watermark gate (`typeof syncId === 'number'` in
+     *    `Database.processDeltaBatch`, the metadata-cursor update, numeric
+     *    `>=` thresholds in TransactionQueue) silently breaks on strings:
+     *    acks are withheld, the resume cursor never advances, and every
+     *    reconnect replays from 0. Coerce ONCE here.
+     *  - `transactionId` / `createdBy`: the SERVER projection sends these as
+     *    nullable (and `createdBy` as a nested ParticipantRef); the client
+     *    contract types them as optional strings and never reads them.
+     *    Normalize to absent instead of rejecting every real server delta.
+     *
+     * Validation: `clientSyncDeltaSchema.safeParse` — the canonical Zod wire
+     * contract. A frame that fails is DROPPED (returns `null`) with a
+     * debug-level log + observability breadcrumb; it is never applied. One
+     * parse per delta — callers must not re-parse.
      */
-    normalizeWireDelta(delta) {
-        if (typeof delta.id === 'number')
-            return delta;
-        const coerced = Number(delta.id);
-        return { ...delta, id: Number.isFinite(coerced) ? coerced : 0 };
+    normalizeWireDelta(raw) {
+        let candidate = raw;
+        if (isRecord(raw)) {
+            const normalized = { ...raw };
+            if (typeof normalized.id !== 'number') {
+                const coerced = Number(normalized.id);
+                normalized.id = Number.isFinite(coerced) ? coerced : 0;
+            }
+            if (normalized.transactionId === null)
+                delete normalized.transactionId;
+            if (normalized.createdBy !== undefined && typeof normalized.createdBy !== 'string') {
+                delete normalized.createdBy;
+            }
+            candidate = normalized;
+        }
+        const parsed = clientSyncDeltaSchema.safeParse(candidate);
+        if (!parsed.success) {
+            const issue = parsed.error.issues[0];
+            const detail = {
+                issue: issue ? `${issue.path.join('.')}: ${issue.message}` : 'not an object',
+                modelName: isRecord(raw) && typeof raw.modelName === 'string' ? raw.modelName : undefined,
+                actionType: isRecord(raw) && typeof raw.actionType === 'string' ? raw.actionType : undefined,
+            };
+            getContext().logger.debug('[SyncWebSocket] dropped malformed wire delta', detail);
+            getContext().observability.breadcrumb('Dropped malformed wire delta', 'sync.websocket', 'warning', detail);
+            return null;
+        }
+        return parsed.data;
     }
     /**
-     * Handle incoming sync delta
+     * Handle incoming sync delta (untrusted wire input — validated and
+     * normalized by {@link normalizeWireDelta}; malformed deltas are dropped).
      */
     handleDelta(rawDelta) {
         const delta = this.normalizeWireDelta(rawDelta);
+        if (!delta)
+            return;
         getContext().logger.debug('Received delta', {
             action: delta.actionType,
             model: delta.modelName,
             id: delta.modelId,
             syncId: delta.id,
         });
-        // DO NOT advance `this.lastSyncId` on receipt. The runtime cursor
+        // DO NOT advance `this.cursor.lastSyncId` on receipt. The runtime cursor
         // must stay consistent with what's persisted in IDB — otherwise the
         // next `requestIncrementalSync()` (and the connect-time handshake)
         // sends an optimistic cursor and the server skips deltas that never
-        // landed in IDB. `this.lastSyncId` is advanced only in `sendAck()`,
+        // landed in IDB. `this.cursor.lastSyncId` is advanced only in `sendAck()`,
         // which is gated on `BaseSyncedStore.flushPendingDeltas`'s
         // `persistedSyncId` watermark. See Replicache's "lastMutationID
         // read in the same transaction as the client view" rule.
@@ -801,7 +631,7 @@ export class SyncWebSocket extends EventEmitter {
     /**
      * Send acknowledgment for received delta with version vector.
      *
-     * This is the SOLE forward-mover of `this.lastSyncId` for live
+     * This is the SOLE forward-mover of `this.cursor.lastSyncId` for live
      * deltas. Called by `BaseSyncedStore.flushPendingDeltas` with the
      * `persistedSyncId` watermark — i.e. only after the deltas have
      * actually committed to IDB. Keeping the cursor advance here (rather
@@ -814,9 +644,7 @@ export class SyncWebSocket extends EventEmitter {
         // these are what `requestIncrementalSync` and the connect handshake
         // will send next, and what `getLastSyncId()` reports for clean-
         // shutdown persistence.
-        if (syncId > this.lastSyncId) {
-            this.lastSyncId = syncId;
-        }
+        this.cursor.ackAdvance(syncId);
         if (this.ws?.readyState !== WebSocket.OPEN)
             return;
         this.send({
@@ -862,35 +690,6 @@ export class SyncWebSocket extends EventEmitter {
             }
         }
     }
-    /**
-     * Project the SDK's `MutationOperation[]` onto the canonical wire
-     * `CommitMessage`. This is the single serialize boundary between the SDK op
-     * type (loose `type: string`, plus an SDK-internal `options` the server never
-     * reads) and the strict wire contract. The per-field map gives compile-time
-     * drift detection (a `CommitOperation` shape change breaks here) and the lone
-     * `as` narrows the validated op `type` to the wire union — the only
-     * loosening, localized to this boundary.
-     */
-    buildCommitFrame(operations, clientTxId, causedByTaskId, reads) {
-        const payload = {
-            operations: operations.map((op) => ({
-                type: op.type,
-                model: op.model,
-                id: op.id,
-                input: op.input,
-                transactionId: op.transactionId,
-                readAt: op.readAt,
-                onStale: op.onStale,
-            })),
-            clientTxId,
-        };
-        if (causedByTaskId)
-            payload.causedByTaskId = causedByTaskId;
-        // Batch-level read-set (STORM layer): rows/groups the batch was premised on.
-        if (reads && reads.length > 0)
-            payload.reads = [...reads];
-        return { type: 'commit', payload };
-    }
     /**
      * Send a `commit` mutation request over the existing WebSocket and
      * resolve when the server's `mutation_result` frame comes back with
@@ -910,62 +709,6 @@ export class SyncWebSocket extends EventEmitter {
      * NOT auto-retry here — the caller's TransactionQueue owns retry +
      * offline replay semantics and the SDK shouldn't duplicate that logic.
      */
-    /**
-     * Defensively validate the optional `notifications` array off a commit ack.
-     * Untrusted wire data — a malformed entry is dropped rather than throwing,
-     * so a bad notification never sinks an otherwise-successful commit.
-     */
-    parseNotifications(raw) {
-        if (!Array.isArray(raw) || raw.length === 0)
-            return undefined;
-        const out = [];
-        for (const entry of raw) {
-            const parsed = staleNotificationSchema.safeParse(entry);
-            if (parsed.success)
-                out.push(parsed.data);
-        }
-        return out.length > 0 ? out : undefined;
-    }
-    /**
-     * Single instrumentation point for claim events. Every `claim_*` frame routes
-     * through here so a developer debugging a collision gets one consistent trace
-     * — a console line AND a structured capture — without each dispatch case
-     * re-deriving the row/holder shape. The wire payload is loosely typed
-     * (`Record<string, unknown>`), so this is the one place that narrows it into
-     * a {@link ClaimEvent}.
-     */
-    recordClaim(phase, payload) {
-        const str = (v) => typeof v === 'string' ? v : undefined;
-        // Targets arrive flat ({ entityType, entityId }) or nested under `target`.
-        const target = payload.target && typeof payload.target === 'object'
-            ? payload.target
-            : payload;
-        const kind = wireParticipantKindSchema.safeParse(payload.participantKind);
-        const event = {
-            phase,
-            claimId: str(payload.claimId),
-            model: str(target.entityType) ?? str(target.model),
-            id: str(target.entityId) ?? str(target.id),
-            field: str(target.field),
-            actor: str(payload.actor) ?? str(payload.heldBy),
-            participantKind: kind.success ? kind.data : undefined,
-            position: typeof payload.position === 'number' ? payload.position : undefined,
-            reason: str(payload.policyReason) ?? str(payload.reason),
-        };
-        const message = formatClaim(event);
-        // A rejection or lost lease is the collision a developer is actively
-        // debugging → warn (shows at the default log level). The routine events
-        // (acquired/queued/granted/expired) are debug-only so they never drown the
-        // console until you opt in with `new Ablo({ debug: true })`.
-        const isCollision = phase === 'rejected' || phase === 'lost';
-        const ctx = getContext();
-        if (isCollision)
-            ctx.logger.warn(message);
-        else
-            ctx.logger.debug(message);
-        ctx.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
-        ctx.observability.captureClaim(event);
-    }
     sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             return Promise.reject(this.notConnectedError('commit'));
@@ -981,7 +724,7 @@ export class SyncWebSocket extends EventEmitter {
                 // an open turn — keeps the wire shape stable for sessions
                 // that don't use turns. Servers that don't know the field
                 // ignore it; newer servers stamp it onto every delta.
-                const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
+                const frame = buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
                 this.ws.send(JSON.stringify(frame));
             }
             catch (error) {
@@ -1003,7 +746,7 @@ export class SyncWebSocket extends EventEmitter {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             throw this.notConnectedError('commit');
         }
-        const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
+        const frame = buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
         this.ws.send(JSON.stringify(frame));
     }
     /**
@@ -1281,7 +1024,7 @@ export class SyncWebSocket extends EventEmitter {
     disconnect() {
         this.isManualClose = true;
         this.stopCatchupInterval();
-        this.stopHeartbeat();
+        this.heartbeat.stop();
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
@@ -1291,67 +1034,6 @@ export class SyncWebSocket extends EventEmitter {
             this.ws = null;
         }
     }
-    /**
-     * Application-level heartbeat. Every `HEARTBEAT_INTERVAL_MS` while
-     * `OPEN`, send `{ type: 'ping' }` and arm a `HEARTBEAT_TIMEOUT_MS`
-     * watchdog. Any inbound frame (handled in `onmessage`) clears the
-     * watchdog. If the watchdog fires, we treat the connection as
-     * zombie and force-close it — `onclose` then triggers the existing
-     * reconnect path.
-     *
-     * Why both sides need this:
-     *  - The server sends RFC 6455 protocol pings via `ws.ping()` every
-     *    30s. Browsers auto-respond with a pong but DO NOT expose either
-     *    frame to JavaScript, so the client is blind to its own keepalive.
-     *  - On a half-open TCP (laptop wake, NAT timeout, mobile handoff)
-     *    the browser may keep `readyState === OPEN` for minutes before
-     *    the OS surfaces the broken connection. App-level traffic is
-     *    the only signal we can observe.
-     */
-    startHeartbeat() {
-        this.stopHeartbeat();
-        this.heartbeatTimer = setInterval(() => {
-            if (this.ws?.readyState !== WebSocket.OPEN)
-                return;
-            // Send the ping. If `send` throws, the socket is already dead —
-            // force-close so onclose triggers the reconnect cycle.
-            try {
-                this.ws.send(JSON.stringify({ type: 'ping' }));
-            }
-            catch (err) {
-                getContext().observability.captureWebSocketError({
-                    context: 'heartbeat-send-failed',
-                    error: err instanceof Error ? err.message : String(err),
-                });
-                this.forceClose('heartbeat-send-failed');
-                return;
-            }
-            // Arm the timeout. ANY inbound message clears it (see onmessage).
-            // We don't require an explicit `pong` — a delta or any other frame
-            // is equally good proof-of-life.
-            if (this.heartbeatTimeoutTimer)
-                clearTimeout(this.heartbeatTimeoutTimer);
-            this.heartbeatTimeoutTimer = setTimeout(() => {
-                getContext().observability.captureWebSocketError({
-                    context: 'heartbeat-timeout',
-                });
-                this.forceClose('heartbeat-timeout');
-            }, SyncWebSocket.HEARTBEAT_TIMEOUT_MS);
-        }, SyncWebSocket.HEARTBEAT_INTERVAL_MS);
-    }
-    stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-        this.clearHeartbeatTimeout();
-    }
-    clearHeartbeatTimeout() {
-        if (this.heartbeatTimeoutTimer) {
-            clearTimeout(this.heartbeatTimeoutTimer);
-            this.heartbeatTimeoutTimer = null;
-        }
-    }
     /**
      * Force-close the socket from the client side using a private 4xxx
      * code. Callers expect `onclose` to fire; that handler runs the
@@ -1416,11 +1098,19 @@ export class SyncWebSocket extends EventEmitter {
      */
     notConnectedError(action) {
         const d = this.getConnectionDiagnostics();
-        let detail;
+        // Session-latched is NOT a transient transport hiccup: reconnection is
+        // suppressed until re-auth (or the store's credential re-mint clears the
+        // latch), so retrying can never succeed. Reject with the PERMANENT
+        // session type — `isPermanentError` surfaces it to the caller as
+        // "re-authenticate" instead of parking the write for a reconnect that
+        // will never happen (the old `ws_not_ready` retry-forever hazard).
         if (d.sessionErrorDetected) {
-            detail = 'session_error_suppressed_reconnect';
+            return Object.assign(new SyncSessionError(`SyncWebSocket not connected — cannot send ${action}: session expired` +
+                (d.lastCloseReason ? ` (${d.lastCloseReason})` : '') +
+                '; re-authenticate'), { diagnostics: d });
         }
-        else if (d.isManualClose) {
+        let detail;
+        if (d.isManualClose) {
             detail = 'manual_close';
         }
         else if (d.isConnecting) {
@@ -1455,47 +1145,31 @@ export class SyncWebSocket extends EventEmitter {
     getSyncGroups() {
         return this.options.syncGroups;
     }
+    // Cursor accessors — thin delegates; the state + semantics live in
+    // sync/syncCursor.ts (SyncCursor).
     /**
      * Update last sync ID (for persistence)
      */
     setLastSyncId(syncId) {
-        this.lastSyncId = syncId;
-    }
-    /**
-     * Get current version vector
-     */
-    getVersionVector() {
-        return { ...this.versionVector };
-    }
-    /**
-     * Update version vector for specific entity type
-     */
-    updateVersionVector(entityType, version) {
-        this.versionVector[entityType] = Math.max(this.versionVector[entityType] || 0, version);
-    }
-    /**
-     * Set version vector (for initialization)
-     */
-    setVersionVector(versions) {
-        this.versionVector = { ...versions };
+        this.cursor.setLastSyncId(syncId);
     }
     /**
      * Update sync cursor (for incremental sync)
      */
     setSyncCursor(cursor) {
-        this.syncCursor = cursor;
+        this.cursor.setSyncCursor(cursor);
     }
     /**
      * Get current sync cursor
      */
     getSyncCursor() {
-        return this.syncCursor;
+        return this.cursor.getSyncCursor();
     }
     /**
      * Get the highest syncId seen this session (for persistence on clean shutdown)
      */
     getLastSyncId() {
-        return this.lastSyncId || 0;
+        return this.cursor.getLastSyncId();
     }
     /**
      * Linear-style incremental sync request
@@ -1516,9 +1190,12 @@ export class SyncWebSocket extends EventEmitter {
         this.send({
             type: 'sync_request',
             payload: {
-                cursor: this.syncCursor, // Always send lastSyncId to ensure server uses client's current position
-                lastSyncId: this.lastSyncId,
+                cursor: this.cursor.syncCursor, // Always send lastSyncId to ensure server uses client's current position
+                lastSyncId: this.cursor.lastSyncId,
                 capabilities: capsArr,
+                // Protocol handshake: the server rejects an out-of-range version with
+                // WS close 4010 before serving any deltas (wire/protocolVersion.ts).
+                protocolVersion: PROTOCOL_VERSION,
             },
         });
     }
@@ -1541,9 +1218,16 @@ export class SyncWebSocket extends EventEmitter {
         });
     }
     /**
-     * Handle sync response from server
+     * Handle sync response from server. Untrusted wire input — the envelope
+     * fields are narrowed defensively and every delta is validated through
+     * {@link normalizeWireDelta} (exactly once each; malformed ones drop out
+     * of the batch).
      */
-    handleSyncResponse(payload) {
+    handleSyncResponse(rawPayload) {
+        const payload = isRecord(rawPayload) ? rawPayload : {};
+        const rawDeltas = Array.isArray(payload.deltas)
+            ? payload.deltas
+            : null;
         // Cursor reconciliation — Linear-style handshake. The server stamps
         // its authoritative `currentSyncId` on every sync_response. If our
         // local cursor is AHEAD of the server, our local view has somehow
@@ -1563,24 +1247,30 @@ export class SyncWebSocket extends EventEmitter {
         // empty-delta responses eliminates this benign false positive while
         // still catching the real corruption case (server head < local AND
         // server has nothing new to send).
-        const hasDeltas = Array.isArray(payload.deltas) && payload.deltas.length > 0;
+        const hasDeltas = rawDeltas !== null && rawDeltas.length > 0;
         if (!hasDeltas && typeof payload.currentSyncId === 'number') {
             const serverHead = payload.currentSyncId;
-            if (serverHead < this.lastSyncId) {
+            if (serverHead < this.cursor.lastSyncId) {
                 getContext().logger.debug('[SyncWebSocket] local cursor ahead of server head — resetting and resyncing', {
-                    local: this.lastSyncId,
+                    local: this.cursor.lastSyncId,
                     server: serverHead,
-                    drift: this.lastSyncId - serverHead,
+                    drift: this.cursor.lastSyncId - serverHead,
                 });
-                getContext().observability.breadcrumb('Local sync cursor diverged from server — reset', 'sync.websocket', 'warning', { local: this.lastSyncId, server: serverHead });
-                this.lastSyncId = serverHead;
+                getContext().observability.breadcrumb('Local sync cursor diverged from server — reset', 'sync.websocket', 'warning', { local: this.cursor.lastSyncId, server: serverHead });
+                this.cursor.lastSyncId = serverHead;
                 // Fire a follow-up incremental sync to re-deliver anything we
                 // were missing. Fire-and-forget — the next response will go
                 // through this same path. The infinite-loop concern is bounded
-                // by the `serverHead < this.lastSyncId` strict-less check: once
+                // by the `serverHead < this.cursor.lastSyncId` strict-less check: once
                 // we've reset to `serverHead`, the next response with the same
-                // (or higher) `currentSyncId` won't re-enter this branch.
-                void this.requestIncrementalSync();
+                // (or higher) `currentSyncId` won't re-enter this branch. A `.catch`
+                // (not `void`) so a failed send logs instead of surfacing as an
+                // unhandled rejection.
+                this.requestIncrementalSync().catch((e) => {
+                    getContext().observability.breadcrumb('Post-cursor-reset sync request failed', 'sync.websocket', 'warning', {
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                });
             }
         }
         if (payload.requiresBootstrap) {
@@ -1588,49 +1278,53 @@ export class SyncWebSocket extends EventEmitter {
             return;
         }
         // Process incremental deltas
-        if (payload.deltas && Array.isArray(payload.deltas)) {
+        if (rawDeltas) {
             // Process all deltas from sync response - store handles idempotency.
-            // Same receive-boundary normalization as handleDelta — catch-up
-            // replays from older servers carry string ids too.
-            const newDeltas = payload.deltas.map((d) => this.normalizeWireDelta(d));
+            // Same receive-boundary validation + normalization as handleDelta —
+            // catch-up replays from older servers carry string ids too, and
+            // malformed deltas drop out of the batch instead of being applied.
+            const newDeltas = [];
+            for (const d of rawDeltas) {
+                const delta = this.normalizeWireDelta(d);
+                if (delta)
+                    newDeltas.push(delta);
+            }
             if (newDeltas.length > 0) {
-                // DO NOT pre-advance `this.lastSyncId` here. Same reasoning as
+                // DO NOT pre-advance `this.cursor.lastSyncId` here. Same reasoning as
                 // `handleDelta`: the runtime cursor must stay consistent with
                 // IDB. The delta_batch event routes through
                 // `BaseSyncedStore.processDeltaWithBatching` →
                 // `flushPendingDeltas`, which calls `acknowledge()` with the
                 // honest `persistedSyncId` once IDB commits. That ack is what
-                // moves `this.lastSyncId` forward.
+                // moves `this.cursor.lastSyncId` forward.
                 // Emit ALL deltas as a single batch event
                 this.emit('delta_batch', newDeltas);
             }
         }
-        // Update cursors and versions
-        if (payload.newCursor) {
-            this.syncCursor = payload.newCursor;
+        // Update cursor. (`newVersions` from pre-cutover servers is ignored —
+        // the version vector was removed in W4a; `sync_id` is the causality token.)
+        if (typeof payload.newCursor === 'string' && payload.newCursor) {
+            this.cursor.syncCursor = payload.newCursor;
         }
-        else if (payload.cursor) {
-            this.syncCursor = payload.cursor;
-        }
-        if (payload.newVersions) {
-            Object.assign(this.versionVector, payload.newVersions);
+        else if (typeof payload.cursor === 'string' && payload.cursor) {
+            this.cursor.syncCursor = payload.cursor;
         }
     }
     /**
      * Handle bootstrap response from server
      */
     handleBootstrapResponse(payload) {
-        // Emit bootstrap data for processing
+        // Emit bootstrap data for processing. (A `version` field from
+        // pre-cutover servers is ignored — version vector removed in W4a.)
+        // Field-wise typeof guards mirror the cursor handling above: the frame
+        // is server-produced, so coercion only bites on malformed frames.
+        const p = (payload && typeof payload === 'object' ? payload : {});
         this.emit('bootstrap_data', {
-            entityType: payload.entityType,
-            data: payload.data,
-            isComplete: payload.isComplete,
-            cursor: payload.cursor,
+            entityType: typeof p.entityType === 'string' ? p.entityType : '',
+            data: p.data,
+            isComplete: p.isComplete === true,
+            cursor: typeof p.cursor === 'string' ? p.cursor : undefined,
         });
-        // Update version vector if provided
-        if (payload.version && payload.entityType) {
-            this.updateVersionVector(payload.entityType.toLowerCase(), payload.version);
-        }
     }
     /**
      * Handle presence update from server. The wire frame's payload is