@abloatai/ablo 0.34.1 → 0.35.0

package/dist/transaction/transport/wsTransport.js

@@ -0,0 +1,1017 @@
+/**
+ * The duplex transport: a WebSocket connection to the sync server, extracted
+ * out of the reactive engine's `SyncWebSocket` (ADR 0016). It owns the socket
+ * lifecycle (connect, reconnect with exponential backoff, disconnect, the
+ * application-level heartbeat), sends commits, claims, releases, and
+ * subscription updates over the one connection, correlates their
+ * acknowledgement frames back to awaiting callers, and dispatches every other
+ * inbound frame through {@link dispatchWsFrame}.
+ *
+ * What it deliberately does not do is materialise: deltas, sync responses,
+ * and bootstrap payloads are surfaced through protected frame hooks
+ * ({@link handleDelta} and its siblings) whose defaults just emit, so a
+ * server-side caller gets the push feed — claim grants, losses, deltas —
+ * with no store, no cursor, and no renderer. The reactive engine subclasses
+ * this and overrides the hooks with validation, cursor advancement, and
+ * bootstrap handling. The membership test (ADR 0016): a caller with no socket
+ * loses only push — it polls instead; a caller with no reactive layer loses
+ * the local copy it never wanted.
+ */
+import { EventEmitter } from 'events';
+import { AbloConnectionError, AbloError, AbloSessionError, AbloValidationError, toAbloError, } from '../errors.js';
+import { updateSubscriptionPayloadSchema } from '../coordination/schema.js';
+import { PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION } from '../wire/protocolVersion.js';
+import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
+import { buildCommitFrame } from './commitFrames.js';
+import { dispatchWsFrame, readWsInboundFrame, } from './wsFrameHandlers.js';
+import { HeartbeatController } from './heartbeat.js';
+import { noopLogger } from '../logger.js';
+import { noopSocketObservability, } from '../observability.js';
+/**
+ * Ceiling for the exponential reconnect backoff (`reconnectDelay * 2^n`,
+ * ±15% jitter). A client-side setting, not part of the wire contract.
+ */
+const MAX_RECONNECT_DELAY_MS = 30_000;
+// ---------------------------------------------------------------------------
+// Consumers pass their own event types as the TCollaboration generic parameter.
+export class WsTransport extends EventEmitter {
+    /**
+     * Subscribe to events with automatic cleanup.
+     * Returns unsubscribe function for clean disposal.
+     */
+    subscribe(event, handler) {
+        this.on(event, handler);
+        return () => this.off(event, handler);
+    }
+    /**
+     * Send a collaboration event (app-specific real-time message).
+     * The wire format is `{ type: messageType, payload: { ...payload, timestamp } }`.
+     */
+    sendCollaborationEvent(messageType, payload) {
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        this.send({
+            type: messageType.replace(/:/g, '_'), // 'document:selection' → 'document_selection' wire format
+            payload: { ...payload, timestamp: Date.now() },
+        });
+    }
+    ws = null;
+    options;
+    /** The transport's reporting ports, shared with the subclassing engine. */
+    logger;
+    observability;
+    onlineStatus;
+    reconnectAttempts = 0;
+    /** Stop retrying after this many consecutive failures (backoff caps at 30s, so ~7.5 min total) */
+    static MAX_RECONNECT_ATTEMPTS = 15;
+    reconnectTimer = null;
+    /**
+     * 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;
+    isConnecting = false;
+    isManualClose = false;
+    /** True while the owner still holds the first connection (`deferConnect`).
+     *  `connect()` is ignored until {@link allowConnect} lifts the hold. */
+    connectHeld;
+    /** When true, a session error has been detected (from any path — WS close or HTTP bootstrap).
+     *  Suppresses reconnection and Sentry error capture to avoid cascading noise. */
+    _sessionErrorDetected = false;
+    /** True once `onopen` has fired at least once on the current socket. Reset each
+     *  time a new socket is created in `connect()`. Used by `onclose` to detect
+     *  handshake failures (close before open) — the one signal we have for "the
+     *  server rejected the upgrade" since browsers hide the HTTP status (e.g.
+     *  401) behind the opaque 1006 close code. */
+    _everOpened = false;
+    /**
+     * Diagnostic snapshot of the last connection lifecycle. Persisted across
+     * the lifetime of the transport so that any subsequent "not connected"
+     * rejection can quote the actual root cause (close code + reason + when)
+     * instead of bottoming out at a generic error string. Browser WS code 1006
+     * hides the real reason, so we layer on our own signals: `forceCloseReason`
+     * captures heartbeat trips / send failures, `everOpened` distinguishes
+     * handshake reject from mid-session drop, and `sessionErrorAt` tells us
+     * whether reconnect is suppressed.
+     */
+    lastOpenAt = null;
+    lastCloseAt = null;
+    lastCloseCode = null;
+    lastCloseReason = null;
+    lastForceCloseReason = null;
+    sessionErrorAt = null;
+    /** 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
+     * timeout / disconnect. Lets consumers await a server ack for mutations
+     * sent over the same socket that streams deltas.
+     */
+    pendingMutations = new Map();
+    /**
+     * 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();
+    /**
+     * In-flight `update_subscription` frames awaiting `subscription_ack`.
+     * A FIFO queue rather than a keyed Map because the wire ack carries no
+     * correlation id — the server applies subscription updates in receive
+     * order and acks in the same order, so `shift()` on ack matches the
+     * oldest pending request. (Read-interest changes are infrequent and
+     * usually settle before the next one, so depth is ~1 in practice.)
+     */
+    pendingSubscriptions = [];
+    constructor(options) {
+        super();
+        // 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';
+        const { logger, observability, onlineStatus, deferConnect, ...connectionOptions } = options;
+        this.logger = logger ?? noopLogger;
+        this.observability = observability ?? noopSocketObservability;
+        this.onlineStatus = onlineStatus ?? { isOnline: () => true };
+        this.connectHeld = deferConnect === true;
+        this.options = {
+            url: wsUrl,
+            reconnectDelay: 1000,
+            maxReconnectDelay: MAX_RECONNECT_DELAY_MS,
+            collaborationEvents: [],
+            syncGroups: [],
+            lastSyncId: 0,
+            userId: '',
+            organizationId: '',
+            capabilities: {
+                partialBootstrap: true,
+                compressedDeltas: true,
+                streamingBootstrap: true,
+                batchedDeltas: true,
+            },
+            ...connectionOptions,
+        };
+        this.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); },
+        }, this.observability);
+        this.collaborationEventTypes = new Set(options.collaborationEvents ?? []);
+        // 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. The four materialisation handlers route
+        // through the protected hooks, so a subclass's overrides win.
+        this.frameSession = {
+            emit: (event, ...args) => this.emit(event, ...args),
+            logger: this.logger,
+            observability: this.observability,
+            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);
+            },
+        };
+    }
+    // ── Materialisation hooks ─────────────────────────────────────────────
+    //
+    // The frame dispatch routes deltas, sync responses, bootstrap payloads, and
+    // presence frames through these protected hooks. The defaults surface the
+    // raw push feed as events — enough for a socketed agent that wants claim
+    // push and change notifications without a local copy. The reactive engine
+    // overrides them with wire validation, cursor advancement, and bootstrap
+    // handling; anything it does not override keeps the transport default.
+    /**
+     * One inbound delta, straight off the wire and unvalidated. The default
+     * emits it as-is; the reactive engine's override validates against the
+     * canonical delta schema and drops anything malformed before emitting.
+     */
+    handleDelta(rawDelta) {
+        this.emit('delta', rawDelta);
+    }
+    /** A `sync_response` frame. Meaningless without a resume cursor to advance,
+     *  so the transport default does nothing. */
+    handleSyncResponse(_payload) { }
+    /** A `bootstrap_response` frame. Bootstrap is materialisation, so the
+     *  transport default does nothing. */
+    handleBootstrapResponse(_payload) { }
+    /**
+     * 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.
+     *
+     * The wire frame is:
+     *   { type: 'presence_update', payload: { kind, userId, status,
+     *     syncGroups, activity, isAgent, timestamp, activeClaims } }
+     */
+    handlePresenceUpdate(
+    // Typed as a partial presence event as well as an envelope, because both
+    // shapes genuinely arrive: the server's canonical `{ payload: {...} }`,
+    // and legacy pathways (test fixtures) that put the fields at the top
+    // level. Declaring the union up front is what lets the fallback below
+    // stay a plain read instead of a checked-off cast.
+    message) {
+        const event = 
+        // Server canonical path: `{ payload: {...} }`. Some legacy
+        // pathways emit fields at the top level (test fixtures) — fall
+        // back to reading from the message itself.
+        message.payload ?? message;
+        this.emit('presence_update', event);
+    }
+    /**
+     * Runs after the socket opens and `connected` is emitted, before the
+     * heartbeat starts. The default does nothing; the reactive engine's
+     * override runs its open ritual — presence, ack, incremental sync, and the
+     * catch-up poll.
+     */
+    onOpened() { }
+    /**
+     * Runs inside the close handler, after the socket reference is cleared and
+     * before in-flight requests are rejected. The default does nothing; the
+     * reactive engine's override stops its catch-up poll.
+     */
+    onClosed() { }
+    /**
+     * The resume position sent as the `cursor` query parameter on the upgrade.
+     * The transport itself holds no cursor — a bare connection resumes from
+     * nothing — so the default is empty; the reactive engine's override supplies
+     * its persisted sync cursor.
+     */
+    resumeCursor() {
+        return '';
+    }
+    /**
+     * Mark that a session error has been detected (e.g. 401 from HTTP bootstrap).
+     * Suppresses further reconnection attempts and Sentry error capture.
+     */
+    setSessionErrorDetected() {
+        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;
+    }
+    /**
+     * Lift the `deferConnect` hold. The owner calls this once the connection's
+     * identity and read scope are seeded; from then on `connect()` works
+     * normally, including every reconnect path.
+     */
+    allowConnect() {
+        this.connectHeld = false;
+    }
+    /**
+     * Connect to the sync engine WebSocket
+     */
+    connect() {
+        if (this.connectHeld) {
+            // Deliberately ignored, not queued: the decided answer to "connect()
+            // before the host has seeded identity" is a no-op, so an early caller
+            // can never open an unscoped connection (see deferConnect).
+            this.logger.debug('WebSocket connect ignored — the connection is still held by its host');
+            return;
+        }
+        if (this._sessionErrorDetected) {
+            this.logger.debug('WebSocket connect suppressed — session error detected');
+            return;
+        }
+        // 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) {
+            this.logger.debug('WebSocket already connected, connecting, or closing');
+            return;
+        }
+        // Note: onlineStatus is advisory — we'll try to connect and let the WebSocket
+        // handle failures. The default browser implementation reads navigator.onLine,
+        // which is unreliable but the only signal available; in Node it returns true
+        // (assume online) so the sidecar/agent path doesn't short-circuit here.
+        if (!this.onlineStatus.isOnline()) {
+            this.logger.debug('onlineStatus reports offline, but attempting connection anyway');
+        }
+        this.isConnecting = true;
+        this.isManualClose = false;
+        // 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.resumeCursor(),
+        });
+        // 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);
+        }
+        // Add sync groups if provided
+        this.options.syncGroups.forEach((group) => {
+            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 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]
+            : [WS_SYNC_SUBPROTOCOL];
+        try {
+            // Reset the handshake flag before wiring the new socket. Each connect()
+            // gets its own lifecycle — a prior successful open on a previous socket
+            // must not mask a handshake failure on the new one.
+            this._everOpened = false;
+            this.ws = new WebSocket(wsUrl, protocols);
+            this.setupEventHandlers();
+        }
+        catch (error) {
+            // WebSocket constructor can throw if URL is invalid
+            const errorMessage = error instanceof Error ? error.message : 'Failed to create WebSocket';
+            this.observability.captureWebSocketError({ context: 'create-websocket', error: errorMessage });
+            this.isConnecting = false;
+            this.emit('error', new AbloConnectionError(errorMessage, { cause: error }));
+            this.scheduleReconnect();
+        }
+    }
+    /**
+     * Setup WebSocket event handlers
+     */
+    setupEventHandlers() {
+        // 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; onClosed(); 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;
+        socket.onopen = () => {
+            if (this.ws !== socket)
+                return; // stale socket — a newer connect() owns the state
+            this.observability.breadcrumb('WebSocket connected', 'sync.websocket', 'info', {
+                reconnectAttempts: this.reconnectAttempts,
+            });
+            this.isConnecting = false;
+            this.reconnectAttempts = 0;
+            this._everOpened = true;
+            this.lastOpenAt = Date.now();
+            this.emit('connected');
+            // The subclass's open ritual (presence, ack, incremental sync,
+            // catch-up poll) runs here, between the `connected` emit and the
+            // heartbeat start — the exact position the inline code held before
+            // the split.
+            this.onOpened();
+            // Start the application-level heartbeat (see HeartbeatController).
+            this.heartbeat.start();
+        };
+        socket.onmessage = (event) => {
+            if (this.ws !== socket)
+                return; // stale socket — drop, don't feed shared state
+            try {
+                // Untrusted wire input: parse to `unknown`, then narrow through
+                // the frame-envelope guard before dispatch. Payload-level
+                // validation (deltas etc.) happens per-frame downstream.
+                const message = JSON.parse(event.data);
+                // Any inbound frame proves the socket is alive — clear the
+                // heartbeat-timeout timer so we don't false-trip force-close
+                // during normal traffic.
+                this.heartbeat.clearHeartbeatTimeout();
+                const frame = readWsInboundFrame(message);
+                if (!frame) {
+                    this.logger.debug('[WsTransport] dropped malformed wire frame', {
+                        received: Array.isArray(message) ? 'array' : typeof message,
+                    });
+                    return;
+                }
+                // 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, frame);
+            }
+            catch (error) {
+                this.observability.captureWebSocketError({
+                    context: 'parse-message',
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        };
+        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 (!this.onlineStatus.isOnline()) {
+                this.observability.breadcrumb('WebSocket error: Network is offline', 'sync.websocket', 'warning');
+                this.emit('error', new AbloConnectionError('Network is offline', { code: 'bootstrap_offline' }));
+                return;
+            }
+            // 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) {
+                this.observability.captureWebSocketError({
+                    context: 'connection-error',
+                    error: error.message,
+                });
+            }
+            this.emit('error', error);
+        };
+        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;
+            this.lastCloseReason = event.reason || null;
+            this.logger.info('WebSocket closed', {
+                code: event.code,
+                reason: event.reason,
+                everOpened,
+                reconnectAttempts: this.reconnectAttempts,
+                forceCloseReason: this.lastForceCloseReason,
+                msSinceOpen: this.lastOpenAt != null ? Date.now() - this.lastOpenAt : null,
+                isManualClose: this.isManualClose,
+            });
+            this.isConnecting = false;
+            this.ws = null;
+            this.onClosed();
+            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;
+            // higher-level retry belongs to MutationQueue, not here.
+            if (this.pendingMutations.size > 0) {
+                for (const pending of this.pendingMutations.values()) {
+                    clearTimeout(pending.timeout);
+                    // AbloConnectionError → `isPermanentError` treats it as transient,
+                    // so MutationQueue retries the commit on reconnect rather than
+                    // rolling it back. `diagnostics` is preserved as a property (the
+                    // queue's failure log walks the cause chain for it).
+                    pending.reject(Object.assign(new AbloConnectionError(`WebSocket closed while commit was in flight (code=${event.code}` +
+                        (event.reason ? ` reason=${event.reason}` : '') +
+                        (this.lastForceCloseReason
+                            ? ` forceCloseReason=${this.lastForceCloseReason}`
+                            : '') +
+                        ')', { code: 'commit_no_result' }), { diagnostics: this.getConnectionDiagnostics() }));
+                }
+                this.pendingMutations.clear();
+            }
+            // Cancel in-flight claims — same rationale. Server-side
+            // claims are bound to the connection; a reconnect will need
+            // to re-claim. Higher-level retry belongs to whoever holds
+            // the participant handle (typically the SDK's claim manager).
+            if (this.pendingClaims.size > 0) {
+                for (const pending of this.pendingClaims.values()) {
+                    clearTimeout(pending.timeout);
+                    pending.reject(new AbloConnectionError(`WebSocket closed while claim was in flight (code=${event.code})`));
+                }
+                this.pendingClaims.clear();
+            }
+            // Cancel in-flight subscription updates — the reconnect handshake
+            // re-sends `options.syncGroups` (the last acked interest) in the
+            // upgrade URL, so a pending change that never acked is simply
+            // retried by the caller against the fresh connection.
+            if (this.pendingSubscriptions.length > 0) {
+                for (const pending of this.pendingSubscriptions) {
+                    clearTimeout(pending.timeout);
+                    pending.reject(new AbloConnectionError(`WebSocket closed while update_subscription was in flight (code=${event.code})`));
+                }
+                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) {
+                this.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)
+            // 4003 = Forbidden (custom)
+            const isSessionClose = event.code === 1008 ||
+                event.code === 4001 ||
+                event.code === 4003 ||
+                AbloSessionError.isSessionError(event.reason || '');
+            if (isSessionClose) {
+                this._sessionErrorDetected = true;
+                this.sessionErrorAt = Date.now();
+                this.observability.captureWebSocketError({
+                    context: 'session-error-close',
+                    code: event.code,
+                    reason: event.reason,
+                });
+                this.emit('session_error', new AbloSessionError(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 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 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
+            // 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) {
+                this.observability.captureWebSocketError({
+                    context: 'handshake-failed-close',
+                    code: event.code,
+                    reason: event.reason,
+                });
+                this.emit('handshake_failed', event);
+                this.emit('disconnected', event);
+                return;
+            }
+            this.emit('disconnected', event);
+            // Reconnect if not manually closed
+            if (!this.isManualClose) {
+                this.scheduleReconnect();
+            }
+        };
+    }
+    /**
+     * Send message to server
+     */
+    send(message) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            // Only log at debug level when offline - this is expected behavior, not an error
+            if (this.onlineStatus.isOnline()) {
+                this.observability.breadcrumb('WebSocket not connected, cannot send message', 'sync.websocket', 'warning');
+            }
+            else {
+                this.logger.debug('WebSocket send skipped - offline');
+            }
+            return;
+        }
+        try {
+            this.ws.send(JSON.stringify(message));
+        }
+        catch (error) {
+            // Only log as error if we're online - offline send failures are expected
+            if (this.onlineStatus.isOnline()) {
+                this.observability.captureWebSocketError({
+                    context: 'send-message',
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            else {
+                this.logger.debug('WebSocket send failed - offline');
+            }
+        }
+    }
+    /**
+     * 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 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, reads, track) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            return Promise.reject(this.notConnectedError('commit'));
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingMutations.delete(clientTxId);
+                reject(new AbloConnectionError(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`, { code: 'commit_no_result' }));
+            }, timeoutMs);
+            this.pendingMutations.set(clientTxId, { resolve, reject, timeout });
+            try {
+                const frame = buildCommitFrame(operations, clientTxId, reads, track);
+                this.ws.send(JSON.stringify(frame));
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                this.pendingMutations.delete(clientTxId);
+                reject(toAbloError(error));
+            }
+        });
+    }
+    /**
+     * Send a commit frame without waiting for `mutation_result`.
+     *
+     * This backs the public `wait: 'queued'` API: the socket accepted the
+     * frame for delivery, but the server has not confirmed it yet. The
+     * eventual `mutation_result` frame is intentionally ignored by this
+     * instance because no pending resolver is registered.
+     */
+    sendCommitQueued(operations, clientTxId, reads, track) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            throw this.notConnectedError('commit');
+        }
+        const frame = buildCommitFrame(operations, clientTxId, reads, track);
+        this.ws.send(JSON.stringify(frame));
+    }
+    /**
+     * 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 a failed ack, a timeout, or a disconnect.
+     */
+    sendClaim(claimId, syncGroups, options) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            return Promise.reject(this.notConnectedError('claim'));
+        }
+        const timeoutMs = options?.timeoutMs ?? 15_000;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingClaims.delete(claimId);
+                reject(new AbloConnectionError(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`, {
+                    code: 'wait_for_timeout',
+                }));
+            }, timeoutMs);
+            this.pendingClaims.set(claimId, { resolve, reject, timeout });
+            try {
+                this.ws.send(JSON.stringify({
+                    type: 'claim',
+                    payload: {
+                        claimId,
+                        syncGroups: [...syncGroups],
+                        capabilityToken: options?.capabilityToken,
+                        ttlSeconds: options?.ttlSeconds,
+                    },
+                }));
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                this.pendingClaims.delete(claimId);
+                reject(toAbloError(error));
+            }
+        });
+    }
+    /**
+     * Drop a previously-active claim. Idempotent — `release` is
+     * fire-and-forget per the wire contract; the server accepts
+     * unknown claimIds silently so disconnect-time release storms
+     * never error. No ack is expected.
+     *
+     * If a claim's send promise is still pending (no claim_ack yet),
+     * we reject it locally — the user explicitly chose to release.
+     */
+    sendRelease(claimId) {
+        // Cancel any in-flight claim that hadn't acked yet — the user
+        // changed their mind. Without this the timer would eventually
+        // reject; doing it now matches the user's claim immediately.
+        const pending = this.pendingClaims.get(claimId);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            this.pendingClaims.delete(claimId);
+            pending.reject(new AbloError(`claim ${claimId} released before ack`, {
+                code: 'claim_wait_aborted',
+                httpStatus: 409,
+            }));
+        }
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            this.ws.send(JSON.stringify({ type: 'release', payload: { claimId } }));
+        }
+        catch {
+            // Idempotent contract — silent failure is acceptable here.
+        }
+    }
+    /**
+     * 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.
+     *
+     * 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} (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) {
+            return Promise.reject(this.notConnectedError('update_subscription'));
+        }
+        const timeoutMs = options?.timeoutMs ?? 15_000;
+        return new Promise((resolve, reject) => {
+            const entry = {
+                resolve,
+                reject,
+                timeout: setTimeout(() => {
+                    const idx = this.pendingSubscriptions.indexOf(entry);
+                    if (idx !== -1)
+                        this.pendingSubscriptions.splice(idx, 1);
+                    reject(new AbloConnectionError(`update_subscription timed out after ${timeoutMs}ms`, { code: 'wait_for_timeout' }));
+                }, timeoutMs),
+            };
+            // Check the payload against the schema the server ingests it with, so a
+            // malformed sync group fails here — naming the group and the call that
+            // asked for it — instead of coming back as a rejection ack a round trip
+            // later, detached from the code that caused it.
+            const payload = updateSubscriptionPayloadSchema.safeParse({
+                syncGroups: [...syncGroups],
+            });
+            if (!payload.success) {
+                clearTimeout(entry.timeout);
+                reject(new AbloValidationError(`update_subscription was given a sync group the protocol does not accept: ${payload.error.issues[0]?.message ?? 'unreadable'}. A group is 'default' or 'kind:id'.`, { code: 'malformed_subscription' }));
+                return;
+            }
+            this.pendingSubscriptions.push(entry);
+            try {
+                this.ws.send(JSON.stringify({ type: 'update_subscription', payload: payload.data }));
+            }
+            catch (error) {
+                clearTimeout(entry.timeout);
+                const idx = this.pendingSubscriptions.indexOf(entry);
+                if (idx !== -1)
+                    this.pendingSubscriptions.splice(idx, 1);
+                reject(toAbloError(error));
+            }
+        });
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Seeds the participant kind after identity resolution. The kind rides the
+     * upgrade URL and selects the server's auth path, and on the hosted path it
+     * is derived from the credential's scope — known only once identity
+     * resolves, after the socket is built. Call before `connect()`.
+     */
+    setKind(kind) {
+        this.options.kind = kind;
+    }
+    getAuthToken() {
+        return this.resolveAuthToken();
+    }
+    /**
+     * Return the credential that will be used by the next WebSocket upgrade.
+     * ConnectionManager reads this for HTTP auth probes so visibility/network
+     * checks authenticate the same way reconnects do.
+     */
+    getCapabilityToken() {
+        return this.resolveAuthToken();
+    }
+    resolveAuthToken = () => {
+        return this.options.getAuthToken?.()
+            ?? this.options.getCapabilityToken?.()
+            ?? this.options.capabilityToken;
+    };
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+        }
+        // Session error means the user needs to re-authenticate — don't reconnect.
+        if (this._sessionErrorDetected) {
+            return;
+        }
+        // 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 (!this.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 the store resets the attempt count and
+        // reconnects when the network returns.
+        if (this.reconnectAttempts >= WsTransport.MAX_RECONNECT_ATTEMPTS) {
+            this.emit('reconnect_failed', { attempts: this.reconnectAttempts });
+            return;
+        }
+        // Exponential backoff with ±15% jitter to prevent thundering herd
+        const baseDelay = Math.min(this.options.reconnectDelay * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectDelay);
+        const jitter = baseDelay * (0.85 + Math.random() * 0.3);
+        const delay = Math.round(jitter);
+        // Emit reconnecting event so UI can show reconnection status
+        this.emit('reconnecting', { attempt: this.reconnectAttempts + 1, delay });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectAttempts++;
+            this.connect();
+        }, delay);
+    }
+    /**
+     * Reset reconnect attempt counter. Called when network comes back online
+     * to allow a fresh reconnect cycle after the max was previously reached.
+     */
+    resetReconnectAttempts() {
+        this.reconnectAttempts = 0;
+    }
+    /**
+     * Disconnect from WebSocket
+     */
+    disconnect() {
+        this.isManualClose = true;
+        this.heartbeat.stop();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close(1000, 'Manual disconnect');
+            this.ws = null;
+        }
+    }
+    /**
+     * Force-close the socket from the client side using a private 4xxx
+     * code. Callers expect `onclose` to fire; that handler runs the
+     * existing reconnect / handshake-failed dispatch. Wrapped in
+     * try/catch because `close()` on a CLOSING/CLOSED socket throws on
+     * some browsers.
+     */
+    forceClose(reason) {
+        if (!this.ws)
+            return;
+        this.lastForceCloseReason = reason;
+        this.logger.debug('[WsTransport] forceClose', {
+            reason,
+            readyState: this.ws.readyState,
+            msSinceOpen: this.lastOpenAt != null ? Date.now() - this.lastOpenAt : null,
+        });
+        try {
+            this.ws.close(4000, reason);
+        }
+        catch {
+            // Already closing / closed — onclose will still fire.
+        }
+    }
+    /**
+     * Get connection state
+     */
+    isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * Snapshot of recent connection lifecycle state, for diagnostic logs
+     * and error messages. Cheap to call (no I/O); safe to log every time
+     * a send is rejected so we can attribute "not connected" rejections
+     * to the actual root cause (handshake reject vs heartbeat zombie vs
+     * session expiry vs explicit close).
+     */
+    getConnectionDiagnostics() {
+        const now = Date.now();
+        return {
+            readyState: this.ws?.readyState ?? null,
+            isConnecting: this.isConnecting,
+            isManualClose: this.isManualClose,
+            sessionErrorDetected: this._sessionErrorDetected,
+            everOpened: this._everOpened,
+            reconnectAttempts: this.reconnectAttempts,
+            maxReconnectAttempts: WsTransport.MAX_RECONNECT_ATTEMPTS,
+            lastOpenAt: this.lastOpenAt,
+            lastCloseAt: this.lastCloseAt,
+            lastCloseCode: this.lastCloseCode,
+            lastCloseReason: this.lastCloseReason,
+            lastForceCloseReason: this.lastForceCloseReason,
+            sessionErrorAt: this.sessionErrorAt,
+            msSinceLastOpen: this.lastOpenAt != null ? now - this.lastOpenAt : null,
+            msSinceLastClose: this.lastCloseAt != null ? now - this.lastCloseAt : null,
+        };
+    }
+    /**
+     * Build a richly-diagnosed "not connected" error so callers (and the
+     * logs they emit) can attribute the rejection. The message embeds the
+     * dominant signal in human-readable form; the structured detail is
+     * also attached as `error.diagnostics` for log scrapers.
+     */
+    notConnectedError(action) {
+        const d = this.getConnectionDiagnostics();
+        // 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 AbloSessionError(`SyncWebSocket not connected — cannot send ${action}: session expired` +
+                (d.lastCloseReason ? ` (${d.lastCloseReason})` : '') +
+                '; re-authenticate'), { diagnostics: d });
+        }
+        let detail;
+        if (d.isManualClose) {
+            detail = 'manual_close';
+        }
+        else if (d.isConnecting) {
+            detail = 'still_connecting';
+        }
+        else if (!d.everOpened && d.lastCloseAt != null) {
+            detail = `handshake_failed code=${d.lastCloseCode}`;
+        }
+        else if (d.lastForceCloseReason) {
+            detail = `force_closed reason=${d.lastForceCloseReason}`;
+        }
+        else if (d.lastCloseAt != null) {
+            detail =
+                `closed code=${d.lastCloseCode}` +
+                    (d.lastCloseReason ? ` reason=${d.lastCloseReason}` : '') +
+                    (d.msSinceLastClose != null ? ` ${d.msSinceLastClose}ms ago` : '') +
+                    (d.reconnectAttempts > 0
+                        ? ` reconnectAttempts=${d.reconnectAttempts}/${d.maxReconnectAttempts}`
+                        : '');
+        }
+        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.
+        const err = Object.assign(new AbloConnectionError(`SyncWebSocket not connected — cannot send ${action} (${detail})`, { code: 'ws_not_ready' }), { diagnostics: d });
+        return err;
+    }
+    /** Returns the sync groups this connection is subscribed to. */
+    getSyncGroups() {
+        return this.options.syncGroups;
+    }
+    /**
+     * Seeds the connection's read interest — the sync groups the next upgrade
+     * URL carries. The set is already mutable state (`subscription_ack` writes
+     * the acked set back so a reconnect resubscribes to current interest);
+     * this setter is the host's way to seed it once identity resolves, before
+     * the first `connect()`.
+     */
+    setSyncGroups(syncGroups) {
+        this.options.syncGroups = [...syncGroups];
+    }
+}