@abloatai/ablo 0.36.0 → 0.37.0

package/dist/transaction/transport/wsTransport.js

@@ -1,1023 +0,0 @@
-/**
- * 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 { participantClaimPayloadSchema, 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'));
-        }
-        // Checked against the schema the server ingests it with, for the same
-        // reason `updateSubscription` below is: the two frames name their scopes
-        // identically, so a group that would be refused there is refused here, at
-        // the call that asked for it, rather than coming back as a failed ack a
-        // round trip later with nothing to point at.
-        const payload = participantClaimPayloadSchema.safeParse({
-            claimId,
-            syncGroups: [...syncGroups],
-            capabilityToken: options?.capabilityToken,
-            ttlSeconds: options?.ttlSeconds,
-        });
-        if (!payload.success) {
-            return Promise.reject(new AbloValidationError(`join 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_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: payload.data }));
-            }
-            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];
-    }
-}