@topgunbuild/client 0.2.1 → 0.4.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { LWWRecord, ORMapRecord, PredicateNode, LWWMap, ORMap, Timestamp, HLC } from '@topgunbuild/core';
+import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
 export { LWWMap, LWWRecord, PredicateNode, Predicates } from '@topgunbuild/core';
 import pino from 'pino';
 
@@ -35,6 +35,65 @@ interface IStorageAdapter {
     getAllKeys(): Promise<string[]>;
 }
 
+/**
+ * Represents a change event for tracking data mutations.
+ */
+interface ChangeEvent<T> {
+    /** Type of change: 'add' for new entries, 'update' for modified entries, 'remove' for deleted entries */
+    type: 'add' | 'update' | 'remove';
+    /** The key of the changed entry */
+    key: string;
+    /** New value (present for 'add' and 'update') */
+    value?: T;
+    /** Previous value (present for 'update' and 'remove') */
+    previousValue?: T;
+    /** HLC timestamp of the change */
+    timestamp: number;
+}
+/**
+ * ChangeTracker computes differences between snapshots of a Map.
+ * Used to track add/update/remove changes for subscription notifications.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ChangeTracker<Todo>();
+ *
+ * // First snapshot
+ * const changes1 = tracker.computeChanges(
+ *   new Map([['a', { title: 'Todo A' }]]),
+ *   Date.now()
+ * );
+ * // changes1 = [{ type: 'add', key: 'a', value: { title: 'Todo A' }, timestamp: ... }]
+ *
+ * // Second snapshot with update
+ * const changes2 = tracker.computeChanges(
+ *   new Map([['a', { title: 'Todo A Updated' }]]),
+ *   Date.now()
+ * );
+ * // changes2 = [{ type: 'update', key: 'a', value: { title: 'Todo A Updated' }, previousValue: { title: 'Todo A' }, timestamp: ... }]
+ * ```
+ */
+declare class ChangeTracker<T> {
+    private previousSnapshot;
+    /**
+     * Computes changes between previous and current state.
+     * Updates internal snapshot after computation.
+     *
+     * @param current - Current state as a Map
+     * @param timestamp - HLC timestamp for the changes
+     * @returns Array of change events (may be empty if no changes)
+     */
+    computeChanges(current: Map<string, T>, timestamp: number): ChangeEvent<T>[];
+    /**
+     * Reset tracker (e.g., on query change or reconnect)
+     */
+    reset(): void;
+    /**
+     * Get current snapshot size for debugging/metrics
+     */
+    get size(): number;
+}
+
 interface QueryFilter {
     where?: Record<string, any>;
     predicate?: PredicateNode;
@@ -55,6 +114,9 @@ declare class QueryHandle<T> {
     private filter;
     private listeners;
     private currentResults;
+    private changeTracker;
+    private pendingChanges;
+    private changeListeners;
     constructor(syncEngine: SyncEngine, mapName: string, filter?: QueryFilter);
     subscribe(callback: (results: QueryResultItem<T>[]) => void): () => void;
     private loadInitialLocalData;
@@ -79,6 +141,47 @@ declare class QueryHandle<T> {
      * Called by SyncEngine when server sends a live update
      */
     onUpdate(key: string, value: T | null): void;
+    /**
+     * Subscribe to change events (Phase 5.1).
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = handle.onChanges((changes) => {
+     *   for (const change of changes) {
+     *     if (change.type === 'add') {
+     *       console.log('Added:', change.key, change.value);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    onChanges(listener: (changes: ChangeEvent<T>[]) => void): () => void;
+    /**
+     * Get and clear pending changes (Phase 5.1).
+     * Call this to retrieve all changes since the last consume.
+     */
+    consumeChanges(): ChangeEvent<T>[];
+    /**
+     * Get last change without consuming (Phase 5.1).
+     * Returns null if no pending changes.
+     */
+    getLastChange(): ChangeEvent<T> | null;
+    /**
+     * Get all pending changes without consuming (Phase 5.1).
+     */
+    getPendingChanges(): ChangeEvent<T>[];
+    /**
+     * Clear all pending changes (Phase 5.1).
+     */
+    clearChanges(): void;
+    /**
+     * Reset change tracker (Phase 5.1).
+     * Use when query filter changes or on reconnect.
+     */
+    resetChangeTracker(): void;
+    private computeAndNotifyChanges;
+    private notifyChangeListeners;
     private notify;
     private getSortedResults;
     getFilter(): QueryFilter;
@@ -304,6 +407,238 @@ interface OperationDroppedEvent {
     key: string;
 }
 
+/**
+ * Connection Provider Types
+ *
+ * IConnectionProvider abstracts WebSocket connection handling to support
+ * both single-server and cluster modes.
+ */
+/**
+ * Events emitted by IConnectionProvider.
+ */
+type ConnectionProviderEvent = 'connected' | 'disconnected' | 'reconnected' | 'message' | 'partitionMapUpdated' | 'error';
+/**
+ * Connection event handler type.
+ */
+type ConnectionEventHandler = (...args: any[]) => void;
+/**
+ * Abstract interface for WebSocket connection providers.
+ *
+ * Implementations:
+ * - SingleServerProvider: Direct connection to a single server
+ * - ClusterClient: Multi-node connection pool with partition routing
+ */
+interface IConnectionProvider {
+    /**
+     * Connect to the server(s).
+     * In cluster mode, connects to all seed nodes.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * In cluster mode: routes to partition owner based on key hash.
+     * In single-server mode: returns the only connection.
+     *
+     * @param key - The key to route (used for partition-aware routing)
+     * @throws Error if not connected
+     */
+    getConnection(key: string): WebSocket;
+    /**
+     * Get any available connection.
+     * Used for subscriptions, metadata requests, and non-key-specific operations.
+     *
+     * @throws Error if not connected
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if at least one connection is active and ready.
+     */
+    isConnected(): boolean;
+    /**
+     * Get all connected node IDs.
+     * Single-server mode returns ['default'].
+     * Cluster mode returns actual node IDs.
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Subscribe to connection events.
+     *
+     * Events:
+     * - 'connected': A connection was established (nodeId?: string)
+     * - 'disconnected': A connection was lost (nodeId?: string)
+     * - 'reconnected': A connection was re-established after disconnect (nodeId?: string)
+     * - 'message': A message was received (nodeId: string, data: any)
+     * - 'partitionMapUpdated': Partition map was updated (cluster mode only)
+     * - 'error': An error occurred (error: Error)
+     */
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Unsubscribe from connection events.
+     */
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Send a message via the appropriate connection.
+     * In cluster mode, routes based on key if provided.
+     *
+     * @param data - Serialized message data
+     * @param key - Optional key for routing (cluster mode)
+     */
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Close all connections gracefully.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Configuration for SingleServerProvider.
+ */
+interface SingleServerProviderConfig {
+    /** WebSocket URL to connect to */
+    url: string;
+    /** Maximum reconnection attempts (default: 10) */
+    maxReconnectAttempts?: number;
+    /** Initial reconnect delay in ms (default: 1000) */
+    reconnectDelayMs?: number;
+    /** Backoff multiplier for reconnect delay (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    maxReconnectDelayMs?: number;
+}
+
+/**
+ * Registered resolver info returned from server.
+ */
+interface ResolverInfo {
+    mapName: string;
+    name: string;
+    priority?: number;
+    keyPattern?: string;
+}
+/**
+ * Registration result from server.
+ */
+interface RegisterResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Client-side manager for conflict resolvers.
+ *
+ * Provides API for:
+ * - Registering conflict resolvers on server
+ * - Unregistering resolvers
+ * - Listing registered resolvers
+ * - Subscribing to merge rejection events
+ */
+declare class ConflictResolverClient {
+    private readonly syncEngine;
+    private readonly rejectionListeners;
+    private readonly pendingRequests;
+    private static readonly REQUEST_TIMEOUT;
+    constructor(syncEngine: SyncEngine);
+    /**
+     * Register a conflict resolver on the server.
+     *
+     * @param mapName The map to register the resolver for
+     * @param resolver The resolver definition
+     * @returns Promise resolving to registration result
+     *
+     * @example
+     * ```typescript
+     * // Register a first-write-wins resolver for bookings
+     * await client.resolvers.register('bookings', {
+     *   name: 'first-write-wins',
+     *   code: `
+     *     if (context.localValue !== undefined) {
+     *       return { action: 'reject', reason: 'Slot already booked' };
+     *     }
+     *     return { action: 'accept', value: context.remoteValue };
+     *   `,
+     *   priority: 100,
+     * });
+     * ```
+     */
+    register<V>(mapName: string, resolver: Omit<ConflictResolverDef<V>, 'fn'>): Promise<RegisterResult>;
+    /**
+     * Unregister a conflict resolver from the server.
+     *
+     * @param mapName The map the resolver is registered for
+     * @param resolverName The name of the resolver to unregister
+     * @returns Promise resolving to unregistration result
+     */
+    unregister(mapName: string, resolverName: string): Promise<RegisterResult>;
+    /**
+     * List registered conflict resolvers on the server.
+     *
+     * @param mapName Optional - filter by map name
+     * @returns Promise resolving to list of resolver info
+     */
+    list(mapName?: string): Promise<ResolverInfo[]>;
+    /**
+     * Subscribe to merge rejection events.
+     *
+     * @param listener Callback for rejection events
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.resolvers.onRejection((rejection) => {
+     *   console.log(`Merge rejected for ${rejection.key}: ${rejection.reason}`);
+     *   // Optionally refresh the local value
+     * });
+     *
+     * // Later...
+     * unsubscribe();
+     * ```
+     */
+    onRejection(listener: (rejection: MergeRejection) => void): () => void;
+    /**
+     * Handle REGISTER_RESOLVER_RESPONSE from server.
+     * Called by SyncEngine.
+     */
+    handleRegisterResponse(message: {
+        requestId: string;
+        success: boolean;
+        error?: string;
+    }): void;
+    /**
+     * Handle UNREGISTER_RESOLVER_RESPONSE from server.
+     * Called by SyncEngine.
+     */
+    handleUnregisterResponse(message: {
+        requestId: string;
+        success: boolean;
+        error?: string;
+    }): void;
+    /**
+     * Handle LIST_RESOLVERS_RESPONSE from server.
+     * Called by SyncEngine.
+     */
+    handleListResponse(message: {
+        requestId: string;
+        resolvers: ResolverInfo[];
+    }): void;
+    /**
+     * Handle MERGE_REJECTED from server.
+     * Called by SyncEngine.
+     */
+    handleMergeRejected(message: {
+        mapName: string;
+        key: string;
+        attemptedValue: unknown;
+        reason: string;
+        timestamp: Timestamp;
+    }): void;
+    /**
+     * Clear all pending requests (e.g., on disconnect).
+     */
+    clearPending(): void;
+    /**
+     * Get the number of registered rejection listeners.
+     */
+    get rejectionListenerCount(): number;
+}
+
 interface HeartbeatConfig {
     intervalMs: number;
     timeoutMs: number;
@@ -323,7 +658,10 @@ interface BackoffConfig {
 }
 interface SyncEngineConfig {
     nodeId: string;
-    serverUrl: string;
+    /** @deprecated Use connectionProvider instead */
+    serverUrl?: string;
+    /** Connection provider (preferred over serverUrl) */
+    connectionProvider?: IConnectionProvider;
     storageAdapter: IStorageAdapter;
     reconnectInterval?: number;
     heartbeat?: Partial<HeartbeatConfig>;
@@ -337,6 +675,8 @@ declare class SyncEngine {
     private readonly hlc;
     private readonly stateMachine;
     private readonly backoffConfig;
+    private readonly connectionProvider;
+    private readonly useConnectionProvider;
     private websocket;
     private opLog;
     private maps;
@@ -358,6 +698,7 @@ declare class SyncEngine {
     private highWaterMarkEmitted;
     private backpressureListeners;
     private pendingWriteConcernPromises;
+    private readonly conflictResolverClient;
     constructor(config: SyncEngineConfig);
     /**
      * Get the current connection state
@@ -384,6 +725,14 @@ declare class SyncEngine {
      * Check if fully connected and synced
      */
     private isConnected;
+    /**
+     * Initialize connection using IConnectionProvider (Phase 4.5 cluster mode).
+     * Sets up event handlers for the connection provider.
+     */
+    private initConnectionProvider;
+    /**
+     * Initialize connection using direct WebSocket (legacy single-server mode).
+     */
     private initConnection;
     private scheduleReconnect;
     private calculateBackoffDelay;
@@ -391,6 +740,18 @@ declare class SyncEngine {
      * Reset backoff counter (called on successful connection)
      */
     private resetBackoff;
+    /**
+     * Send a message through the current connection.
+     * Uses connectionProvider if in cluster mode, otherwise uses direct websocket.
+     * @param message Message object to serialize and send
+     * @param key Optional key for routing (cluster mode only)
+     * @returns true if message was sent, false otherwise
+     */
+    private sendMessage;
+    /**
+     * Check if we can send messages (connection is ready).
+     */
+    private canSend;
     private loadOpLog;
     private saveOpLog;
     registerMap(mapName: string, map: LWWMap<any, any> | ORMap<any, any>): void;
@@ -439,6 +800,43 @@ declare class SyncEngine {
      * Use after fatal errors to start fresh.
      */
     resetConnection(): void;
+    /**
+     * Wait for a partition map update from the connection provider.
+     * Used when an operation fails with NOT_OWNER error and needs
+     * to wait for an updated partition map before retrying.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 5000ms)
+     * @returns Promise that resolves when partition map is updated or times out
+     */
+    waitForPartitionMapUpdate(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for the connection to be available.
+     * Used when an operation fails due to connection issues and needs
+     * to wait for reconnection before retrying.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 10000ms)
+     * @returns Promise that resolves when connected or rejects on timeout
+     */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for a specific sync state.
+     * Useful for waiting until fully connected and synced.
+     *
+     * @param targetState - The state to wait for
+     * @param timeoutMs - Maximum time to wait (default: 30000ms)
+     * @returns Promise that resolves when state is reached or rejects on timeout
+     */
+    waitForState(targetState: SyncState, timeoutMs?: number): Promise<void>;
+    /**
+     * Check if the connection provider is connected.
+     * Convenience method for failover logic.
+     */
+    isProviderConnected(): boolean;
+    /**
+     * Get the connection provider for direct access.
+     * Use with caution - prefer using SyncEngine methods.
+     */
+    getConnectionProvider(): IConnectionProvider;
     private resetMap;
     /**
      * Starts the heartbeat mechanism after successful connection.
@@ -540,6 +938,99 @@ declare class SyncEngine {
      * Cancel all pending Write Concern promises (e.g., on disconnect).
      */
     private cancelAllWriteConcernPromises;
+    /** Counter update listeners by name */
+    private counterUpdateListeners;
+    /**
+     * Subscribe to counter updates from server.
+     * @param name Counter name
+     * @param listener Callback when counter state is updated
+     * @returns Unsubscribe function
+     */
+    onCounterUpdate(name: string, listener: (state: any) => void): () => void;
+    /**
+     * Request initial counter state from server.
+     * @param name Counter name
+     */
+    requestCounter(name: string): void;
+    /**
+     * Sync local counter state to server.
+     * @param name Counter name
+     * @param state Counter state to sync
+     */
+    syncCounter(name: string, state: any): void;
+    /**
+     * Handle incoming counter update from server.
+     * Called by handleServerMessage for COUNTER_UPDATE messages.
+     */
+    private handleCounterUpdate;
+    /** Pending entry processor requests by requestId */
+    private pendingProcessorRequests;
+    /** Pending batch entry processor requests by requestId */
+    private pendingBatchProcessorRequests;
+    /** Default timeout for entry processor requests (ms) */
+    private static readonly PROCESSOR_TIMEOUT;
+    /**
+     * Execute an entry processor on a single key atomically.
+     *
+     * @param mapName Name of the map
+     * @param key Key to process
+     * @param processor Processor definition
+     * @returns Promise resolving to the processor result
+     */
+    executeOnKey<V, R = V>(mapName: string, key: string, processor: EntryProcessorDef<V, R>): Promise<EntryProcessorResult<R>>;
+    /**
+     * Execute an entry processor on multiple keys.
+     *
+     * @param mapName Name of the map
+     * @param keys Keys to process
+     * @param processor Processor definition
+     * @returns Promise resolving to a map of key -> result
+     */
+    executeOnKeys<V, R = V>(mapName: string, keys: string[], processor: EntryProcessorDef<V, R>): Promise<Map<string, EntryProcessorResult<R>>>;
+    /**
+     * Handle entry processor response from server.
+     * Called by handleServerMessage for ENTRY_PROCESS_RESPONSE messages.
+     */
+    private handleEntryProcessResponse;
+    /**
+     * Handle entry processor batch response from server.
+     * Called by handleServerMessage for ENTRY_PROCESS_BATCH_RESPONSE messages.
+     */
+    private handleEntryProcessBatchResponse;
+    /** Message listeners for journal and other generic messages */
+    private messageListeners;
+    /**
+     * Subscribe to all incoming messages.
+     * Used by EventJournalReader to receive journal events.
+     *
+     * @param event Event type (currently only 'message')
+     * @param handler Message handler
+     */
+    on(event: 'message', handler: (message: any) => void): void;
+    /**
+     * Unsubscribe from incoming messages.
+     *
+     * @param event Event type (currently only 'message')
+     * @param handler Message handler to remove
+     */
+    off(event: 'message', handler: (message: any) => void): void;
+    /**
+     * Send a message to the server.
+     * Public method for EventJournalReader and other components.
+     *
+     * @param message Message object to send
+     */
+    send(message: any): void;
+    /**
+     * Emit message to all listeners.
+     * Called internally when a message is received.
+     */
+    private emitMessage;
+    /**
+     * Get the conflict resolver client for registering custom resolvers
+     * and subscribing to merge rejection events.
+     */
+    getConflictResolverClient(): ConflictResolverClient;
 }
 
 interface ILock {
@@ -558,95 +1049,353 @@ declare class DistributedLock implements ILock {
     isLocked(): boolean;
 }
 
-declare class TopGunClient {
-    private readonly nodeId;
+/**
+ * Client-side handle for a PN Counter.
+ *
+ * Wraps the core PNCounterImpl and integrates with SyncEngine for:
+ * - Automatic sync to server when counter changes
+ * - Receiving remote updates from other clients
+ * - Local persistence via IStorageAdapter (IndexedDB in browser)
+ *
+ * @example
+ * ```typescript
+ * const counter = client.getPNCounter('likes:post-123');
+ * counter.increment(); // Immediate local update + sync to server
+ *
+ * counter.subscribe((value) => {
+ *   console.log('Current likes:', value);
+ * });
+ * ```
+ */
+declare class PNCounterHandle implements PNCounter {
+    private readonly counter;
+    private readonly name;
     private readonly syncEngine;
-    private readonly maps;
-    private readonly storageAdapter;
-    private readonly topicHandles;
-    constructor(config: {
-        nodeId?: string;
-        serverUrl: string;
-        storage: IStorageAdapter;
-        backoff?: Partial<BackoffConfig>;
-        backpressure?: Partial<BackpressureConfig>;
-    });
-    start(): Promise<void>;
-    setAuthToken(token: string): void;
-    setAuthTokenProvider(provider: () => Promise<string | null>): void;
+    private readonly storageAdapter?;
+    private syncScheduled;
+    private persistScheduled;
+    private unsubscribeFromUpdates?;
+    constructor(name: string, nodeId: string, syncEngine: SyncEngine, storageAdapter?: IStorageAdapter);
     /**
-     * Creates a live query subscription for a map.
+     * Restore counter state from local storage.
+     * Called during construction to recover offline state.
      */
-    query<T>(mapName: string, filter: QueryFilter): QueryHandle<T>;
+    private restoreFromStorage;
     /**
-     * Retrieves a distributed lock instance.
-     * @param name The name of the lock.
+     * Persist counter state to local storage.
+     * Debounced to avoid excessive writes during rapid operations.
      */
-    getLock(name: string): DistributedLock;
+    private schedulePersist;
     /**
-     * Retrieves a topic handle for Pub/Sub messaging.
-     * @param name The name of the topic.
+     * Actually persist state to storage.
      */
-    topic(name: string): TopicHandle;
+    private persistToStorage;
     /**
-     * Retrieves an LWWMap instance. If the map doesn't exist locally, it's created.
-     * @param name The name of the map.
-     * @returns An LWWMap instance.
+     * Get current counter value.
      */
-    getMap<K, V>(name: string): LWWMap<K, V>;
+    get(): number;
     /**
-     * Retrieves an ORMap instance. If the map doesn't exist locally, it's created.
-     * @param name The name of the map.
-     * @returns An ORMap instance.
+     * Increment by 1 and return new value.
      */
-    getORMap<K, V>(name: string): ORMap<K, V>;
-    private restoreORMap;
-    private persistORMapKey;
-    private persistORMapTombstones;
+    increment(): number;
     /**
-     * Closes the client, disconnecting from the server and cleaning up resources.
+     * Decrement by 1 and return new value.
      */
-    close(): void;
+    decrement(): number;
     /**
-     * Get the current connection state
+     * Add delta (positive or negative) and return new value.
      */
-    getConnectionState(): SyncState;
+    addAndGet(delta: number): number;
     /**
-     * Subscribe to connection state changes
-     * @param listener Callback function called on each state change
-     * @returns Unsubscribe function
+     * Get state for sync.
      */
-    onConnectionStateChange(listener: (event: StateChangeEvent) => void): () => void;
+    getState(): PNCounterState;
     /**
-     * Get state machine history for debugging
-     * @param limit Maximum number of entries to return
+     * Merge remote state.
      */
-    getStateHistory(limit?: number): StateChangeEvent[];
+    merge(remote: PNCounterState): void;
     /**
-     * Reset the connection and state machine.
-     * Use after fatal errors to start fresh.
+     * Subscribe to value changes.
      */
-    resetConnection(): void;
+    subscribe(listener: (value: number) => void): () => void;
     /**
-     * Get the current number of pending (unacknowledged) operations.
+     * Get the counter name.
      */
-    getPendingOpsCount(): number;
+    getName(): string;
     /**
-     * Get the current backpressure status.
+     * Cleanup resources.
      */
-    getBackpressureStatus(): BackpressureStatus;
+    dispose(): void;
     /**
-     * Returns true if writes are currently paused due to backpressure.
+     * Schedule sync to server with debouncing.
+     * Batches rapid increments to avoid network spam.
      */
-    isBackpressurePaused(): boolean;
+    private scheduleSync;
+}
+
+/**
+ * Serialized journal event from network (bigint as string).
+ */
+interface JournalEventData {
+    sequence: string;
+    type: JournalEventType;
+    mapName: string;
+    key: string;
+    value?: unknown;
+    previousValue?: unknown;
+    timestamp: {
+        millis: number;
+        counter: number;
+        nodeId: string;
+    };
+    nodeId: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for journal subscription.
+ */
+interface JournalSubscribeOptions {
+    /** Start from specific sequence */
+    fromSequence?: bigint;
+    /** Filter by map name */
+    mapName?: string;
+    /** Filter by event types */
+    types?: JournalEventType[];
+}
+/**
+ * Client-side Event Journal Reader.
+ * Communicates with server to read and subscribe to journal events.
+ */
+declare class EventJournalReader {
+    private readonly syncEngine;
+    private readonly listeners;
+    private subscriptionCounter;
+    constructor(syncEngine: SyncEngine);
     /**
-     * Subscribe to backpressure events.
+     * Read events from sequence with optional limit.
      *
-     * Available events:
-     * - 'backpressure:high': Emitted when pending ops reach high water mark
-     * - 'backpressure:low': Emitted when pending ops drop below low water mark
-     * - 'backpressure:paused': Emitted when writes are paused (pause strategy)
-     * - 'backpressure:resumed': Emitted when writes resume after being paused
+     * @param sequence Starting sequence (inclusive)
+     * @param limit Maximum events to return (default: 100)
+     * @returns Promise resolving to array of events
+     */
+    readFrom(sequence: bigint, limit?: number): Promise<JournalEvent[]>;
+    /**
+     * Read events for a specific map.
+     *
+     * @param mapName Map name to filter
+     * @param sequence Starting sequence (default: 0n)
+     * @param limit Maximum events to return (default: 100)
+     */
+    readMapEvents(mapName: string, sequence?: bigint, limit?: number): Promise<JournalEvent[]>;
+    /**
+     * Subscribe to new journal events.
+     *
+     * @param listener Callback for each event
+     * @param options Subscription options
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: (event: JournalEvent) => void, options?: JournalSubscribeOptions): () => void;
+    /**
+     * Get the latest sequence number from server.
+     */
+    getLatestSequence(): Promise<bigint>;
+    /**
+     * Parse network event data to JournalEvent.
+     */
+    private parseEvent;
+    /**
+     * Generate unique request ID.
+     */
+    private generateRequestId;
+}
+
+/**
+ * Cluster mode configuration for TopGunClient.
+ * When provided, the client connects to multiple nodes with partition-aware routing.
+ */
+interface TopGunClusterConfig {
+    /** Initial seed nodes (at least one required) */
+    seeds: string[];
+    /** Connection pool size per node (default: 1) */
+    connectionsPerNode?: number;
+    /** Enable smart routing to partition owner (default: true) */
+    smartRouting?: boolean;
+    /** Partition map refresh interval in ms (default: 30000) */
+    partitionMapRefreshMs?: number;
+    /** Connection timeout per node in ms (default: 5000) */
+    connectionTimeoutMs?: number;
+    /** Retry attempts for failed operations (default: 3) */
+    retryAttempts?: number;
+}
+/**
+ * Default values for cluster configuration
+ */
+declare const DEFAULT_CLUSTER_CONFIG: Required<Omit<TopGunClusterConfig, 'seeds'>>;
+/**
+ * TopGunClient configuration options
+ */
+interface TopGunClientConfig {
+    /** Unique node identifier (auto-generated if not provided) */
+    nodeId?: string;
+    /** Single-server mode: WebSocket URL to connect to */
+    serverUrl?: string;
+    /** Cluster mode: Configuration for multi-node routing */
+    cluster?: TopGunClusterConfig;
+    /** Storage adapter for local persistence */
+    storage: IStorageAdapter;
+    /** Backoff configuration for reconnection */
+    backoff?: Partial<BackoffConfig>;
+    /** Backpressure configuration */
+    backpressure?: Partial<BackpressureConfig>;
+}
+declare class TopGunClient {
+    private readonly nodeId;
+    private readonly syncEngine;
+    private readonly maps;
+    private readonly storageAdapter;
+    private readonly topicHandles;
+    private readonly counters;
+    private readonly clusterClient?;
+    private readonly isClusterMode;
+    private readonly clusterConfig?;
+    constructor(config: TopGunClientConfig);
+    start(): Promise<void>;
+    setAuthToken(token: string): void;
+    setAuthTokenProvider(provider: () => Promise<string | null>): void;
+    /**
+     * Creates a live query subscription for a map.
+     */
+    query<T>(mapName: string, filter: QueryFilter): QueryHandle<T>;
+    /**
+     * Retrieves a distributed lock instance.
+     * @param name The name of the lock.
+     */
+    getLock(name: string): DistributedLock;
+    /**
+     * Retrieves a topic handle for Pub/Sub messaging.
+     * @param name The name of the topic.
+     */
+    topic(name: string): TopicHandle;
+    /**
+     * Retrieves a PN Counter instance. If the counter doesn't exist locally, it's created.
+     * PN Counters support increment and decrement operations that work offline
+     * and sync to server when connected.
+     *
+     * @param name The name of the counter (e.g., 'likes:post-123')
+     * @returns A PNCounterHandle instance
+     *
+     * @example
+     * ```typescript
+     * const likes = client.getPNCounter('likes:post-123');
+     * likes.increment(); // +1
+     * likes.decrement(); // -1
+     * likes.addAndGet(10); // +10
+     *
+     * likes.subscribe((value) => {
+     *   console.log('Current likes:', value);
+     * });
+     * ```
+     */
+    getPNCounter(name: string): PNCounterHandle;
+    /**
+     * Retrieves an LWWMap instance. If the map doesn't exist locally, it's created.
+     * @param name The name of the map.
+     * @returns An LWWMap instance.
+     */
+    getMap<K, V>(name: string): LWWMap<K, V>;
+    /**
+     * Retrieves an ORMap instance. If the map doesn't exist locally, it's created.
+     * @param name The name of the map.
+     * @returns An ORMap instance.
+     */
+    getORMap<K, V>(name: string): ORMap<K, V>;
+    private restoreORMap;
+    private persistORMapKey;
+    private persistORMapTombstones;
+    /**
+     * Closes the client, disconnecting from the server and cleaning up resources.
+     */
+    close(): void;
+    /**
+     * Check if running in cluster mode
+     */
+    isCluster(): boolean;
+    /**
+     * Get list of connected cluster nodes (cluster mode only)
+     * @returns Array of connected node IDs, or empty array in single-server mode
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Get the current partition map version (cluster mode only)
+     * @returns Partition map version, or 0 in single-server mode
+     */
+    getPartitionMapVersion(): number;
+    /**
+     * Check if direct routing is active (cluster mode only)
+     * Direct routing sends operations directly to partition owners.
+     * @returns true if routing is active, false otherwise
+     */
+    isRoutingActive(): boolean;
+    /**
+     * Get health status for all cluster nodes (cluster mode only)
+     * @returns Map of node IDs to their health status
+     */
+    getClusterHealth(): Map<string, NodeHealth>;
+    /**
+     * Force refresh of partition map (cluster mode only)
+     * Use this after detecting routing errors.
+     */
+    refreshPartitionMap(): Promise<void>;
+    /**
+     * Get cluster router statistics (cluster mode only)
+     */
+    getClusterStats(): {
+        mapVersion: number;
+        partitionCount: number;
+        nodeCount: number;
+        lastRefresh: number;
+        isStale: boolean;
+    } | null;
+    /**
+     * Get the current connection state
+     */
+    getConnectionState(): SyncState;
+    /**
+     * Subscribe to connection state changes
+     * @param listener Callback function called on each state change
+     * @returns Unsubscribe function
+     */
+    onConnectionStateChange(listener: (event: StateChangeEvent) => void): () => void;
+    /**
+     * Get state machine history for debugging
+     * @param limit Maximum number of entries to return
+     */
+    getStateHistory(limit?: number): StateChangeEvent[];
+    /**
+     * Reset the connection and state machine.
+     * Use after fatal errors to start fresh.
+     */
+    resetConnection(): void;
+    /**
+     * Get the current number of pending (unacknowledged) operations.
+     */
+    getPendingOpsCount(): number;
+    /**
+     * Get the current backpressure status.
+     */
+    getBackpressureStatus(): BackpressureStatus;
+    /**
+     * Returns true if writes are currently paused due to backpressure.
+     */
+    isBackpressurePaused(): boolean;
+    /**
+     * Subscribe to backpressure events.
+     *
+     * Available events:
+     * - 'backpressure:high': Emitted when pending ops reach high water mark
+     * - 'backpressure:low': Emitted when pending ops drop below low water mark
+     * - 'backpressure:paused': Emitted when writes are paused (pause strategy)
+     * - 'backpressure:resumed': Emitted when writes resume after being paused
      * - 'operation:dropped': Emitted when an operation is dropped (drop-oldest strategy)
      *
      * @param event Event name
@@ -669,6 +1418,144 @@ declare class TopGunClient {
      * ```
      */
     onBackpressure(event: 'backpressure:high' | 'backpressure:low' | 'backpressure:paused' | 'backpressure:resumed' | 'operation:dropped', listener: (data?: BackpressureThresholdEvent | OperationDroppedEvent) => void): () => void;
+    /**
+     * Execute an entry processor on a single key atomically.
+     *
+     * Entry processors solve the read-modify-write race condition by executing
+     * user-defined logic atomically on the server where the data lives.
+     *
+     * @param mapName Name of the map
+     * @param key Key to process
+     * @param processor Processor definition with name, code, and optional args
+     * @returns Promise resolving to the processor result
+     *
+     * @example
+     * ```typescript
+     * // Increment a counter atomically
+     * const result = await client.executeOnKey('stats', 'pageViews', {
+     *   name: 'increment',
+     *   code: `
+     *     const current = value ?? 0;
+     *     return { value: current + 1, result: current + 1 };
+     *   `,
+     * });
+     *
+     * // Using built-in processor
+     * import { BuiltInProcessors } from '@topgunbuild/core';
+     * const result = await client.executeOnKey(
+     *   'stats',
+     *   'pageViews',
+     *   BuiltInProcessors.INCREMENT(1)
+     * );
+     * ```
+     */
+    executeOnKey<V, R = V>(mapName: string, key: string, processor: EntryProcessorDef<V, R>): Promise<EntryProcessorResult<R>>;
+    /**
+     * Execute an entry processor on multiple keys.
+     *
+     * Each key is processed atomically. The operation returns when all keys
+     * have been processed.
+     *
+     * @param mapName Name of the map
+     * @param keys Keys to process
+     * @param processor Processor definition
+     * @returns Promise resolving to a map of key -> result
+     *
+     * @example
+     * ```typescript
+     * // Reset multiple counters
+     * const results = await client.executeOnKeys(
+     *   'stats',
+     *   ['pageViews', 'uniqueVisitors', 'bounceRate'],
+     *   {
+     *     name: 'reset',
+     *     code: `return { value: 0, result: value };`, // Returns old value
+     *   }
+     * );
+     *
+     * for (const [key, result] of results) {
+     *   console.log(`${key}: was ${result.result}, now 0`);
+     * }
+     * ```
+     */
+    executeOnKeys<V, R = V>(mapName: string, keys: string[], processor: EntryProcessorDef<V, R>): Promise<Map<string, EntryProcessorResult<R>>>;
+    /** Cached EventJournalReader instance */
+    private journalReader?;
+    /**
+     * Get the Event Journal reader for subscribing to and reading
+     * map change events.
+     *
+     * The Event Journal provides:
+     * - Append-only log of all map changes (PUT, UPDATE, DELETE)
+     * - Subscription to real-time events
+     * - Historical event replay
+     * - Audit trail for compliance
+     *
+     * @returns EventJournalReader instance
+     *
+     * @example
+     * ```typescript
+     * const journal = client.getEventJournal();
+     *
+     * // Subscribe to all events
+     * const unsubscribe = journal.subscribe((event) => {
+     *   console.log(`${event.type} on ${event.mapName}:${event.key}`);
+     * });
+     *
+     * // Subscribe to specific map
+     * journal.subscribe(
+     *   (event) => console.log('User changed:', event.key),
+     *   { mapName: 'users' }
+     * );
+     *
+     * // Read historical events
+     * const events = await journal.readFrom(0n, 100);
+     * ```
+     */
+    getEventJournal(): EventJournalReader;
+    /**
+     * Get the conflict resolver client for registering custom merge resolvers.
+     *
+     * Conflict resolvers allow you to customize how merge conflicts are handled
+     * on the server. You can implement business logic like:
+     * - First-write-wins for booking systems
+     * - Numeric constraints (non-negative, min/max)
+     * - Owner-only modifications
+     * - Custom merge strategies
+     *
+     * @returns ConflictResolverClient instance
+     *
+     * @example
+     * ```typescript
+     * const resolvers = client.getConflictResolvers();
+     *
+     * // Register a first-write-wins resolver
+     * await resolvers.register('bookings', {
+     *   name: 'first-write-wins',
+     *   code: `
+     *     if (context.localValue !== undefined) {
+     *       return { action: 'reject', reason: 'Slot already booked' };
+     *     }
+     *     return { action: 'accept', value: context.remoteValue };
+     *   `,
+     *   priority: 100,
+     * });
+     *
+     * // Subscribe to merge rejections
+     * resolvers.onRejection((rejection) => {
+     *   console.log(`Merge rejected: ${rejection.reason}`);
+     *   // Optionally refresh local state
+     * });
+     *
+     * // List registered resolvers
+     * const registered = await resolvers.list('bookings');
+     * console.log('Active resolvers:', registered);
+     *
+     * // Unregister when done
+     * await resolvers.unregister('bookings', 'first-write-wins');
+     * ```
+     */
+    getConflictResolvers(): ConflictResolverClient;
 }
 
 interface TopGunConfig {
@@ -797,6 +1684,574 @@ declare class BackpressureError extends Error {
     constructor(pendingCount: number, maxPending: number);
 }
 
+/**
+ * ConnectionPool - Manages WebSocket connections to multiple cluster nodes
+ *
+ * Phase 4: Partition-Aware Client Routing
+ *
+ * Features:
+ * - Maintains connections to all known cluster nodes
+ * - Automatic reconnection with exponential backoff
+ * - Health monitoring and status tracking
+ * - Connection lifecycle management
+ */
+
+interface ConnectionPoolEvents {
+    'node:connected': (nodeId: string) => void;
+    'node:disconnected': (nodeId: string, reason: string) => void;
+    'node:healthy': (nodeId: string) => void;
+    'node:unhealthy': (nodeId: string, reason: string) => void;
+    'message': (nodeId: string, message: any) => void;
+    'error': (nodeId: string, error: Error) => void;
+}
+declare class ConnectionPool {
+    private readonly listeners;
+    private readonly config;
+    private readonly connections;
+    private primaryNodeId;
+    private healthCheckTimer;
+    private authToken;
+    constructor(config?: Partial<ConnectionPoolConfig>);
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+    /**
+     * Set authentication token for all connections
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Add a node to the connection pool
+     */
+    addNode(nodeId: string, endpoint: string): Promise<void>;
+    /**
+     * Remove a node from the connection pool
+     */
+    removeNode(nodeId: string): Promise<void>;
+    /**
+     * Get connection for a specific node
+     */
+    getConnection(nodeId: string): WebSocket | null;
+    /**
+     * Get primary connection (first/seed node)
+     */
+    getPrimaryConnection(): WebSocket | null;
+    /**
+     * Get any healthy connection
+     */
+    getAnyHealthyConnection(): {
+        nodeId: string;
+        socket: WebSocket;
+    } | null;
+    /**
+     * Send message to a specific node
+     */
+    send(nodeId: string, message: any): boolean;
+    /**
+     * Send message to primary node
+     */
+    sendToPrimary(message: any): boolean;
+    /**
+     * Get health status for all nodes
+     */
+    getHealthStatus(): Map<string, NodeHealth>;
+    /**
+     * Get list of connected node IDs
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Get all node IDs
+     */
+    getAllNodes(): string[];
+    /**
+     * Check if node is connected and authenticated
+     */
+    isNodeConnected(nodeId: string): boolean;
+    /**
+     * Check if connected to a specific node.
+     * Alias for isNodeConnected() for IConnectionProvider compatibility.
+     */
+    isConnected(nodeId: string): boolean;
+    /**
+     * Start health monitoring
+     */
+    startHealthCheck(): void;
+    /**
+     * Stop health monitoring
+     */
+    stopHealthCheck(): void;
+    /**
+     * Close all connections and cleanup
+     */
+    close(): void;
+    private connect;
+    private sendAuth;
+    private handleMessage;
+    private flushPendingMessages;
+    private scheduleReconnect;
+    private performHealthCheck;
+}
+
+/**
+ * PartitionRouter - Routes operations to the correct cluster node
+ *
+ * Phase 4: Partition-Aware Client Routing
+ *
+ * Features:
+ * - Maintains local copy of partition map
+ * - Routes keys to owner nodes using consistent hashing
+ * - Handles stale routing with automatic refresh
+ * - Supports fallback to server-side forwarding
+ */
+
+interface RoutingResult {
+    nodeId: string;
+    partitionId: number;
+    isOwner: boolean;
+    isBackup: boolean;
+}
+interface PartitionRouterEvents {
+    'partitionMap:updated': (version: number, changesCount: number) => void;
+    'partitionMap:stale': (currentVersion: number, lastRefresh: number) => void;
+    'routing:miss': (key: string, expectedOwner: string, actualOwner: string) => void;
+}
+declare class PartitionRouter {
+    private readonly listeners;
+    private readonly config;
+    private readonly connectionPool;
+    private partitionMap;
+    private lastRefreshTime;
+    private refreshTimer;
+    private pendingRefresh;
+    constructor(connectionPool: ConnectionPool, config?: Partial<PartitionRouterConfig>);
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeListener(event: string, listener: (...args: any[]) => void): this;
+    removeAllListeners(event?: string): this;
+    /**
+     * Get the partition ID for a given key
+     */
+    getPartitionId(key: string): number;
+    /**
+     * Route a key to the owner node
+     */
+    route(key: string): RoutingResult | null;
+    /**
+     * Route a key and get the WebSocket connection to use
+     */
+    routeToConnection(key: string): {
+        nodeId: string;
+        socket: WebSocket;
+    } | null;
+    /**
+     * Get routing info for multiple keys (batch routing)
+     */
+    routeBatch(keys: string[]): Map<string, RoutingResult[]>;
+    /**
+     * Get all partitions owned by a specific node
+     */
+    getPartitionsForNode(nodeId: string): number[];
+    /**
+     * Get current partition map version
+     */
+    getMapVersion(): number;
+    /**
+     * Check if partition map is available
+     */
+    hasPartitionMap(): boolean;
+    /**
+     * Get owner node for a key.
+     * Returns null if partition map is not available.
+     */
+    getOwner(key: string): string | null;
+    /**
+     * Get backup nodes for a key.
+     * Returns empty array if partition map is not available.
+     */
+    getBackups(key: string): string[];
+    /**
+     * Get the full partition map.
+     * Returns null if not available.
+     */
+    getMap(): PartitionMap | null;
+    /**
+     * Update entire partition map.
+     * Only accepts newer versions.
+     */
+    updateMap(map: PartitionMap): boolean;
+    /**
+     * Update a single partition (for delta updates).
+     */
+    updatePartition(partitionId: number, owner: string, backups: string[]): void;
+    /**
+     * Check if partition map is stale
+     */
+    isMapStale(): boolean;
+    /**
+     * Request fresh partition map from server
+     */
+    refreshPartitionMap(): Promise<void>;
+    /**
+     * Start periodic partition map refresh
+     */
+    startPeriodicRefresh(): void;
+    /**
+     * Stop periodic refresh
+     */
+    stopPeriodicRefresh(): void;
+    /**
+     * Handle NOT_OWNER error from server
+     */
+    handleNotOwnerError(key: string, actualOwner: string, newMapVersion: number): void;
+    /**
+     * Get statistics about routing
+     */
+    getStats(): {
+        mapVersion: number;
+        partitionCount: number;
+        nodeCount: number;
+        lastRefresh: number;
+        isStale: boolean;
+    };
+    /**
+     * Cleanup resources
+     */
+    close(): void;
+    private handlePartitionMap;
+    private handlePartitionMapDelta;
+    private applyPartitionChange;
+    private updateConnectionPool;
+    private doRefreshPartitionMap;
+}
+
+/**
+ * ClusterClient - Cluster-aware client wrapper
+ *
+ * Phase 4: Partition-Aware Client Routing
+ * Phase 4.5: Implements IConnectionProvider for SyncEngine abstraction
+ *
+ * Wraps the standard TopGunClient with cluster-aware routing capabilities.
+ * Coordinates between ConnectionPool and PartitionRouter for optimal
+ * request routing in a clustered environment.
+ */
+
+interface ClusterClientEvents {
+    'connected': () => void;
+    'disconnected': (reason: string) => void;
+    'partitionMap:ready': (version: number) => void;
+    'routing:active': () => void;
+    'error': (error: Error) => void;
+    'circuit:open': (nodeId: string) => void;
+    'circuit:closed': (nodeId: string) => void;
+    'circuit:half-open': (nodeId: string) => void;
+}
+/**
+ * Circuit breaker state for a node.
+ */
+interface CircuitState {
+    /** Number of consecutive failures */
+    failures: number;
+    /** Timestamp of last failure */
+    lastFailure: number;
+    /** Current circuit state */
+    state: 'closed' | 'open' | 'half-open';
+}
+/**
+ * Routing metrics for monitoring smart routing effectiveness.
+ */
+interface RoutingMetrics {
+    /** Operations routed directly to partition owner */
+    directRoutes: number;
+    /** Operations falling back to any node (owner unavailable) */
+    fallbackRoutes: number;
+    /** Operations when partition map is missing/stale */
+    partitionMisses: number;
+    /** Total routing decisions made */
+    totalRoutes: number;
+}
+type ClusterRoutingMode = 'direct' | 'forward';
+/**
+ * ClusterClient implements IConnectionProvider for multi-node cluster mode.
+ * It provides partition-aware routing and connection management.
+ */
+declare class ClusterClient implements IConnectionProvider {
+    private readonly listeners;
+    private readonly connectionPool;
+    private readonly partitionRouter;
+    private readonly config;
+    private initialized;
+    private routingActive;
+    private readonly routingMetrics;
+    private readonly circuits;
+    private readonly circuitBreakerConfig;
+    constructor(config: ClusterClientConfig);
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+    /**
+     * Connect to cluster nodes (IConnectionProvider interface).
+     * Alias for start() method.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key (IConnectionProvider interface).
+     * Routes to partition owner based on key hash when smart routing is enabled.
+     * @throws Error if not connected
+     */
+    getConnection(key: string): WebSocket;
+    /**
+     * Get fallback connection when owner is unavailable.
+     * @throws Error if no connection available
+     */
+    private getFallbackConnection;
+    /**
+     * Request a partition map refresh in the background.
+     * Called when routing to an unknown/disconnected owner.
+     */
+    private requestPartitionMapRefresh;
+    /**
+     * Request partition map from a specific node.
+     * Called on first node connection.
+     */
+    private requestPartitionMapFromNode;
+    /**
+     * Check if at least one connection is active (IConnectionProvider interface).
+     */
+    isConnected(): boolean;
+    /**
+     * Send data via the appropriate connection (IConnectionProvider interface).
+     * Routes based on key if provided.
+     */
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Send data with automatic retry and rerouting on failure.
+     * @param data - Data to send
+     * @param key - Optional key for routing
+     * @param options - Retry options
+     * @throws Error after max retries exceeded
+     */
+    sendWithRetry(data: ArrayBuffer | Uint8Array, key?: string, options?: {
+        maxRetries?: number;
+        retryDelayMs?: number;
+        retryOnNotOwner?: boolean;
+    }): Promise<void>;
+    /**
+     * Check if an error is retryable.
+     */
+    private isRetryableError;
+    /**
+     * Wait for partition map update.
+     */
+    private waitForPartitionMapUpdateInternal;
+    /**
+     * Wait for at least one connection to be available.
+     */
+    private waitForConnectionInternal;
+    /**
+     * Helper delay function.
+     */
+    private delay;
+    /**
+     * Initialize cluster connections
+     */
+    start(): Promise<void>;
+    /**
+     * Set authentication token
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Send operation with automatic routing (legacy API for cluster operations).
+     * @deprecated Use send(data, key) for IConnectionProvider interface
+     */
+    sendMessage(key: string, message: any): boolean;
+    /**
+     * Send directly to partition owner
+     */
+    sendDirect(key: string, message: any): boolean;
+    /**
+     * Send to primary node for server-side forwarding
+     */
+    sendForward(message: any): boolean;
+    /**
+     * Send batch of operations with routing
+     */
+    sendBatch(operations: Array<{
+        key: string;
+        message: any;
+    }>): Map<string, boolean>;
+    /**
+     * Get connection pool health status
+     */
+    getHealthStatus(): Map<string, NodeHealth>;
+    /**
+     * Get partition router stats
+     */
+    getRouterStats(): ReturnType<PartitionRouter['getStats']>;
+    /**
+     * Get routing metrics for monitoring smart routing effectiveness.
+     */
+    getRoutingMetrics(): RoutingMetrics;
+    /**
+     * Reset routing metrics counters.
+     * Useful for monitoring intervals.
+     */
+    resetRoutingMetrics(): void;
+    /**
+     * Check if cluster routing is active
+     */
+    isRoutingActive(): boolean;
+    /**
+     * Get list of connected nodes
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Check if cluster client is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Force refresh of partition map
+     */
+    refreshPartitionMap(): Promise<void>;
+    /**
+     * Shutdown cluster client (IConnectionProvider interface).
+     */
+    close(): Promise<void>;
+    /**
+     * Get the connection pool (for internal use)
+     */
+    getConnectionPool(): ConnectionPool;
+    /**
+     * Get the partition router (for internal use)
+     */
+    getPartitionRouter(): PartitionRouter;
+    /**
+     * Get any healthy WebSocket connection (IConnectionProvider interface).
+     * @throws Error if not connected
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Get any healthy WebSocket connection, or null if none available.
+     * Use this for optional connection checks.
+     */
+    getAnyConnectionOrNull(): WebSocket | null;
+    /**
+     * Get circuit breaker state for a node.
+     */
+    getCircuit(nodeId: string): CircuitState;
+    /**
+     * Check if a node can be used (circuit not open).
+     */
+    canUseNode(nodeId: string): boolean;
+    /**
+     * Record a successful operation to a node.
+     * Resets circuit breaker on success.
+     */
+    recordSuccess(nodeId: string): void;
+    /**
+     * Record a failed operation to a node.
+     * Opens circuit breaker after threshold failures.
+     */
+    recordFailure(nodeId: string): void;
+    /**
+     * Get all circuit breaker states.
+     */
+    getCircuitStates(): Map<string, CircuitState>;
+    /**
+     * Reset circuit breaker for a specific node.
+     */
+    resetCircuit(nodeId: string): void;
+    /**
+     * Reset all circuit breakers.
+     */
+    resetAllCircuits(): void;
+    private setupEventHandlers;
+    private waitForPartitionMap;
+}
+
+/**
+ * SingleServerProvider implements IConnectionProvider for single-server mode.
+ *
+ * This is an adapter that wraps direct WebSocket connection handling,
+ * providing the same interface used by ClusterClient for multi-node mode.
+ */
+declare class SingleServerProvider implements IConnectionProvider {
+    private readonly url;
+    private readonly config;
+    private ws;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private isClosing;
+    private listeners;
+    constructor(config: SingleServerProviderConfig);
+    /**
+     * Connect to the WebSocket server.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * In single-server mode, key is ignored.
+     */
+    getConnection(_key: string): WebSocket;
+    /**
+     * Get any available connection.
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Get connected node IDs.
+     * Single-server mode returns ['default'] when connected.
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Subscribe to connection events.
+     */
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Unsubscribe from connection events.
+     */
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Send data via the WebSocket connection.
+     * In single-server mode, key parameter is ignored.
+     */
+    send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Close the WebSocket connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Calculate backoff delay with exponential increase.
+     */
+    private calculateBackoffDelay;
+    /**
+     * Get the WebSocket URL this provider connects to.
+     */
+    getUrl(): string;
+    /**
+     * Get current reconnection attempt count.
+     */
+    getReconnectAttempts(): number;
+    /**
+     * Reset reconnection counter.
+     * Called externally after successful authentication.
+     */
+    resetReconnectAttempts(): void;
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, DEFAULT_BACKPRESSURE_CONFIG, EncryptedStorageAdapter, type HeartbeatConfig, IDBAdapter, type IStorageAdapter, type OpLogEntry, type OperationDroppedEvent, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };
+export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };