@abloatai/ablo 0.26.0 → 0.28.0

package/dist/sync/SyncWebSocket.js

@@ -1,16 +1,15 @@
 /**
- * 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 { AbloConnectionError, AbloError, SyncSessionError, toAbloError, } from '../errors.js';
-import { clientSyncDeltaSchema } from '../schema/sync-delta-wire.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';
@@ -24,11 +23,11 @@ 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.
+ * 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;
 /**
@@ -37,8 +36,7 @@ const CATCHUP_POLL_INTERVAL_MS = 30_000;
  */
 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.
@@ -69,10 +67,10 @@ export class SyncWebSocket extends EventEmitter {
     /** Periodic catchup interval — polls for missed deltas every 30s while connected */
     catchupInterval = null;
     /**
-     * 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.
+     * 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.
      */
     heartbeat = new HeartbeatController({
         isSocketOpen: () => this.ws?.readyState === WebSocket.OPEN,
@@ -111,20 +109,19 @@ export class SyncWebSocket extends EventEmitter {
     lastForceCloseReason = null;
     sessionErrorAt = 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`.
+     * 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;
     /**
-     * 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.
+     * 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;
     /**
@@ -135,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();
     /**
@@ -152,7 +149,7 @@ 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';
@@ -173,9 +170,9 @@ export class SyncWebSocket extends EventEmitter {
         };
         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.
+        // 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,
@@ -238,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, capabilities from URL; these are sent in sync_request
             // and ack messages to avoid stale baselines on reconnect.
             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);
         }
@@ -258,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]
@@ -290,14 +287,14 @@ export class SyncWebSocket extends EventEmitter {
      * Setup WebSocket event handlers
      */
     setupEventHandlers() {
-        // 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).
+        // 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;
@@ -337,10 +334,9 @@ export class SyncWebSocket extends EventEmitter {
             }
             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
+            // 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(() => {
@@ -355,7 +351,7 @@ export class SyncWebSocket extends EventEmitter {
                     });
                 }
             }, CATCHUP_POLL_INTERVAL_MS);
-            // Start application-level heartbeat — see sync/heartbeat.ts for rationale.
+            // Start the application-level heartbeat (see HeartbeatController).
             this.heartbeat.start();
         };
         socket.onmessage = (event) => {
@@ -366,7 +362,7 @@ export class SyncWebSocket extends EventEmitter {
                 // 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.heartbeat.clearHeartbeatTimeout();
@@ -376,10 +372,9 @@ export class SyncWebSocket extends EventEmitter {
                     });
                     return;
                 }
-                // 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.
+                // 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) {
@@ -399,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({
@@ -411,7 +406,7 @@ export class SyncWebSocket extends EventEmitter {
             this.emit('error', error);
         };
         socket.onclose = (event) => {
-            // Stale-socket close: a NEWER socket already owns the connection
+            // 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`
@@ -480,9 +475,9 @@ 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
+            // 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({
@@ -511,25 +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 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.
+                // 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',
@@ -548,28 +542,25 @@ export class SyncWebSocket extends EventEmitter {
         };
     }
     /**
-     * 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.
+     * 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 (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.
+     * 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: `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.
+     * 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(raw) {
         let candidate = raw;
@@ -614,30 +605,27 @@ export class SyncWebSocket extends EventEmitter {
             id: delta.modelId,
             syncId: delta.id,
         });
-        // 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.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.
+        // 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.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
-     * 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 —
@@ -691,23 +679,15 @@ export class SyncWebSocket extends EventEmitter {
         }
     }
     /**
-     * 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).
-     *
-     * 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.
+     * 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 } }`.
      *
-     * 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.
+     * 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.
      */
     sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
@@ -750,21 +730,14 @@ export class SyncWebSocket extends EventEmitter {
         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.
-     *
-     * 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.
+     * 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.
      *
-     * 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) {
@@ -829,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) {
@@ -879,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;
@@ -976,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;
@@ -1098,12 +1070,12 @@ export class SyncWebSocket extends EventEmitter {
      */
     notConnectedError(action) {
         const d = this.getConnectionDiagnostics();
-        // 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).
+        // 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) {
             return Object.assign(new SyncSessionError(`SyncWebSocket not connected — cannot send ${action}: session expired` +
                 (d.lastCloseReason ? ` (${d.lastCloseReason})` : '') +
@@ -1134,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;
     }
@@ -1145,8 +1117,8 @@ export class SyncWebSocket extends EventEmitter {
     getSyncGroups() {
         return this.options.syncGroups;
     }
-    // Cursor accessors — thin delegates; the state + semantics live in
-    // sync/syncCursor.ts (SyncCursor).
+    // Cursor accessors — thin delegates; the state and semantics live in
+    // SyncCursor.
     /**
      * Update last sync ID (for persistence)
      */
@@ -1172,7 +1144,7 @@ export class SyncWebSocket extends EventEmitter {
         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) {
@@ -1194,7 +1166,7 @@ export class SyncWebSocket extends EventEmitter {
                 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).
+                // WebSocket close code 4010 before serving any deltas.
                 protocolVersion: PROTOCOL_VERSION,
             },
         });
@@ -1228,25 +1200,22 @@ export class SyncWebSocket extends EventEmitter {
         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
-        // 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.
+        // 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).
+        // 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;
@@ -1314,10 +1283,10 @@ export class SyncWebSocket extends EventEmitter {
      * Handle bootstrap response from server
      */
     handleBootstrapResponse(payload) {
-        // 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.
+        // 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: typeof p.entityType === 'string' ? p.entityType : '',
@@ -1327,13 +1296,12 @@ export class SyncWebSocket extends EventEmitter {
         });
     }
     /**
-     * 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 } }
      */