@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/SyncWebSocket.js

@@ -1,22 +1,42 @@
 /**
- * SyncWebSocket - Manages WebSocket connection to Go sync engine
- *
- * Handles:
- * - WebSocket lifecycle (connect, reconnect, disconnect)
- * - Delta reception and processing
- * - Multi-tab support
- * - Automatic reconnection with exponential backoff
+ * Manages the WebSocket connection to the sync server. It owns the socket
+ * lifecycle (connect, reconnect, disconnect), receives and validates the
+ * incoming delta stream, sends commits and claims over the same socket, and
+ * reconnects automatically with exponential backoff. Consumers subscribe to its
+ * typed events (see {@link CoreSyncEventMap}) to react to deltas, presence, and
+ * connection changes.
  */
 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 '../wire/delta.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
+/**
+ * How often, while connected, the client polls for any deltas whose best-effort
+ * broadcast was lost in transit. This is a client-side eventual-consistency
+ * setting, not part of the wire contract, so the server derives nothing from
+ * it. That it currently equals the 30-second ping is a coincidence, not a
+ * guarantee.
+ */
+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.
+// Consumers pass their own event types as the TCollaboration generic parameter.
 export class SyncWebSocket extends EventEmitter {
     /**
      * Subscribe to events with automatic cleanup.
@@ -47,20 +67,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 30 seconds and force-close after a
+     * 10-second silence. The {@link HeartbeatController} holds the timing and the
+     * zombie-socket rationale; the closures below are the only socket access it
+     * 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 +108,22 @@ export class SyncWebSocket extends EventEmitter {
     lastCloseReason = null;
     lastForceCloseReason = null;
     sessionErrorAt = null;
-    lastSyncId;
-    versionVector;
-    syncCursor = null;
+    /**
+     * Sync-position state: the lastSyncId watermark, version vector, and server
+     * cursor. The advance discipline is documented at `sendAck` and `handleDelta`;
+     * the state itself lives in {@link SyncCursor}.
+     */
+    cursor;
     /** Registered collaboration event keys (colon format) for dispatch in onmessage */
     collaborationEventTypes;
+    /**
+     * A minimal session adapter handed to the inbound frame dispatch table
+     * ({@link dispatchWsFrame}). It exposes only the members the handlers touch;
+     * the closure members read live state so a reassignment here (for example the
+     * `pendingSubscriptions` reset on close) cannot strand a handler 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
@@ -101,10 +132,10 @@ export class SyncWebSocket extends EventEmitter {
      */
     pendingMutations = new Map();
     /**
-     * In-flight `claim` requests keyed by claimId. Resolved when the
-     * matching `claim_ack` arrives, or rejected on timeout/disconnect.
-     * Same shape as pendingMutations — Phoenix-style request/response
-     * over a multiplexed connection.
+     * In-flight `claim` requests keyed by claimId. Resolved when the matching
+     * `claim_ack` arrives, or rejected on timeout or disconnect — the same
+     * request/response pattern as `pendingMutations`, multiplexed over the one
+     * connection.
      */
     pendingClaims = new Map();
     /**
@@ -118,28 +149,17 @@ export class SyncWebSocket extends EventEmitter {
     pendingSubscriptions = [];
     constructor(options) {
         super();
-        // Construct WebSocket URL from base Go server URL
+        // Construct the WebSocket URL from the base server URL.
         const baseUrl = options.baseUrl || options.url || "http://localhost:8080";
         const wsProtocol = baseUrl.startsWith('https') ? 'wss' : 'ws';
         const wsUrl = baseUrl.replace(/^https?/, wsProtocol) + '/api/sync/ws';
         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 +168,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 reassigned members 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 +196,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 +215,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
@@ -182,18 +235,18 @@ export class SyncWebSocket extends EventEmitter {
         }
         this.isConnecting = true;
         this.isManualClose = false;
-        // Pattern: one credential, server-resolved identity. The bearer travels
-        // in a `Sec-WebSocket-Protocol` value (built below), NOT the URL. The
-        // server is bearer-only (`apiKeyProvider`) and resolves identity from the
-        // verified token — userId/organizationId are NEVER read from URL params.
+        // One credential, server-resolved identity. The bearer travels in a
+        // `Sec-WebSocket-Protocol` value (built below), not the URL. The server is
+        // bearer-only and resolves identity from the verified token; userId and
+        // organizationId are never read from URL parameters.
         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
-        // capability-token path activates instead of session auth.
+        // Participant kind — defaults to `user` for session connections. Agent
+        // runtimes pass `'agent'` so the server's capability-token path activates
+        // instead of session auth.
         if (this.options.kind && this.options.kind !== 'user') {
             params.set('kind', this.options.kind);
         }
@@ -202,13 +255,13 @@ export class SyncWebSocket extends EventEmitter {
             params.append('syncGroups', group);
         });
         const wsUrl = `${this.options.url}?${params.toString()}`;
-        // Carry the bearer in a `Sec-WebSocket-Protocol` value, NOT the URL. A
-        // browser can't set an Authorization header on a WS, but it CAN offer
-        // subprotocols — and unlike the query string, those don't land in ALB
-        // access logs, proxies, or browser history. The server reads
-        // `ablo.bearer.<token>` and selects the real `ablo.sync.v1` protocol,
-        // never echoing the token-bearing value back. (Token is the raw ek_/rk_,
-        // which is subprotocol-token-safe — alphanumerics + `_`.)
+        // Carry the bearer in a `Sec-WebSocket-Protocol` value, not the URL. A
+        // browser cannot set an Authorization header on a WebSocket, but it can
+        // offer subprotocols — and unlike the query string, those do not land in
+        // load-balancer access logs, proxies, or browser history. The server reads
+        // `ablo.bearer.<token>` and selects the real `ablo.sync.v1` protocol, never
+        // echoing the token-bearing value back. The token is the raw `ek_`/`rk_`,
+        // which is safe as a subprotocol value (alphanumerics and `_`).
         const authToken = this.resolveAuthToken();
         const protocols = authToken
             ? [`${WS_BEARER_SUBPROTOCOL_PREFIX}${authToken}`, WS_SYNC_SUBPROTOCOL]
@@ -234,11 +287,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 field —
+        // see there), so a handler firing late, after `connect()` has replaced the
+        // socket, can never clobber the new connection's shared state. Without this
+        // guard, an old socket's `onclose` would unconditionally run `this.ws =
+        // null; stopCatchupInterval(); stopHeartbeat()` — a reconnect during close
+        // teardown then orphaned the fresh socket (a 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 +313,69 @@ 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, so this interval guarantees eventual consistency by
+            // fetching any deltas that were committed 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 the application-level heartbeat (see HeartbeatController).
+            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
+                // 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 });
-                        }
-                    }
-                }
+                // Dispatch by frame type (see dispatchWsFrame). The session adapter
+                // exposes only the members the handlers touch; keepalives, the older
+                // bare-delta form, and collaboration events are all routed there too.
+                dispatchWsFrame(this.frameSession, message);
             }
             catch (error) {
                 getContext().observability.captureWebSocketError({
@@ -627,7 +384,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()) {
@@ -635,8 +394,8 @@ export class SyncWebSocket extends EventEmitter {
                 this.emit('error', new AbloConnectionError('Network is offline', { code: 'bootstrap_offline' }));
                 return;
             }
-            // After session error, suppress Sentry capture — the root cause is already reported.
-            // Still emit so SyncedStore can update UI state.
+            // After a session error, suppress error capture — the root cause is
+            // already reported. Still emit so the store can update UI state.
             const error = new AbloConnectionError(`WebSocket connection failed`);
             if (!this._sessionErrorDetected) {
                 getContext().observability.captureWebSocketError({
@@ -646,7 +405,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 +432,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 +475,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,21 +506,24 @@ 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 itself.
                 this.emit('disconnected', event);
                 return;
             }
             // Handshake failure: `onclose` fired before `onopen` ever did, so the
-            // server rejected the upgrade (typically 401/403 on a bad cookie, but
-            // could also be a CORS/origin reject or an LB 5xx). The browser hides
-            // the HTTP status behind code 1006, so we can't tell which from here.
+            // server rejected the upgrade (typically 401/403 on a bad cookie, but it
+            // could also be a CORS/origin reject or a load-balancer 5xx). The browser
+            // hides the HTTP status behind code 1006, so we cannot tell which from
+            // here.
             //
-            // Emit a dedicated event and SKIP the internal reconnect — the owner
-            // (SyncedStore / ConnectionStore) should run an auth-validating HTTP
-            // probe to distinguish session expiry from a transient network issue
-            // and transition the UI accordingly. Reconnecting blindly is what
-            // produced the infinite "offline → reconnecting → offline" loop on
-            // stale cookies.
+            // Emit a dedicated event and skip the internal reconnect — the owner
+            // should run an auth-validating HTTP probe to distinguish session expiry
+            // from a transient network issue and transition the UI accordingly.
+            // Reconnecting blindly is what produced the infinite
+            // "offline → reconnecting → offline" loop on stale cookies.
             if (!everOpened && !this.isManualClose) {
                 getContext().observability.captureWebSocketError({
                     context: 'handshake-failed-close',
@@ -756,67 +542,97 @@ 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.
+     * Validates and normalizes a wire delta at the receive boundary — the single
+     * seam every inbound delta (a `delta` frame, a batch element, a `sync_response`
+     * replay, or the older bare frame) passes through before it is emitted,
+     * persisted, or allowed to advance any watermark.
+     *
+     * Normalization keeps already-deployed servers compatible:
+     *  - `id`: the contract says `number`, but some servers have sent the raw
+     *    Postgres BIGINT serialization — a string — and every downstream watermark
+     *    gate treats a string as invalid, so acks are withheld, the resume cursor
+     *    never advances, and every reconnect replays from zero. Coerce it once here.
+     *  - `transactionId` / `createdBy`: the server projection sends these as
+     *    nullable (and `createdBy` as a nested reference); the client contract
+     *    types them as optional strings and never reads them, so normalize them to
+     *    absent rather than reject every real server delta.
+     *
+     * Validation runs `clientSyncDeltaSchema.safeParse`, the canonical wire
+     * contract. A frame that fails is dropped (returns `null`) with a debug log
+     * and an observability breadcrumb; it is never applied. There is 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
-        // 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()`,
-        // which is gated on `BaseSyncedStore.flushPendingDeltas`'s
-        // `persistedSyncId` watermark. See Replicache's "lastMutationID
-        // read in the same transaction as the client view" rule.
+        // Do not advance `this.cursor.lastSyncId` on receipt. The runtime cursor
+        // must stay consistent with what has been persisted locally; otherwise the
+        // next `requestIncrementalSync()` (and the connect-time handshake) would
+        // send an optimistic cursor and the server would skip deltas that never
+        // landed in local storage. `this.cursor.lastSyncId` advances only in
+        // `sendAck()`, which the store gates on its persisted-syncId watermark, so
+        // the cursor is never read ahead of the persisted client view.
         //
-        // Version vector is also intentionally NOT updated here for the
-        // same reason — left to the persistence-gated path.
+        // The version vector is intentionally not updated here for the same reason;
+        // it is left to the persistence-gated path.
         // Emit delta for processing. Ack will be sent by SyncedStore after persistence.
         this.emit('delta', delta);
     }
     /**
-     * Send acknowledgment for received delta with version vector.
-     *
-     * This is the SOLE forward-mover of `this.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
-     * than at receipt in `handleDelta`/`handleSyncResponse`) means the
-     * cursor never gets ahead of the persisted view, so reconnect/
-     * catch-up requests can't accidentally skip un-persisted deltas.
+     * Acknowledges received deltas up to the given syncId. This is the only place
+     * `this.cursor.lastSyncId` moves forward for live deltas. The store calls it
+     * with its persisted-syncId watermark — that is, only after the deltas have
+     * committed to local storage. Advancing the cursor here, rather than at
+     * receipt in `handleDelta` or `handleSyncResponse`, keeps the cursor from
+     * getting ahead of the persisted view, so reconnect and catch-up requests
+     * cannot skip un-persisted deltas.
      */
     sendAck(syncId) {
         // Advance the local cursor *and* the version vector for this ack —
         // 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({
@@ -863,109 +679,16 @@ 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
-     * the same `clientTxId`. The wire-level frame is `{ type: 'commit',
-     * payload: { operations, clientTxId } }` — matching the
-     * `handleCommit` path on `apps/sync-server/src/hub/Hub.ts` (see the
-     * dispatch at Hub.ts:737).
+     * Sends a `commit` mutation request over the existing WebSocket and resolves
+     * when the server's `mutation_result` frame comes back with the same
+     * `clientTxId`. The wire frame is `{ type: 'commit', payload: { operations,
+     * clientTxId } }`.
      *
-     * Historical naming note: this was originally `sendBatchAck` back when
-     * the Go sync-engine used a GraphQL `batchAck` mutation. The TS
-     * sync-server uses `type: 'commit'` over WebSocket exclusively. The
-     * method name now matches the wire protocol so the ack/commit naming
-     * confusion stops here.
-     *
-     * Times out after 15s of silence from the server. The socket may close
-     * during an in-flight mutation (network flap, server restart); we do
-     * 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.
+     * Times out after 15 seconds of silence from the server. The socket may close
+     * during an in-flight mutation (a network flap, a server restart); this does
+     * not auto-retry — the caller's transaction queue owns retry and offline
+     * replay, and the SDK does not duplicate that logic.
      */
-    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 +704,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,25 +726,18 @@ 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));
     }
     /**
-     * Activate a participant claim on this connection. Multiplexed
-     * subscription pattern (Phoenix Channels / Pusher) — the same
-     * connection can hold N concurrent claims, each scoped to a
-     * different set of sync groups.
+     * Activates a participant claim on this connection. One connection can hold
+     * several concurrent claims at once, each scoped to a different set of sync
+     * groups, so the SDK reuses the existing connection instead of opening a
+     * separate socket per scope.
      *
-     * Returns a promise that resolves with the server-canonicalized
-     * `syncGroups` and effective `ttlSeconds` once `claim_ack` arrives,
-     * or rejects with a typed error on `success: false` ack /
-     * timeout / disconnect.
-     *
-     * Why this exists: the old scoped-participant path opened a separate
-     * WS per scope. With claims, the SDK reuses the existing session/agent
-     * connection — one TCP, N logical participants. See
-     * `apps/sync-server/docs/PARTICIPANT_CLAIMS.md` for the migration
-     * framing (Phase A.1).
+     * Returns a promise that resolves with the server-canonicalized `syncGroups`
+     * and effective `ttlSeconds` once `claim_ack` arrives, or rejects with a typed
+     * error on a failed ack, a timeout, or a disconnect.
      */
     sendClaim(claimId, syncGroups, options) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
@@ -1086,22 +802,21 @@ export class SyncWebSocket extends EventEmitter {
         }
     }
     /**
-     * Move this connection's READ interest — replace the connection-level
-     * sync groups mid-session as the user opens/closes entities. This is the
-     * area-of-interest (AOI) navigation primitive: the server fans out
-     * deltas only for groups currently in view, instead of the frozen set
-     * chosen at connect.
+     * Moves this connection's read interest — replaces the connection-level sync
+     * groups mid-session as the user opens and closes entities. This is the
+     * area-of-interest navigation primitive: the server fans out deltas only for
+     * the groups currently in view, rather than the fixed set chosen at connect.
      *
-     * Full-set replace semantics — pass the complete new group list, not a
-     * delta. Resolves with the server's effective set once `subscription_ack`
-     * arrives; rejects (typed) on a scope denial (a restricted `rk_` key
-     * requesting a group outside its allowlist), timeout, or disconnect. On
-     * success the new set is recorded as `options.syncGroups` so a later
-     * reconnect re-subscribes to current interest, not the connect-time set.
+     * This is a full-set replace: pass the complete new group list, not a delta.
+     * Resolves with the server's effective set once `subscription_ack` arrives;
+     * rejects (with a typed error) on a scope denial (a restricted `rk_` key
+     * requesting a group outside its allowlist), a timeout, or a disconnect. On
+     * success the new set is recorded as `options.syncGroups`, so a later reconnect
+     * re-subscribes to the current interest rather than the connect-time set.
      *
-     * Distinct from {@link sendClaim} (write-claim, per-op, TTL'd) — this is
-     * the read side and carries no capability token of its own; it's bounded
-     * by the connection credential's grant.
+     * Distinct from {@link sendClaim} (a write claim, per operation, with a TTL):
+     * this is the read side, carries no capability token of its own, and is
+     * bounded by the connection credential's grant.
      */
     updateSubscription(syncGroups, options) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
@@ -1136,9 +851,9 @@ export class SyncWebSocket extends EventEmitter {
         });
     }
     /**
-     * Compatibility setter for direct SyncWebSocket users. The SDK-owned
-     * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
-     * shared credential source instead of this copied value.
+     * Sets a fixed credential for callers that construct the socket directly. The
+     * SDK instead supplies `getAuthToken`, so reconnects read the shared
+     * credential source rather than this copied value.
      */
     setCapabilityToken(token) {
         this.options.capabilityToken = token;
@@ -1233,17 +948,17 @@ export class SyncWebSocket extends EventEmitter {
         if (this._sessionErrorDetected) {
             return;
         }
-        // Don't attempt reconnection while offline.
-        // SyncedStore.handleNetworkOnline() owns the offline→online transition:
-        // it bootstraps first, then calls syncWebSocket.connect() explicitly.
-        // Self-reconnecting here would bypass the bootstrap gate and cause stale data.
+        // Don't attempt reconnection while offline. The owning store manages the
+        // offline→online transition: it bootstraps first, then calls `connect()`
+        // explicitly. Self-reconnecting here would bypass that bootstrap gate and
+        // surface stale data.
         if (!getContext().onlineStatus.isOnline()) {
             this.emit('reconnecting', { attempt: this.reconnectAttempts + 1, delay: 0 });
             return;
         }
-        // Give up after MAX_RECONNECT_ATTEMPTS consecutive failures.
-        // The user can recover by refreshing or when network comes back online
-        // (handleNetworkOnline resets attempts and reconnects).
+        // Give up after MAX_RECONNECT_ATTEMPTS consecutive failures. The user can
+        // recover by refreshing, or the store resets the attempt count and
+        // reconnects when the network returns.
         if (this.reconnectAttempts >= SyncWebSocket.MAX_RECONNECT_ATTEMPTS) {
             this.emit('reconnect_failed', { attempts: this.reconnectAttempts });
             return;
@@ -1281,7 +996,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 +1006,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 +1070,19 @@ export class SyncWebSocket extends EventEmitter {
      */
     notConnectedError(action) {
         const d = this.getConnectionDiagnostics();
-        let detail;
+        // A session-latched socket 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
+        // error type — `isPermanentError` surfaces it to the caller as
+        // "re-authenticate" instead of parking the write for a reconnect that will
+        // never happen.
         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) {
@@ -1444,10 +1106,10 @@ export class SyncWebSocket extends EventEmitter {
         else {
             detail = 'never_connected';
         }
-        // Typed so it lands in the AbloError hierarchy AND `isPermanentError`
-        // sees a transient transport failure (retry on reconnect, don't roll
-        // back). `diagnostics` stays a property — the queue's failure log walks
-        // the cause chain for it.
+        // Typed so it lands in the AbloError hierarchy and `isPermanentError` sees a
+        // transient transport failure (retry on reconnect, don't roll back).
+        // `diagnostics` stays a property — the queue's failure log walks the cause
+        // chain for it.
         const err = Object.assign(new AbloConnectionError(`SyncWebSocket not connected — cannot send ${action} (${detail})`, { code: 'ws_not_ready' }), { diagnostics: d });
         return err;
     }
@@ -1455,50 +1117,34 @@ export class SyncWebSocket extends EventEmitter {
     getSyncGroups() {
         return this.options.syncGroups;
     }
+    // Cursor accessors — thin delegates; the state and semantics live in
+    // 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
+     * Requests an incremental sync from the server, starting at the current cursor.
      */
     async requestIncrementalSync() {
         if (this.ws?.readyState !== WebSocket.OPEN) {
@@ -1516,9 +1162,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
+                // WebSocket close code 4010 before serving any deltas.
+                protocolVersion: PROTOCOL_VERSION,
             },
         });
     }
@@ -1541,46 +1190,56 @@ 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) {
-        // 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
-        // diverged (corrupted metadata, future regression reintroducing an
-        // eager-advance, IDB lying about a successful commit). Trust the
-        // server, reset the cursor, and request another sync so any deltas
-        // we *should* have applied get re-delivered. Backward-compatible
-        // when the field is absent (older server build) — we just skip the
-        // reconciliation step.
+    handleSyncResponse(rawPayload) {
+        const payload = isRecord(rawPayload) ? rawPayload : {};
+        const rawDeltas = Array.isArray(payload.deltas)
+            ? payload.deltas
+            : null;
+        // Cursor reconciliation. The server stamps its authoritative `currentSyncId`
+        // on every sync_response. If our local cursor is ahead of the server, our
+        // local view has somehow diverged (corrupted metadata, a regression that
+        // reintroduced an eager advance, or local storage lying about a successful
+        // commit). Trust the server, reset the cursor, and request another sync so
+        // any deltas we should have applied get re-delivered. When the field is
+        // absent (an older server build) we simply skip this step.
         //
-        // We only reconcile when the response carries NO deltas. If deltas
-        // are present, they'll advance our cursor through the normal
-        // persistence-gated path anyway — and the in-flight request/response
-        // round-trip means the snapshot's `currentSyncId` is naturally a
-        // few syncIds behind our locally-advanced cursor at receive time
-        // (live deltas may have landed in the meantime). Restricting to
-        // 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;
+        // We only reconcile when the response carries no deltas. If deltas are
+        // present they advance our cursor through the normal persistence-gated path
+        // anyway — and the in-flight round-trip means the snapshot's `currentSyncId`
+        // is naturally a few syncIds behind our locally-advanced cursor at receive
+        // time (live deltas may have landed in the meantime). Restricting to
+        // empty-delta responses eliminates that benign false positive while still
+        // catching the real corruption case (server head < local, and the server
+        // has nothing new to send).
+        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,58 +1247,61 @@ 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 the bootstrap data for processing. (A `version` field from older
+        // servers is ignored; the version vector is no longer used.) The typeof
+        // guards mirror the cursor handling above: the frame is server-produced, so
+        // coercion only bites on a malformed frame.
+        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
-     * forwarded as-is so every consumer (web entity cache,
-     * PresenceStream, agent runtime) reads from the same shape.
-     * Stripping fields here was a prior bug — it silently dropped
-     * `kind`, `activity`, `syncGroups`, `isAgent` for rich consumers.
+     * Handles a presence update from the server. The wire frame's payload is
+     * forwarded as-is, so every consumer reads the same shape; stripping fields
+     * here would drop `kind`, `activity`, `syncGroups`, and `isAgent` for
+     * consumers that need them.
      *
-     * Wire frame (apps/sync-server/src/hub/types.ts PresenceUpdateMessage):
+     * The wire frame is:
      *   { type: 'presence_update', payload: { kind, userId, status,
      *     syncGroups, activity, isAgent, timestamp, activeClaims } }
      */