@abloatai/ablo 0.36.0 → 0.37.0

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

@@ -1,574 +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 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;
-}