@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/transport/wsTransport.d.ts

@@ -0,0 +1,574 @@
+/**
+ * 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 type { ParticipantKind } from '../types/participant.js';
+import type { BootstrapReason } from '../wire/bootstrapReason.js';
+import type { ClientSyncDelta } from '../wire/delta.js';
+import type { ClaimAcquired, PresenceUpdate, ClaimExpired, ClaimGranted, ClaimHeartbeatAckPayload, ClaimLost, ClaimQueue, ClaimQueued, ClaimRejection, ParticipantClaimPayload, StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
+import { type CommitAck, type CommitFrameOperation } from './commitFrames.js';
+import { type Logger } from '../logger.js';
+import { type SocketObservability } from '../observability.js';
+export interface SyncCapabilities {
+    partialBootstrap?: boolean;
+    compressedDeltas?: boolean;
+    streamingBootstrap?: boolean;
+    batchedDeltas?: boolean;
+}
+export interface WsTransportOptions {
+    /** Base HTTP URL of the sync server */
+    baseUrl?: string;
+    url?: string;
+    /**
+     * Engine bookkeeping only. The server is bearer-only — it resolves identity
+     * from the verified credential and never reads these — and the transport
+     * itself never reads them either. A bare connection omits them.
+     */
+    userId?: string;
+    organizationId?: string;
+    lastSyncId?: number;
+    syncGroups?: string[];
+    capabilities?: SyncCapabilities;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    /**
+     * Collaboration event type keys to listen for (e.g., ['document:selection',
+     * 'document:cursor']). Wire messages with matching types (underscore format)
+     * are emitted as events.
+     *
+     * Defaults to none. The vocabulary is the application's, not the SDK's, so
+     * an application names the events it broadcasts rather than inheriting a
+     * built-in list that would only ever fit one consumer.
+     */
+    collaborationEvents?: string[];
+    /**
+     * The participant kind declared on the WebSocket upgrade. Defaults to
+     * `'user'` (session auth, the web app). Agent runtimes pass `'agent'` so the
+     * server verifies them by capability token instead of session auth. The
+     * server reads this as the `kind` query parameter.
+     */
+    kind?: ParticipantKind;
+    /**
+     * The agent's bearer credential — a restricted (`rk_`) API key. When set, it
+     * is sent in the `ablo.bearer.<token>` WebSocket subprotocol so the credential
+     * stays out of URLs and proxy logs. Required for `kind: 'agent'` and ignored
+     * for `kind: 'user'`.
+     */
+    capabilityToken?: string;
+    /**
+     * Getter for the current credential. When provided, the WebSocket upgrade
+     * reads it instead of a copied `capabilityToken`, so reconnects always use
+     * the freshest token from the SDK's single credential source. Preferred over
+     * `getCapabilityToken`.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /** @deprecated Use `getAuthToken`. Kept for direct low-level callers. */
+    getCapabilityToken?: AuthTokenGetter;
+    /**
+     * Hold the first connection until the owner releases it. While held,
+     * `connect()` is ignored (debug-logged). A host that builds the socket
+     * before identity is resolved sets this, seeds the late values (`setKind`,
+     * `setSyncGroups`, the resume cursor), and calls {@link WsTransport.allowConnect}
+     * followed by `connect()` — so no caller can open an unscoped connection in
+     * the window between construction and identity resolution.
+     */
+    deferConnect?: boolean;
+    /** Where the transport logs. Defaults to silent. */
+    logger?: Logger;
+    /** Where lifecycle breadcrumbs, socket errors, and coordination outcomes
+     *  are reported. Defaults to silent. */
+    observability?: SocketObservability;
+    /** The connectivity signal consulted before connecting, sending, and
+     *  scheduling reconnects. Defaults to always-online, which is correct for a
+     *  server-side host; the browser engine passes its `navigator.onLine`-backed
+     *  provider. */
+    onlineStatus?: {
+        isOnline(): boolean;
+    };
+}
+/**
+ * Bootstrap hint from server indicating full or partial bootstrap is needed.
+ * Properties are optional since server payload structure may vary.
+ */
+export interface BootstrapHint {
+    tables?: string[];
+    reason?: BootstrapReason;
+    staleTables?: string[];
+    totalDeltaCount?: number;
+}
+/** Bootstrap data event payload */
+export interface BootstrapDataEvent {
+    entityType: string;
+    data: unknown;
+    isComplete: boolean;
+    cursor?: string;
+}
+/**
+ * The presence frame, re-exported at the path consumers already reach it
+ * through. The declaration lives with the rest of the coordination vocabulary;
+ * this keeps `import { PresenceUpdate } from '…/wsTransport'` working for
+ * everything that used to import the hand-written type from here. The local
+ * `import type` above is what makes this a re-export of a bound name rather
+ * than a pass-through that leaves the name unusable in this file.
+ */
+export type { PresenceUpdate };
+/**
+ * Core event map — transport-level events that every connection emits.
+ * SDK consumers extend this with app-specific collaboration events.
+ */
+export interface CoreSyncEventMap {
+    connected: [];
+    disconnected: [CloseEvent];
+    reconnecting: [{
+        attempt: number;
+        delay: number;
+    }];
+    delta: [ClientSyncDelta];
+    delta_batch: [ClientSyncDelta[]];
+    bootstrap_required: [BootstrapHint];
+    bootstrap_data: [BootstrapDataEvent];
+    presence_update: [PresenceUpdate];
+    error: [Error];
+    session_error: [Error];
+    /**
+     * The WebSocket `onclose` fired before `onopen` — the handshake itself
+     * failed. The browser cannot expose the HTTP status (it shows as code
+     * 1006 with no reason), so the consumer should run an authenticated
+     * HTTP probe to distinguish auth failure (session expired) from a
+     * generic network issue.
+     */
+    handshake_failed: [CloseEvent];
+    reconnect_failed: [{
+        attempts: number;
+    }];
+    /**
+     * Server-initiated notification that a previously-active claim's
+     * TTL has expired. Consumers (e.g., the participant SDK) re-mint
+     * a fresh capability and re-claim, OR accept the drop. The claim
+     * is already inactive on the server side by the time this fires —
+     * no client-side action needed unless re-claiming.
+     */
+    claim_expired: [ClaimExpired];
+    /**
+     * Server rejected an `claim_begin` because another participant
+     * already holds an open claim on the same target (cooperative
+     * mutex enforced server-side). Surfaces to the participant-level
+     * ClaimStream so the caller knows their announce was denied.
+     * Payload mirrors the wire frame's `payload`.
+     */
+    claim_rejected: [ClaimRejection];
+    /**
+     * Fair-queue frames (opt-in `queue: true` on `claim_begin`). `claim_acquired`
+     * means the target was free and the lease is ours immediately; `claim_queued`
+     * means the claim is waiting in line (carries `position`); `claim_granted`
+     * means it reached the head and the lease is now ours; `claim_lost` means a
+     * held/granted claim was taken away (TTL lapse on disconnect, revoke).
+     */
+    /**
+     * Per-entity wait-queue snapshot: `{ target, queue: Claim[] }` with each
+     * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
+     * queue mutation — powers the reactive `ablo.<model>.claim.queue({ id })` read.
+     */
+    claim_queue: [ClaimQueue];
+    claim_acquired: [ClaimAcquired];
+    claim_queued: [ClaimQueued];
+    claim_granted: [ClaimGranted];
+    claim_lost: [ClaimLost];
+    /**
+     * Reply to an outbound `claim_heartbeat` — the lease's fate: `held` with
+     * the extended `expiresAt`, `queued` with the current `position`, or
+     * `lost`. Correlated back to the awaiting caller by `claimId` in the
+     * claim stream.
+     */
+    claim_heartbeat_ack: [ClaimHeartbeatAckPayload];
+    /**
+     * A committed write guarded with `onStale: 'notify'` collided with a
+     * concurrent change. Rather than forcing an outcome, the engine returns the
+     * conflicting field's current value so the actor — an agent reasoning over the
+     * change, or a person watching the row — can reconcile it. The commit itself
+     * succeeded; the held operations were not written, and the actor re-issues
+     * them once it has reconciled.
+     */
+    'conflict:notified': [{
+        clientTxId: string;
+        notifications: StaleNotification[];
+    }];
+}
+/**
+ * Collaboration event — app-specific real-time events (selection, cursors, etc.)
+ * Each event is a [payload] tuple matching the EventEmitter convention.
+ */
+export type DefaultCollaborationEvents = Record<string, never>;
+/**
+ * Constraint for event maps: every value must be a tuple of handler args.
+ *
+ * Why a mapped type and not `Record<string, unknown[]>`?
+ * `Record<string, ...>` requires an implicit string index signature, which
+ * TypeScript interfaces don't have. So a closed interface like Ablo's
+ * `AbloCollaborationEvents` would fail to satisfy `Record<string, unknown[]>`,
+ * even though every one of its values is a tuple. This mapped form iterates
+ * over `keyof T` instead of demanding a string index, so it accepts both
+ * closed interfaces and open Record types — while still enforcing
+ * "every value is an array."
+ */
+export type EventMap<T> = {
+    [K in keyof T]: unknown[];
+};
+/**
+ * Full event map = core + collaboration events.
+ * Pass your own TCollaboration to add app-specific events.
+ */
+export type SyncWebSocketEventMap<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents> = CoreSyncEventMap & TCollaboration;
+export declare class WsTransport<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents> extends EventEmitter {
+    /**
+     * Subscribe to events with automatic cleanup.
+     * Returns unsubscribe function for clean disposal.
+     */
+    subscribe<K extends keyof SyncWebSocketEventMap<TCollaboration>>(event: K, handler: (...args: SyncWebSocketEventMap<TCollaboration>[K]) => void): () => void;
+    /**
+     * Send a collaboration event (app-specific real-time message).
+     * The wire format is `{ type: messageType, payload: { ...payload, timestamp } }`.
+     */
+    sendCollaborationEvent<K extends string & keyof TCollaboration>(messageType: K, payload: TCollaboration[K] extends [infer P] ? Omit<P & Record<string, unknown>, 'timestamp'> : never): void;
+    private ws;
+    protected options: Required<Omit<WsTransportOptions, 'baseUrl' | 'kind' | 'capabilityToken' | 'getAuthToken' | 'getCapabilityToken' | 'deferConnect' | 'logger' | 'observability' | 'onlineStatus'>> & {
+        baseUrl?: string;
+        kind?: WsTransportOptions['kind'];
+        capabilityToken?: WsTransportOptions['capabilityToken'];
+        getAuthToken?: WsTransportOptions['getAuthToken'];
+        getCapabilityToken?: WsTransportOptions['getCapabilityToken'];
+    };
+    /** The transport's reporting ports, shared with the subclassing engine. */
+    protected readonly logger: Logger;
+    protected readonly observability: SocketObservability;
+    protected readonly onlineStatus: {
+        isOnline(): boolean;
+    };
+    private reconnectAttempts;
+    /** Stop retrying after this many consecutive failures (backoff caps at 30s, so ~7.5 min total) */
+    private static readonly MAX_RECONNECT_ATTEMPTS;
+    private reconnectTimer;
+    /**
+     * 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.
+     */
+    private readonly heartbeat;
+    private isConnecting;
+    private isManualClose;
+    /** True while the owner still holds the first connection (`deferConnect`).
+     *  `connect()` is ignored until {@link allowConnect} lifts the hold. */
+    private 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. */
+    private _sessionErrorDetected;
+    /** 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. */
+    private _everOpened;
+    /**
+     * 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.
+     */
+    private lastOpenAt;
+    private lastCloseAt;
+    private lastCloseCode;
+    private lastCloseReason;
+    private lastForceCloseReason;
+    private sessionErrorAt;
+    /** Registered collaboration event keys (colon format) for dispatch in onmessage */
+    private 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.
+     */
+    private readonly 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.
+     */
+    private pendingMutations;
+    /**
+     * 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.
+     */
+    private pendingClaims;
+    /**
+     * 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.)
+     */
+    private pendingSubscriptions;
+    constructor(options: WsTransportOptions);
+    /**
+     * 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.
+     */
+    protected handleDelta(rawDelta: unknown): void;
+    /** A `sync_response` frame. Meaningless without a resume cursor to advance,
+     *  so the transport default does nothing. */
+    protected handleSyncResponse(_payload: unknown): void;
+    /** A `bootstrap_response` frame. Bootstrap is materialisation, so the
+     *  transport default does nothing. */
+    protected handleBootstrapResponse(_payload: unknown): void;
+    /**
+     * 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 } }
+     */
+    protected handlePresenceUpdate(message: Partial<PresenceUpdate> & {
+        payload?: PresenceUpdate;
+        [k: string]: unknown;
+    }): void;
+    /**
+     * 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.
+     */
+    protected onOpened(): void;
+    /**
+     * 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.
+     */
+    protected onClosed(): void;
+    /**
+     * 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.
+     */
+    protected resumeCursor(): string;
+    /**
+     * Mark that a session error has been detected (e.g. 401 from HTTP bootstrap).
+     * Suppresses further reconnection attempts and Sentry error capture.
+     */
+    setSessionErrorDetected(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * Connect to the sync engine WebSocket
+     */
+    connect(): void;
+    /**
+     * Setup WebSocket event handlers
+     */
+    private setupEventHandlers;
+    /**
+     * Send message to server
+     */
+    send(message: any): void;
+    /**
+     * 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: readonly CommitFrameOperation[], clientTxId: string, timeoutMs?: number, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): Promise<CommitAck>;
+    /**
+     * 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: readonly CommitFrameOperation[], clientTxId: string, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): void;
+    /**
+     * 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: string, syncGroups: readonly string[], options?: Pick<ParticipantClaimPayload, 'capabilityToken' | 'ttlSeconds'> & {
+        timeoutMs?: number;
+    }): Promise<{
+        syncGroups: string[];
+        ttlSeconds?: number;
+    }>;
+    /**
+     * 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: string): void;
+    /**
+     * 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: readonly string[], options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        syncGroups: string[];
+    }>;
+    /**
+     * 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: string): void;
+    /**
+     * 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: ParticipantKind): void;
+    getAuthToken(): string | undefined;
+    /**
+     * 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(): string | undefined;
+    private resolveAuthToken;
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    private scheduleReconnect;
+    /**
+     * Reset reconnect attempt counter. Called when network comes back online
+     * to allow a fresh reconnect cycle after the max was previously reached.
+     */
+    resetReconnectAttempts(): void;
+    /**
+     * Disconnect from WebSocket
+     */
+    disconnect(): void;
+    /**
+     * 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.
+     */
+    protected forceClose(reason: string): void;
+    /**
+     * Get connection state
+     */
+    isConnected(): boolean;
+    /**
+     * 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(): {
+        readyState: number | null;
+        isConnecting: boolean;
+        isManualClose: boolean;
+        sessionErrorDetected: boolean;
+        everOpened: boolean;
+        reconnectAttempts: number;
+        maxReconnectAttempts: number;
+        lastOpenAt: number | null;
+        lastCloseAt: number | null;
+        lastCloseCode: number | null;
+        lastCloseReason: string | null;
+        lastForceCloseReason: string | null;
+        sessionErrorAt: number | null;
+        msSinceLastOpen: number | null;
+        msSinceLastClose: number | 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.
+     */
+    protected notConnectedError(action: string): Error & {
+        diagnostics: ReturnType<WsTransport['getConnectionDiagnostics']>;
+    };
+    /** Returns the sync groups this connection is subscribed to. */
+    getSyncGroups(): string[];
+    /**
+     * 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: readonly string[]): void;
+}