@topgunbuild/client 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -203,6 +203,233 @@ var DEFAULT_BACKPRESSURE_CONFIG = {
   lowWaterMark: 0.5
 };
 
+// src/connection/SingleServerProvider.ts
+var DEFAULT_CONFIG = {
+  maxReconnectAttempts: 10,
+  reconnectDelayMs: 1e3,
+  backoffMultiplier: 2,
+  maxReconnectDelayMs: 3e4
+};
+var SingleServerProvider = class {
+  constructor(config) {
+    this.ws = null;
+    this.reconnectAttempts = 0;
+    this.reconnectTimer = null;
+    this.isClosing = false;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.url = config.url;
+    this.config = {
+      url: config.url,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts,
+      reconnectDelayMs: config.reconnectDelayMs ?? DEFAULT_CONFIG.reconnectDelayMs,
+      backoffMultiplier: config.backoffMultiplier ?? DEFAULT_CONFIG.backoffMultiplier,
+      maxReconnectDelayMs: config.maxReconnectDelayMs ?? DEFAULT_CONFIG.maxReconnectDelayMs
+    };
+  }
+  /**
+   * Connect to the WebSocket server.
+   */
+  async connect() {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      return;
+    }
+    this.isClosing = false;
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.url);
+        this.ws.binaryType = "arraybuffer";
+        this.ws.onopen = () => {
+          this.reconnectAttempts = 0;
+          logger.info({ url: this.url }, "SingleServerProvider connected");
+          this.emit("connected", "default");
+          resolve();
+        };
+        this.ws.onerror = (error) => {
+          logger.error({ err: error, url: this.url }, "SingleServerProvider WebSocket error");
+          this.emit("error", error);
+        };
+        this.ws.onclose = (event) => {
+          logger.info({ url: this.url, code: event.code }, "SingleServerProvider disconnected");
+          this.emit("disconnected", "default");
+          if (!this.isClosing) {
+            this.scheduleReconnect();
+          }
+        };
+        this.ws.onmessage = (event) => {
+          this.emit("message", "default", event.data);
+        };
+        const timeoutId = setTimeout(() => {
+          if (this.ws && this.ws.readyState === WebSocket.CONNECTING) {
+            this.ws.close();
+            reject(new Error(`Connection timeout to ${this.url}`));
+          }
+        }, this.config.reconnectDelayMs * 5);
+        const originalOnOpen = this.ws.onopen;
+        const wsRef = this.ws;
+        this.ws.onopen = (ev) => {
+          clearTimeout(timeoutId);
+          if (originalOnOpen) {
+            originalOnOpen.call(wsRef, ev);
+          }
+        };
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+  /**
+   * Get connection for a specific key.
+   * In single-server mode, key is ignored.
+   */
+  getConnection(_key) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("Not connected");
+    }
+    return this.ws;
+  }
+  /**
+   * Get any available connection.
+   */
+  getAnyConnection() {
+    return this.getConnection("");
+  }
+  /**
+   * Check if connected.
+   */
+  isConnected() {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+  /**
+   * Get connected node IDs.
+   * Single-server mode returns ['default'] when connected.
+   */
+  getConnectedNodes() {
+    return this.isConnected() ? ["default"] : [];
+  }
+  /**
+   * Subscribe to connection events.
+   */
+  on(event, handler2) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(handler2);
+  }
+  /**
+   * Unsubscribe from connection events.
+   */
+  off(event, handler2) {
+    this.listeners.get(event)?.delete(handler2);
+  }
+  /**
+   * Send data via the WebSocket connection.
+   * In single-server mode, key parameter is ignored.
+   */
+  send(data, _key) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("Not connected");
+    }
+    this.ws.send(data);
+  }
+  /**
+   * Close the WebSocket connection.
+   */
+  async close() {
+    this.isClosing = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.onerror = null;
+      this.ws.onmessage = null;
+      if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+        this.ws.close();
+      }
+      this.ws = null;
+    }
+    logger.info({ url: this.url }, "SingleServerProvider closed");
+  }
+  /**
+   * Emit an event to all listeners.
+   */
+  emit(event, ...args) {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      for (const handler2 of handlers) {
+        try {
+          handler2(...args);
+        } catch (err) {
+          logger.error({ err, event }, "Error in SingleServerProvider event handler");
+        }
+      }
+    }
+  }
+  /**
+   * Schedule a reconnection attempt with exponential backoff.
+   */
+  scheduleReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      logger.error(
+        { attempts: this.reconnectAttempts, url: this.url },
+        "SingleServerProvider max reconnect attempts reached"
+      );
+      this.emit("error", new Error("Max reconnection attempts reached"));
+      return;
+    }
+    const delay = this.calculateBackoffDelay();
+    logger.info(
+      { delay, attempt: this.reconnectAttempts, url: this.url },
+      `SingleServerProvider scheduling reconnect in ${delay}ms`
+    );
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      this.reconnectAttempts++;
+      try {
+        await this.connect();
+        this.emit("reconnected", "default");
+      } catch (error) {
+        logger.error({ err: error }, "SingleServerProvider reconnection failed");
+        this.scheduleReconnect();
+      }
+    }, delay);
+  }
+  /**
+   * Calculate backoff delay with exponential increase.
+   */
+  calculateBackoffDelay() {
+    const { reconnectDelayMs, backoffMultiplier, maxReconnectDelayMs } = this.config;
+    let delay = reconnectDelayMs * Math.pow(backoffMultiplier, this.reconnectAttempts);
+    delay = Math.min(delay, maxReconnectDelayMs);
+    delay = delay * (0.5 + Math.random());
+    return Math.floor(delay);
+  }
+  /**
+   * Get the WebSocket URL this provider connects to.
+   */
+  getUrl() {
+    return this.url;
+  }
+  /**
+   * Get current reconnection attempt count.
+   */
+  getReconnectAttempts() {
+    return this.reconnectAttempts;
+  }
+  /**
+   * Reset reconnection counter.
+   * Called externally after successful authentication.
+   */
+  resetReconnectAttempts() {
+    this.reconnectAttempts = 0;
+  }
+};
+
 // src/SyncEngine.ts
 var DEFAULT_BACKOFF_CONFIG = {
   initialDelayMs: 1e3,
@@ -232,8 +459,13 @@ var SyncEngine = class {
     this.waitingForCapacity = [];
     this.highWaterMarkEmitted = false;
     this.backpressureListeners = /* @__PURE__ */ new Map();
+    // Write Concern state (Phase 5.01)
+    this.pendingWriteConcernPromises = /* @__PURE__ */ new Map();
+    if (!config.serverUrl && !config.connectionProvider) {
+      throw new Error("SyncEngine requires either serverUrl or connectionProvider");
+    }
     this.nodeId = config.nodeId;
-    this.serverUrl = config.serverUrl;
+    this.serverUrl = config.serverUrl || "";
     this.storageAdapter = config.storageAdapter;
     this.hlc = new HLC(this.nodeId);
     this.stateMachine = new SyncStateMachine();
@@ -250,7 +482,15 @@ var SyncEngine = class {
       ...DEFAULT_BACKPRESSURE_CONFIG,
       ...config.backpressure
     };
-    this.initConnection();
+    if (config.connectionProvider) {
+      this.connectionProvider = config.connectionProvider;
+      this.useConnectionProvider = true;
+      this.initConnectionProvider();
+    } else {
+      this.connectionProvider = new SingleServerProvider({ url: config.serverUrl });
+      this.useConnectionProvider = false;
+      this.initConnection();
+    }
     this.loadOpLog();
   }
   // ============================================
@@ -301,6 +541,65 @@ var SyncEngine = class {
   // ============================================
   // Connection Management
   // ============================================
+  /**
+   * Initialize connection using IConnectionProvider (Phase 4.5 cluster mode).
+   * Sets up event handlers for the connection provider.
+   */
+  initConnectionProvider() {
+    this.stateMachine.transition("CONNECTING" /* CONNECTING */);
+    this.connectionProvider.on("connected", (_nodeId) => {
+      if (this.authToken || this.tokenProvider) {
+        logger.info("ConnectionProvider connected. Sending auth...");
+        this.stateMachine.transition("AUTHENTICATING" /* AUTHENTICATING */);
+        this.sendAuth();
+      } else {
+        logger.info("ConnectionProvider connected. Waiting for auth token...");
+        this.stateMachine.transition("AUTHENTICATING" /* AUTHENTICATING */);
+      }
+    });
+    this.connectionProvider.on("disconnected", (_nodeId) => {
+      logger.info("ConnectionProvider disconnected.");
+      this.stopHeartbeat();
+      this.stateMachine.transition("DISCONNECTED" /* DISCONNECTED */);
+    });
+    this.connectionProvider.on("reconnected", (_nodeId) => {
+      logger.info("ConnectionProvider reconnected.");
+      this.stateMachine.transition("CONNECTING" /* CONNECTING */);
+      if (this.authToken || this.tokenProvider) {
+        this.stateMachine.transition("AUTHENTICATING" /* AUTHENTICATING */);
+        this.sendAuth();
+      }
+    });
+    this.connectionProvider.on("message", (_nodeId, data) => {
+      let message;
+      if (data instanceof ArrayBuffer) {
+        message = deserialize(new Uint8Array(data));
+      } else if (data instanceof Uint8Array) {
+        message = deserialize(data);
+      } else {
+        try {
+          message = typeof data === "string" ? JSON.parse(data) : data;
+        } catch (e) {
+          logger.error({ err: e }, "Failed to parse message from ConnectionProvider");
+          return;
+        }
+      }
+      this.handleServerMessage(message);
+    });
+    this.connectionProvider.on("partitionMapUpdated", () => {
+      logger.debug("Partition map updated");
+    });
+    this.connectionProvider.on("error", (error) => {
+      logger.error({ err: error }, "ConnectionProvider error");
+    });
+    this.connectionProvider.connect().catch((err) => {
+      logger.error({ err }, "Failed to connect via ConnectionProvider");
+      this.stateMachine.transition("DISCONNECTED" /* DISCONNECTED */);
+    });
+  }
+  /**
+   * Initialize connection using direct WebSocket (legacy single-server mode).
+   */
   initConnection() {
     this.stateMachine.transition("CONNECTING" /* CONNECTING */);
     this.websocket = new WebSocket(this.serverUrl);
@@ -376,6 +675,40 @@ var SyncEngine = class {
   resetBackoff() {
     this.backoffAttempt = 0;
   }
+  /**
+   * 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
+   */
+  sendMessage(message, key) {
+    const data = serialize(message);
+    if (this.useConnectionProvider) {
+      try {
+        this.connectionProvider.send(data, key);
+        return true;
+      } catch (err) {
+        logger.warn({ err }, "Failed to send via ConnectionProvider");
+        return false;
+      }
+    } else {
+      if (this.websocket?.readyState === WebSocket.OPEN) {
+        this.websocket.send(data);
+        return true;
+      }
+      return false;
+    }
+  }
+  /**
+   * Check if we can send messages (connection is ready).
+   */
+  canSend() {
+    if (this.useConnectionProvider) {
+      return this.connectionProvider.isConnected();
+    }
+    return this.websocket?.readyState === WebSocket.OPEN;
+  }
   async loadOpLog() {
     const storedTimestamp = await this.storageAdapter.getMeta("lastSyncTimestamp");
     if (storedTimestamp) {
@@ -422,36 +755,34 @@ var SyncEngine = class {
     const pending = this.opLog.filter((op) => !op.synced);
     if (pending.length === 0) return;
     logger.info({ count: pending.length }, "Syncing pending operations");
-    if (this.websocket?.readyState === WebSocket.OPEN) {
-      this.websocket.send(serialize({
-        type: "OP_BATCH",
-        payload: {
-          ops: pending
-        }
-      }));
-    }
+    this.sendMessage({
+      type: "OP_BATCH",
+      payload: {
+        ops: pending
+      }
+    });
   }
   startMerkleSync() {
     for (const [mapName, map] of this.maps) {
       if (map instanceof LWWMap) {
         logger.info({ mapName }, "Starting Merkle sync for LWWMap");
-        this.websocket?.send(serialize({
+        this.sendMessage({
           type: "SYNC_INIT",
           mapName,
           lastSyncTimestamp: this.lastSyncTimestamp
-        }));
+        });
       } else if (map instanceof ORMap) {
         logger.info({ mapName }, "Starting Merkle sync for ORMap");
         const tree = map.getMerkleTree();
         const rootHash = tree.getRootHash();
         const bucketHashes = tree.getBuckets("");
-        this.websocket?.send(serialize({
+        this.sendMessage({
           type: "ORMAP_SYNC_INIT",
           mapName,
           rootHash,
           bucketHashes,
           lastSyncTimestamp: this.lastSyncTimestamp
-        }));
+        });
       }
     }
   }
@@ -492,10 +823,10 @@ var SyncEngine = class {
     }
     const token = this.authToken;
     if (!token) return;
-    this.websocket?.send(serialize({
+    this.sendMessage({
       type: "AUTH",
       token
-    }));
+    });
   }
   subscribeToQuery(query) {
     this.queries.set(query.id, query);
@@ -512,27 +843,27 @@ var SyncEngine = class {
   unsubscribeFromTopic(topic) {
     this.topics.delete(topic);
     if (this.isAuthenticated()) {
-      this.websocket?.send(serialize({
+      this.sendMessage({
         type: "TOPIC_UNSUB",
         payload: { topic }
-      }));
+      });
     }
   }
   publishTopic(topic, data) {
     if (this.isAuthenticated()) {
-      this.websocket?.send(serialize({
+      this.sendMessage({
         type: "TOPIC_PUB",
         payload: { topic, data }
-      }));
+      });
     } else {
       logger.warn({ topic }, "Dropped topic publish (offline)");
     }
   }
   sendTopicSubscription(topic) {
-    this.websocket?.send(serialize({
+    this.sendMessage({
       type: "TOPIC_SUB",
       payload: { topic }
-    }));
+    });
   }
   /**
    * Executes a query against local storage immediately
@@ -569,21 +900,21 @@ var SyncEngine = class {
   unsubscribeFromQuery(queryId) {
     this.queries.delete(queryId);
     if (this.isAuthenticated()) {
-      this.websocket?.send(serialize({
+      this.sendMessage({
         type: "QUERY_UNSUB",
         payload: { queryId }
-      }));
+      });
     }
   }
   sendQuerySubscription(query) {
-    this.websocket?.send(serialize({
+    this.sendMessage({
       type: "QUERY_SUB",
       payload: {
         queryId: query.id,
         mapName: query.getMapName(),
         query: query.getFilter()
       }
-    }));
+    });
   }
   requestLock(name, requestId, ttl) {
     if (!this.isAuthenticated()) {
@@ -598,10 +929,15 @@ var SyncEngine = class {
       }, 3e4);
       this.pendingLockRequests.set(requestId, { resolve, reject, timer });
       try {
-        this.websocket?.send(serialize({
+        const sent = this.sendMessage({
           type: "LOCK_REQUEST",
           payload: { requestId, name, ttl }
-        }));
+        });
+        if (!sent) {
+          clearTimeout(timer);
+          this.pendingLockRequests.delete(requestId);
+          reject(new Error("Failed to send lock request"));
+        }
       } catch (e) {
         clearTimeout(timer);
         this.pendingLockRequests.delete(requestId);
@@ -620,10 +956,15 @@ var SyncEngine = class {
       }, 5e3);
       this.pendingLockRequests.set(requestId, { resolve, reject, timer });
       try {
-        this.websocket?.send(serialize({
+        const sent = this.sendMessage({
           type: "LOCK_RELEASE",
           payload: { requestId, name, fencingToken }
-        }));
+        });
+        if (!sent) {
+          clearTimeout(timer);
+          this.pendingLockRequests.delete(requestId);
+          resolve(false);
+        }
       } catch (e) {
         clearTimeout(timer);
         this.pendingLockRequests.delete(requestId);
@@ -633,6 +974,22 @@ var SyncEngine = class {
   }
   async handleServerMessage(message) {
     switch (message.type) {
+      case "BATCH": {
+        const batchData = message.data;
+        const view = new DataView(batchData.buffer, batchData.byteOffset, batchData.byteLength);
+        let offset = 0;
+        const count = view.getUint32(offset, true);
+        offset += 4;
+        for (let i = 0; i < count; i++) {
+          const msgLen = view.getUint32(offset, true);
+          offset += 4;
+          const msgData = batchData.slice(offset, offset + msgLen);
+          offset += msgLen;
+          const innerMsg = deserialize(msgData);
+          await this.handleServerMessage(innerMsg);
+        }
+        break;
+      }
       case "AUTH_REQUIRED":
         this.sendAuth();
         break;
@@ -664,8 +1021,18 @@ var SyncEngine = class {
         this.authToken = null;
         break;
       case "OP_ACK": {
-        const { lastId } = message.payload;
-        logger.info({ lastId }, "Received ACK for ops");
+        const { lastId, achievedLevel, results } = message.payload;
+        logger.info({ lastId, achievedLevel, hasResults: !!results }, "Received ACK for ops");
+        if (results && Array.isArray(results)) {
+          for (const result of results) {
+            const op = this.opLog.find((o) => o.id === result.opId);
+            if (op && !op.synced) {
+              op.synced = true;
+              logger.debug({ opId: result.opId, achievedLevel: result.achievedLevel, success: result.success }, "Op ACK with Write Concern");
+            }
+            this.resolveWriteConcernPromise(result.opId, result);
+          }
+        }
         let maxSyncedId = -1;
         let ackedCount = 0;
         this.opLog.forEach((op) => {
@@ -726,18 +1093,20 @@ var SyncEngine = class {
       }
       case "SERVER_EVENT": {
         const { mapName, eventType, key, record, orRecord, orTag } = message.payload;
-        const localMap = this.maps.get(mapName);
-        if (localMap) {
-          if (localMap instanceof LWWMap && record) {
-            localMap.merge(key, record);
-            await this.storageAdapter.put(`${mapName}:${key}`, record);
-          } else if (localMap instanceof ORMap) {
-            if (eventType === "OR_ADD" && orRecord) {
-              localMap.apply(key, orRecord);
-            } else if (eventType === "OR_REMOVE" && orTag) {
-              localMap.applyTombstone(orTag);
-            }
-          }
+        await this.applyServerEvent(mapName, eventType, key, record, orRecord, orTag);
+        break;
+      }
+      case "SERVER_BATCH_EVENT": {
+        const { events } = message.payload;
+        for (const event of events) {
+          await this.applyServerEvent(
+            event.mapName,
+            event.eventType,
+            event.key,
+            event.record,
+            event.orRecord,
+            event.orTag
+          );
         }
         break;
       }
@@ -774,11 +1143,11 @@ var SyncEngine = class {
         const { mapName } = message.payload;
         logger.warn({ mapName }, "Sync Reset Required due to GC Age");
         await this.resetMap(mapName);
-        this.websocket?.send(serialize({
+        this.sendMessage({
           type: "SYNC_INIT",
           mapName,
           lastSyncTimestamp: 0
-        }));
+        });
         break;
       }
       case "SYNC_RESP_ROOT": {
@@ -788,10 +1157,10 @@ var SyncEngine = class {
           const localRootHash = map.getMerkleTree().getRootHash();
           if (localRootHash !== rootHash) {
             logger.info({ mapName, localRootHash, remoteRootHash: rootHash }, "Root hash mismatch, requesting buckets");
-            this.websocket?.send(serialize({
+            this.sendMessage({
               type: "MERKLE_REQ_BUCKET",
               payload: { mapName, path: "" }
-            }));
+            });
           } else {
             logger.info({ mapName }, "Map is in sync");
           }
@@ -813,10 +1182,10 @@ var SyncEngine = class {
             const localHash = localBuckets[bucketKey] || 0;
             if (localHash !== remoteHash) {
               const newPath = path + bucketKey;
-              this.websocket?.send(serialize({
+              this.sendMessage({
                 type: "MERKLE_REQ_BUCKET",
                 payload: { mapName, path: newPath }
-              }));
+              });
             }
           }
         }
@@ -849,10 +1218,10 @@ var SyncEngine = class {
           const localRootHash = localTree.getRootHash();
           if (localRootHash !== rootHash) {
             logger.info({ mapName, localRootHash, remoteRootHash: rootHash }, "ORMap root hash mismatch, requesting buckets");
-            this.websocket?.send(serialize({
+            this.sendMessage({
               type: "ORMAP_MERKLE_REQ_BUCKET",
               payload: { mapName, path: "" }
-            }));
+            });
           } else {
             logger.info({ mapName }, "ORMap is in sync");
           }
@@ -874,10 +1243,10 @@ var SyncEngine = class {
             const localHash = localBuckets[bucketKey] || 0;
             if (localHash !== remoteHash) {
               const newPath = path + bucketKey;
-              this.websocket?.send(serialize({
+              this.sendMessage({
                 type: "ORMAP_MERKLE_REQ_BUCKET",
                 payload: { mapName, path: newPath }
-              }));
+              });
             }
           }
           for (const [bucketKey, localHash] of Object.entries(localBuckets)) {
@@ -940,6 +1309,25 @@ var SyncEngine = class {
   getHLC() {
     return this.hlc;
   }
+  /**
+   * Helper method to apply a single server event to the local map.
+   * Used by both SERVER_EVENT and SERVER_BATCH_EVENT handlers.
+   */
+  async applyServerEvent(mapName, eventType, key, record, orRecord, orTag) {
+    const localMap = this.maps.get(mapName);
+    if (localMap) {
+      if (localMap instanceof LWWMap && record) {
+        localMap.merge(key, record);
+        await this.storageAdapter.put(`${mapName}:${key}`, record);
+      } else if (localMap instanceof ORMap) {
+        if (eventType === "OR_ADD" && orRecord) {
+          localMap.apply(key, orRecord);
+        } else if (eventType === "OR_REMOVE" && orTag) {
+          localMap.applyTombstone(orTag);
+        }
+      }
+    }
+  }
   /**
    * Closes the WebSocket connection and cleans up resources.
    */
@@ -949,11 +1337,16 @@ var SyncEngine = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
-    if (this.websocket) {
+    if (this.useConnectionProvider) {
+      this.connectionProvider.close().catch((err) => {
+        logger.error({ err }, "Error closing ConnectionProvider");
+      });
+    } else if (this.websocket) {
       this.websocket.onclose = null;
       this.websocket.close();
       this.websocket = null;
     }
+    this.cancelAllWriteConcernPromises(new Error("SyncEngine closed"));
     this.stateMachine.transition("DISCONNECTED" /* DISCONNECTED */);
     logger.info("SyncEngine closed");
   }
@@ -965,7 +1358,100 @@ var SyncEngine = class {
     this.close();
     this.stateMachine.reset();
     this.resetBackoff();
-    this.initConnection();
+    if (this.useConnectionProvider) {
+      this.initConnectionProvider();
+    } else {
+      this.initConnection();
+    }
+  }
+  // ============================================
+  // Failover Support Methods (Phase 4.5 Task 05)
+  // ============================================
+  /**
+   * 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 = 5e3) {
+    return new Promise((resolve) => {
+      const timeout = setTimeout(resolve, timeoutMs);
+      const handler2 = () => {
+        clearTimeout(timeout);
+        this.connectionProvider.off("partitionMapUpdated", handler2);
+        resolve();
+      };
+      this.connectionProvider.on("partitionMapUpdated", handler2);
+    });
+  }
+  /**
+   * 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 = 1e4) {
+    return new Promise((resolve, reject) => {
+      if (this.connectionProvider.isConnected()) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        this.connectionProvider.off("connected", handler2);
+        reject(new Error("Connection timeout waiting for reconnection"));
+      }, timeoutMs);
+      const handler2 = () => {
+        clearTimeout(timeout);
+        this.connectionProvider.off("connected", handler2);
+        resolve();
+      };
+      this.connectionProvider.on("connected", handler2);
+    });
+  }
+  /**
+   * 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, timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      if (this.stateMachine.getState() === targetState) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        unsubscribe();
+        reject(new Error(`Timeout waiting for state ${targetState}`));
+      }, timeoutMs);
+      const unsubscribe = this.stateMachine.onStateChange((event) => {
+        if (event.to === targetState) {
+          clearTimeout(timeout);
+          unsubscribe();
+          resolve();
+        }
+      });
+    });
+  }
+  /**
+   * Check if the connection provider is connected.
+   * Convenience method for failover logic.
+   */
+  isProviderConnected() {
+    return this.connectionProvider.isConnected();
+  }
+  /**
+   * Get the connection provider for direct access.
+   * Use with caution - prefer using SyncEngine methods.
+   */
+  getConnectionProvider() {
+    return this.connectionProvider;
   }
   async resetMap(mapName) {
     const map = this.maps.get(mapName);
@@ -1013,12 +1499,12 @@ var SyncEngine = class {
    * Sends a PING message to the server.
    */
   sendPing() {
-    if (this.websocket?.readyState === WebSocket.OPEN) {
+    if (this.canSend()) {
       const pingMessage = {
         type: "PING",
         timestamp: Date.now()
       };
-      this.websocket.send(serialize(pingMessage));
+      this.sendMessage(pingMessage);
     }
   }
   /**
@@ -1097,13 +1583,13 @@ var SyncEngine = class {
       }
     }
     if (entries.length > 0) {
-      this.websocket?.send(serialize({
+      this.sendMessage({
         type: "ORMAP_PUSH_DIFF",
         payload: {
           mapName,
           entries
         }
-      }));
+      });
       logger.debug({ mapName, keyCount: entries.length }, "Pushed ORMap diff to server");
     }
   }
@@ -1274,21 +1760,73 @@ var SyncEngine = class {
       });
     }
   }
-};
-
-// src/TopGunClient.ts
-import { LWWMap as LWWMap2, ORMap as ORMap2 } from "@topgunbuild/core";
-
-// src/QueryHandle.ts
-var QueryHandle = class {
-  constructor(syncEngine, mapName, filter = {}) {
-    this.listeners = /* @__PURE__ */ new Set();
-    this.currentResults = /* @__PURE__ */ new Map();
-    // Track if we've received authoritative server response
-    this.hasReceivedServerData = false;
-    this.id = crypto.randomUUID();
-    this.syncEngine = syncEngine;
-    this.mapName = mapName;
+  // ============================================
+  // Write Concern Methods (Phase 5.01)
+  // ============================================
+  /**
+   * Register a pending Write Concern promise for an operation.
+   * The promise will be resolved when the server sends an ACK with the operation result.
+   *
+   * @param opId - Operation ID
+   * @param timeout - Timeout in ms (default: 5000)
+   * @returns Promise that resolves with the Write Concern result
+   */
+  registerWriteConcernPromise(opId, timeout = 5e3) {
+    return new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.pendingWriteConcernPromises.delete(opId);
+        reject(new Error(`Write Concern timeout for operation ${opId}`));
+      }, timeout);
+      this.pendingWriteConcernPromises.set(opId, {
+        resolve,
+        reject,
+        timeoutHandle
+      });
+    });
+  }
+  /**
+   * Resolve a pending Write Concern promise with the server result.
+   *
+   * @param opId - Operation ID
+   * @param result - Result from server ACK
+   */
+  resolveWriteConcernPromise(opId, result) {
+    const pending = this.pendingWriteConcernPromises.get(opId);
+    if (pending) {
+      if (pending.timeoutHandle) {
+        clearTimeout(pending.timeoutHandle);
+      }
+      pending.resolve(result);
+      this.pendingWriteConcernPromises.delete(opId);
+    }
+  }
+  /**
+   * Cancel all pending Write Concern promises (e.g., on disconnect).
+   */
+  cancelAllWriteConcernPromises(error) {
+    for (const [opId, pending] of this.pendingWriteConcernPromises.entries()) {
+      if (pending.timeoutHandle) {
+        clearTimeout(pending.timeoutHandle);
+      }
+      pending.reject(error);
+    }
+    this.pendingWriteConcernPromises.clear();
+  }
+};
+
+// src/TopGunClient.ts
+import { LWWMap as LWWMap2, ORMap as ORMap2 } from "@topgunbuild/core";
+
+// src/QueryHandle.ts
+var QueryHandle = class {
+  constructor(syncEngine, mapName, filter = {}) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.currentResults = /* @__PURE__ */ new Map();
+    // Track if we've received authoritative server response
+    this.hasReceivedServerData = false;
+    this.id = crypto.randomUUID();
+    this.syncEngine = syncEngine;
+    this.mapName = mapName;
     this.filter = filter;
   }
   subscribe(callback) {
@@ -1347,152 +1885,1626 @@ var QueryHandle = class {
         this.currentResults.delete(key);
       }
     }
-    if (removedKeys.length > 0) {
-      console.log(`[QueryHandle:${this.mapName}] Removed ${removedKeys.length} keys:`, removedKeys);
-    }
-    for (const item of items) {
-      this.currentResults.set(item.key, item.value);
+    if (removedKeys.length > 0) {
+      console.log(`[QueryHandle:${this.mapName}] Removed ${removedKeys.length} keys:`, removedKeys);
+    }
+    for (const item of items) {
+      this.currentResults.set(item.key, item.value);
+    }
+    console.log(`[QueryHandle:${this.mapName}] After merge: ${this.currentResults.size} results`);
+    this.notify();
+  }
+  /**
+   * Called by SyncEngine when server sends a live update
+   */
+  onUpdate(key, value) {
+    if (value === null) {
+      this.currentResults.delete(key);
+    } else {
+      this.currentResults.set(key, value);
+    }
+    this.notify();
+  }
+  notify() {
+    const results = this.getSortedResults();
+    for (const listener of this.listeners) {
+      listener(results);
+    }
+  }
+  getSortedResults() {
+    const results = Array.from(this.currentResults.entries()).map(
+      ([key, value]) => ({ ...value, _key: key })
+    );
+    if (this.filter.sort) {
+      results.sort((a, b) => {
+        for (const [field, direction] of Object.entries(this.filter.sort)) {
+          const valA = a[field];
+          const valB = b[field];
+          if (valA < valB) return direction === "asc" ? -1 : 1;
+          if (valA > valB) return direction === "asc" ? 1 : -1;
+        }
+        return 0;
+      });
+    }
+    return results;
+  }
+  getFilter() {
+    return this.filter;
+  }
+  getMapName() {
+    return this.mapName;
+  }
+};
+
+// src/DistributedLock.ts
+var DistributedLock = class {
+  constructor(syncEngine, name) {
+    this.fencingToken = null;
+    this._isLocked = false;
+    this.syncEngine = syncEngine;
+    this.name = name;
+  }
+  async lock(ttl = 1e4) {
+    const requestId = crypto.randomUUID();
+    try {
+      const result = await this.syncEngine.requestLock(this.name, requestId, ttl);
+      this.fencingToken = result.fencingToken;
+      this._isLocked = true;
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  async unlock() {
+    if (!this._isLocked || this.fencingToken === null) return;
+    const requestId = crypto.randomUUID();
+    try {
+      await this.syncEngine.releaseLock(this.name, requestId, this.fencingToken);
+    } finally {
+      this._isLocked = false;
+      this.fencingToken = null;
+    }
+  }
+  isLocked() {
+    return this._isLocked;
+  }
+};
+
+// src/TopicHandle.ts
+var TopicHandle = class {
+  constructor(engine, topic) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.engine = engine;
+    this.topic = topic;
+  }
+  get id() {
+    return this.topic;
+  }
+  /**
+   * Publish a message to the topic
+   */
+  publish(data) {
+    this.engine.publishTopic(this.topic, data);
+  }
+  /**
+   * Subscribe to the topic
+   */
+  subscribe(callback) {
+    if (this.listeners.size === 0) {
+      this.engine.subscribeToTopic(this.topic, this);
+    }
+    this.listeners.add(callback);
+    return () => this.unsubscribe(callback);
+  }
+  unsubscribe(callback) {
+    this.listeners.delete(callback);
+    if (this.listeners.size === 0) {
+      this.engine.unsubscribeFromTopic(this.topic);
+    }
+  }
+  /**
+   * Called by SyncEngine when a message is received
+   */
+  onMessage(data, context) {
+    this.listeners.forEach((cb) => {
+      try {
+        cb(data, context);
+      } catch (e) {
+        console.error("Error in topic listener", e);
+      }
+    });
+  }
+};
+
+// src/cluster/ClusterClient.ts
+import {
+  DEFAULT_CONNECTION_POOL_CONFIG as DEFAULT_CONNECTION_POOL_CONFIG2,
+  DEFAULT_PARTITION_ROUTER_CONFIG as DEFAULT_PARTITION_ROUTER_CONFIG2,
+  DEFAULT_CIRCUIT_BREAKER_CONFIG,
+  serialize as serialize3
+} from "@topgunbuild/core";
+
+// src/cluster/ConnectionPool.ts
+import {
+  DEFAULT_CONNECTION_POOL_CONFIG
+} from "@topgunbuild/core";
+import { serialize as serialize2, deserialize as deserialize2 } from "@topgunbuild/core";
+var ConnectionPool = class {
+  constructor(config = {}) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.connections = /* @__PURE__ */ new Map();
+    this.primaryNodeId = null;
+    this.healthCheckTimer = null;
+    this.authToken = null;
+    this.config = {
+      ...DEFAULT_CONNECTION_POOL_CONFIG,
+      ...config
+    };
+  }
+  // ============================================
+  // Event Emitter Methods (browser-compatible)
+  // ============================================
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+    return this;
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+    return this;
+  }
+  emit(event, ...args) {
+    const eventListeners = this.listeners.get(event);
+    if (!eventListeners || eventListeners.size === 0) {
+      return false;
+    }
+    for (const listener of eventListeners) {
+      try {
+        listener(...args);
+      } catch (err) {
+        logger.error({ event, err }, "Error in event listener");
+      }
+    }
+    return true;
+  }
+  removeAllListeners(event) {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+    return this;
+  }
+  /**
+   * Set authentication token for all connections
+   */
+  setAuthToken(token) {
+    this.authToken = token;
+    for (const conn of this.connections.values()) {
+      if (conn.state === "CONNECTED") {
+        this.sendAuth(conn);
+      }
+    }
+  }
+  /**
+   * Add a node to the connection pool
+   */
+  async addNode(nodeId, endpoint) {
+    if (this.connections.has(nodeId)) {
+      const existing = this.connections.get(nodeId);
+      if (existing.endpoint !== endpoint) {
+        await this.removeNode(nodeId);
+      } else {
+        return;
+      }
+    }
+    const connection = {
+      nodeId,
+      endpoint,
+      socket: null,
+      state: "DISCONNECTED",
+      lastSeen: 0,
+      latencyMs: 0,
+      reconnectAttempts: 0,
+      reconnectTimer: null,
+      pendingMessages: []
+    };
+    this.connections.set(nodeId, connection);
+    if (!this.primaryNodeId) {
+      this.primaryNodeId = nodeId;
+    }
+    await this.connect(nodeId);
+  }
+  /**
+   * Remove a node from the connection pool
+   */
+  async removeNode(nodeId) {
+    const connection = this.connections.get(nodeId);
+    if (!connection) return;
+    if (connection.reconnectTimer) {
+      clearTimeout(connection.reconnectTimer);
+      connection.reconnectTimer = null;
+    }
+    if (connection.socket) {
+      connection.socket.onclose = null;
+      connection.socket.close();
+      connection.socket = null;
+    }
+    this.connections.delete(nodeId);
+    if (this.primaryNodeId === nodeId) {
+      this.primaryNodeId = this.connections.size > 0 ? this.connections.keys().next().value ?? null : null;
+    }
+    logger.info({ nodeId }, "Node removed from connection pool");
+  }
+  /**
+   * Get connection for a specific node
+   */
+  getConnection(nodeId) {
+    const connection = this.connections.get(nodeId);
+    if (!connection || connection.state !== "AUTHENTICATED") {
+      return null;
+    }
+    return connection.socket;
+  }
+  /**
+   * Get primary connection (first/seed node)
+   */
+  getPrimaryConnection() {
+    if (!this.primaryNodeId) return null;
+    return this.getConnection(this.primaryNodeId);
+  }
+  /**
+   * Get any healthy connection
+   */
+  getAnyHealthyConnection() {
+    for (const [nodeId, conn] of this.connections) {
+      if (conn.state === "AUTHENTICATED" && conn.socket) {
+        return { nodeId, socket: conn.socket };
+      }
+    }
+    return null;
+  }
+  /**
+   * Send message to a specific node
+   */
+  send(nodeId, message) {
+    const connection = this.connections.get(nodeId);
+    if (!connection) {
+      logger.warn({ nodeId }, "Cannot send: node not in pool");
+      return false;
+    }
+    const data = serialize2(message);
+    if (connection.state === "AUTHENTICATED" && connection.socket?.readyState === WebSocket.OPEN) {
+      connection.socket.send(data);
+      return true;
+    }
+    if (connection.pendingMessages.length < 1e3) {
+      connection.pendingMessages.push(data);
+      return true;
+    }
+    logger.warn({ nodeId }, "Message queue full, dropping message");
+    return false;
+  }
+  /**
+   * Send message to primary node
+   */
+  sendToPrimary(message) {
+    if (!this.primaryNodeId) {
+      logger.warn("No primary node available");
+      return false;
+    }
+    return this.send(this.primaryNodeId, message);
+  }
+  /**
+   * Get health status for all nodes
+   */
+  getHealthStatus() {
+    const status = /* @__PURE__ */ new Map();
+    for (const [nodeId, conn] of this.connections) {
+      status.set(nodeId, {
+        nodeId,
+        state: conn.state,
+        lastSeen: conn.lastSeen,
+        latencyMs: conn.latencyMs,
+        reconnectAttempts: conn.reconnectAttempts
+      });
+    }
+    return status;
+  }
+  /**
+   * Get list of connected node IDs
+   */
+  getConnectedNodes() {
+    return Array.from(this.connections.entries()).filter(([_, conn]) => conn.state === "AUTHENTICATED").map(([nodeId]) => nodeId);
+  }
+  /**
+   * Get all node IDs
+   */
+  getAllNodes() {
+    return Array.from(this.connections.keys());
+  }
+  /**
+   * Check if node is connected and authenticated
+   */
+  isNodeConnected(nodeId) {
+    const conn = this.connections.get(nodeId);
+    return conn?.state === "AUTHENTICATED";
+  }
+  /**
+   * Check if connected to a specific node.
+   * Alias for isNodeConnected() for IConnectionProvider compatibility.
+   */
+  isConnected(nodeId) {
+    return this.isNodeConnected(nodeId);
+  }
+  /**
+   * Start health monitoring
+   */
+  startHealthCheck() {
+    if (this.healthCheckTimer) return;
+    this.healthCheckTimer = setInterval(() => {
+      this.performHealthCheck();
+    }, this.config.healthCheckIntervalMs);
+  }
+  /**
+   * Stop health monitoring
+   */
+  stopHealthCheck() {
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer);
+      this.healthCheckTimer = null;
+    }
+  }
+  /**
+   * Close all connections and cleanup
+   */
+  close() {
+    this.stopHealthCheck();
+    for (const nodeId of this.connections.keys()) {
+      this.removeNode(nodeId);
+    }
+    this.connections.clear();
+    this.primaryNodeId = null;
+  }
+  // ============================================
+  // Private Methods
+  // ============================================
+  async connect(nodeId) {
+    const connection = this.connections.get(nodeId);
+    if (!connection) return;
+    if (connection.state === "CONNECTING" || connection.state === "CONNECTED") {
+      return;
+    }
+    connection.state = "CONNECTING";
+    logger.info({ nodeId, endpoint: connection.endpoint }, "Connecting to node");
+    try {
+      const socket = new WebSocket(connection.endpoint);
+      socket.binaryType = "arraybuffer";
+      connection.socket = socket;
+      socket.onopen = () => {
+        connection.state = "CONNECTED";
+        connection.reconnectAttempts = 0;
+        connection.lastSeen = Date.now();
+        logger.info({ nodeId }, "Connected to node");
+        this.emit("node:connected", nodeId);
+        if (this.authToken) {
+          this.sendAuth(connection);
+        }
+      };
+      socket.onmessage = (event) => {
+        connection.lastSeen = Date.now();
+        this.handleMessage(nodeId, event);
+      };
+      socket.onerror = (error) => {
+        logger.error({ nodeId, error }, "WebSocket error");
+        this.emit("error", nodeId, error instanceof Error ? error : new Error("WebSocket error"));
+      };
+      socket.onclose = () => {
+        const wasConnected = connection.state === "AUTHENTICATED";
+        connection.state = "DISCONNECTED";
+        connection.socket = null;
+        if (wasConnected) {
+          this.emit("node:disconnected", nodeId, "Connection closed");
+        }
+        this.scheduleReconnect(nodeId);
+      };
+    } catch (error) {
+      connection.state = "FAILED";
+      logger.error({ nodeId, error }, "Failed to connect");
+      this.scheduleReconnect(nodeId);
+    }
+  }
+  sendAuth(connection) {
+    if (!this.authToken || !connection.socket) return;
+    connection.socket.send(serialize2({
+      type: "AUTH",
+      token: this.authToken
+    }));
+  }
+  handleMessage(nodeId, event) {
+    const connection = this.connections.get(nodeId);
+    if (!connection) return;
+    let message;
+    try {
+      if (event.data instanceof ArrayBuffer) {
+        message = deserialize2(new Uint8Array(event.data));
+      } else {
+        message = JSON.parse(event.data);
+      }
+    } catch (e) {
+      logger.error({ nodeId, error: e }, "Failed to parse message");
+      return;
+    }
+    if (message.type === "AUTH_ACK") {
+      connection.state = "AUTHENTICATED";
+      logger.info({ nodeId }, "Authenticated with node");
+      this.emit("node:healthy", nodeId);
+      this.flushPendingMessages(connection);
+      return;
+    }
+    if (message.type === "AUTH_REQUIRED") {
+      if (this.authToken) {
+        this.sendAuth(connection);
+      }
+      return;
+    }
+    if (message.type === "AUTH_FAIL") {
+      logger.error({ nodeId, error: message.error }, "Authentication failed");
+      connection.state = "FAILED";
+      return;
+    }
+    if (message.type === "PONG") {
+      if (message.timestamp) {
+        connection.latencyMs = Date.now() - message.timestamp;
+      }
+      return;
+    }
+    if (message.type === "PARTITION_MAP" || message.type === "PARTITION_MAP_DELTA") {
+      this.emit("message", nodeId, message);
+      return;
+    }
+    this.emit("message", nodeId, message);
+  }
+  flushPendingMessages(connection) {
+    if (!connection.socket || connection.state !== "AUTHENTICATED") return;
+    const pending = connection.pendingMessages;
+    connection.pendingMessages = [];
+    for (const data of pending) {
+      if (connection.socket.readyState === WebSocket.OPEN) {
+        connection.socket.send(data);
+      }
+    }
+    if (pending.length > 0) {
+      logger.debug({ nodeId: connection.nodeId, count: pending.length }, "Flushed pending messages");
+    }
+  }
+  scheduleReconnect(nodeId) {
+    const connection = this.connections.get(nodeId);
+    if (!connection) return;
+    if (connection.reconnectTimer) {
+      clearTimeout(connection.reconnectTimer);
+      connection.reconnectTimer = null;
+    }
+    if (connection.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      connection.state = "FAILED";
+      logger.error({ nodeId, attempts: connection.reconnectAttempts }, "Max reconnect attempts reached");
+      this.emit("node:unhealthy", nodeId, "Max reconnect attempts reached");
+      return;
+    }
+    const delay = Math.min(
+      this.config.reconnectDelayMs * Math.pow(2, connection.reconnectAttempts),
+      this.config.maxReconnectDelayMs
+    );
+    connection.state = "RECONNECTING";
+    connection.reconnectAttempts++;
+    logger.info({ nodeId, delay, attempt: connection.reconnectAttempts }, "Scheduling reconnect");
+    connection.reconnectTimer = setTimeout(() => {
+      connection.reconnectTimer = null;
+      this.connect(nodeId);
+    }, delay);
+  }
+  performHealthCheck() {
+    const now = Date.now();
+    for (const [nodeId, connection] of this.connections) {
+      if (connection.state !== "AUTHENTICATED") continue;
+      const timeSinceLastSeen = now - connection.lastSeen;
+      if (timeSinceLastSeen > this.config.healthCheckIntervalMs * 3) {
+        logger.warn({ nodeId, timeSinceLastSeen }, "Node appears stale, sending ping");
+      }
+      if (connection.socket?.readyState === WebSocket.OPEN) {
+        connection.socket.send(serialize2({
+          type: "PING",
+          timestamp: now
+        }));
+      }
+    }
+  }
+};
+
+// src/cluster/PartitionRouter.ts
+import {
+  DEFAULT_PARTITION_ROUTER_CONFIG,
+  PARTITION_COUNT,
+  hashString
+} from "@topgunbuild/core";
+var PartitionRouter = class {
+  constructor(connectionPool, config = {}) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.partitionMap = null;
+    this.lastRefreshTime = 0;
+    this.refreshTimer = null;
+    this.pendingRefresh = null;
+    this.connectionPool = connectionPool;
+    this.config = {
+      ...DEFAULT_PARTITION_ROUTER_CONFIG,
+      ...config
+    };
+    this.connectionPool.on("message", (nodeId, message) => {
+      if (message.type === "PARTITION_MAP") {
+        this.handlePartitionMap(message);
+      } else if (message.type === "PARTITION_MAP_DELTA") {
+        this.handlePartitionMapDelta(message);
+      }
+    });
+  }
+  // ============================================
+  // Event Emitter Methods (browser-compatible)
+  // ============================================
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+    return this;
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+    return this;
+  }
+  once(event, listener) {
+    const wrapper = (...args) => {
+      this.off(event, wrapper);
+      listener(...args);
+    };
+    return this.on(event, wrapper);
+  }
+  emit(event, ...args) {
+    const eventListeners = this.listeners.get(event);
+    if (!eventListeners || eventListeners.size === 0) {
+      return false;
+    }
+    for (const listener of eventListeners) {
+      try {
+        listener(...args);
+      } catch (err) {
+        logger.error({ event, err }, "Error in event listener");
+      }
+    }
+    return true;
+  }
+  removeListener(event, listener) {
+    return this.off(event, listener);
+  }
+  removeAllListeners(event) {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+    return this;
+  }
+  /**
+   * Get the partition ID for a given key
+   */
+  getPartitionId(key) {
+    return Math.abs(hashString(key)) % PARTITION_COUNT;
+  }
+  /**
+   * Route a key to the owner node
+   */
+  route(key) {
+    if (!this.partitionMap) {
+      return null;
+    }
+    const partitionId = this.getPartitionId(key);
+    const partition = this.partitionMap.partitions.find((p) => p.partitionId === partitionId);
+    if (!partition) {
+      logger.warn({ key, partitionId }, "Partition not found in map");
+      return null;
+    }
+    return {
+      nodeId: partition.ownerNodeId,
+      partitionId,
+      isOwner: true,
+      isBackup: false
+    };
+  }
+  /**
+   * Route a key and get the WebSocket connection to use
+   */
+  routeToConnection(key) {
+    const routing = this.route(key);
+    if (!routing) {
+      if (this.config.fallbackMode === "forward") {
+        const primary = this.connectionPool.getAnyHealthyConnection();
+        if (primary) {
+          return primary;
+        }
+      }
+      return null;
+    }
+    const socket = this.connectionPool.getConnection(routing.nodeId);
+    if (socket) {
+      return { nodeId: routing.nodeId, socket };
+    }
+    const partition = this.partitionMap.partitions.find((p) => p.partitionId === routing.partitionId);
+    if (partition) {
+      for (const backupId of partition.backupNodeIds) {
+        const backupSocket = this.connectionPool.getConnection(backupId);
+        if (backupSocket) {
+          logger.debug({ key, owner: routing.nodeId, backup: backupId }, "Using backup node");
+          return { nodeId: backupId, socket: backupSocket };
+        }
+      }
+    }
+    if (this.config.fallbackMode === "forward") {
+      return this.connectionPool.getAnyHealthyConnection();
+    }
+    return null;
+  }
+  /**
+   * Get routing info for multiple keys (batch routing)
+   */
+  routeBatch(keys) {
+    const result = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      const routing = this.route(key);
+      if (routing) {
+        const nodeId = routing.nodeId;
+        if (!result.has(nodeId)) {
+          result.set(nodeId, []);
+        }
+        result.get(nodeId).push({ ...routing, key });
+      }
+    }
+    return result;
+  }
+  /**
+   * Get all partitions owned by a specific node
+   */
+  getPartitionsForNode(nodeId) {
+    if (!this.partitionMap) return [];
+    return this.partitionMap.partitions.filter((p) => p.ownerNodeId === nodeId).map((p) => p.partitionId);
+  }
+  /**
+   * Get current partition map version
+   */
+  getMapVersion() {
+    return this.partitionMap?.version ?? 0;
+  }
+  /**
+   * Check if partition map is available
+   */
+  hasPartitionMap() {
+    return this.partitionMap !== null;
+  }
+  /**
+   * Get owner node for a key.
+   * Returns null if partition map is not available.
+   */
+  getOwner(key) {
+    if (!this.partitionMap) return null;
+    const partitionId = this.getPartitionId(key);
+    const partition = this.partitionMap.partitions.find((p) => p.partitionId === partitionId);
+    return partition?.ownerNodeId ?? null;
+  }
+  /**
+   * Get backup nodes for a key.
+   * Returns empty array if partition map is not available.
+   */
+  getBackups(key) {
+    if (!this.partitionMap) return [];
+    const partitionId = this.getPartitionId(key);
+    const partition = this.partitionMap.partitions.find((p) => p.partitionId === partitionId);
+    return partition?.backupNodeIds ?? [];
+  }
+  /**
+   * Get the full partition map.
+   * Returns null if not available.
+   */
+  getMap() {
+    return this.partitionMap;
+  }
+  /**
+   * Update entire partition map.
+   * Only accepts newer versions.
+   */
+  updateMap(map) {
+    if (this.partitionMap && map.version <= this.partitionMap.version) {
+      return false;
+    }
+    this.partitionMap = map;
+    this.lastRefreshTime = Date.now();
+    this.updateConnectionPool(map);
+    const changesCount = map.partitions.length;
+    logger.info({
+      version: map.version,
+      partitions: map.partitionCount,
+      nodes: map.nodes.length
+    }, "Partition map updated via updateMap");
+    this.emit("partitionMap:updated", map.version, changesCount);
+    return true;
+  }
+  /**
+   * Update a single partition (for delta updates).
+   */
+  updatePartition(partitionId, owner, backups) {
+    if (!this.partitionMap) return;
+    const partition = this.partitionMap.partitions.find((p) => p.partitionId === partitionId);
+    if (partition) {
+      partition.ownerNodeId = owner;
+      partition.backupNodeIds = backups;
+    }
+  }
+  /**
+   * Check if partition map is stale
+   */
+  isMapStale() {
+    if (!this.partitionMap) return true;
+    const now = Date.now();
+    return now - this.lastRefreshTime > this.config.maxMapStalenessMs;
+  }
+  /**
+   * Request fresh partition map from server
+   */
+  async refreshPartitionMap() {
+    if (this.pendingRefresh) {
+      return this.pendingRefresh;
+    }
+    this.pendingRefresh = this.doRefreshPartitionMap();
+    try {
+      await this.pendingRefresh;
+    } finally {
+      this.pendingRefresh = null;
+    }
+  }
+  /**
+   * Start periodic partition map refresh
+   */
+  startPeriodicRefresh() {
+    if (this.refreshTimer) return;
+    this.refreshTimer = setInterval(() => {
+      if (this.isMapStale()) {
+        this.emit("partitionMap:stale", this.getMapVersion(), this.lastRefreshTime);
+        this.refreshPartitionMap().catch((err) => {
+          logger.error({ error: err }, "Failed to refresh partition map");
+        });
+      }
+    }, this.config.mapRefreshIntervalMs);
+  }
+  /**
+   * Stop periodic refresh
+   */
+  stopPeriodicRefresh() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  /**
+   * Handle NOT_OWNER error from server
+   */
+  handleNotOwnerError(key, actualOwner, newMapVersion) {
+    const routing = this.route(key);
+    const expectedOwner = routing?.nodeId ?? "unknown";
+    this.emit("routing:miss", key, expectedOwner, actualOwner);
+    if (newMapVersion > this.getMapVersion()) {
+      this.refreshPartitionMap().catch((err) => {
+        logger.error({ error: err }, "Failed to refresh partition map after NOT_OWNER");
+      });
+    }
+  }
+  /**
+   * Get statistics about routing
+   */
+  getStats() {
+    return {
+      mapVersion: this.getMapVersion(),
+      partitionCount: this.partitionMap?.partitionCount ?? 0,
+      nodeCount: this.partitionMap?.nodes.length ?? 0,
+      lastRefresh: this.lastRefreshTime,
+      isStale: this.isMapStale()
+    };
+  }
+  /**
+   * Cleanup resources
+   */
+  close() {
+    this.stopPeriodicRefresh();
+    this.partitionMap = null;
+  }
+  // ============================================
+  // Private Methods
+  // ============================================
+  handlePartitionMap(message) {
+    const newMap = message.payload;
+    if (this.partitionMap && newMap.version <= this.partitionMap.version) {
+      logger.debug({
+        current: this.partitionMap.version,
+        received: newMap.version
+      }, "Ignoring older partition map");
+      return;
+    }
+    this.partitionMap = newMap;
+    this.lastRefreshTime = Date.now();
+    this.updateConnectionPool(newMap);
+    const changesCount = newMap.partitions.length;
+    logger.info({
+      version: newMap.version,
+      partitions: newMap.partitionCount,
+      nodes: newMap.nodes.length
+    }, "Partition map updated");
+    this.emit("partitionMap:updated", newMap.version, changesCount);
+  }
+  handlePartitionMapDelta(message) {
+    const delta = message.payload;
+    if (!this.partitionMap) {
+      logger.warn("Received delta but no base map, requesting full map");
+      this.refreshPartitionMap();
+      return;
+    }
+    if (delta.previousVersion !== this.partitionMap.version) {
+      logger.warn({
+        expected: this.partitionMap.version,
+        received: delta.previousVersion
+      }, "Delta version mismatch, requesting full map");
+      this.refreshPartitionMap();
+      return;
+    }
+    for (const change of delta.changes) {
+      this.applyPartitionChange(change);
+    }
+    this.partitionMap.version = delta.version;
+    this.lastRefreshTime = Date.now();
+    logger.info({
+      version: delta.version,
+      changes: delta.changes.length
+    }, "Applied partition map delta");
+    this.emit("partitionMap:updated", delta.version, delta.changes.length);
+  }
+  applyPartitionChange(change) {
+    if (!this.partitionMap) return;
+    const partition = this.partitionMap.partitions.find((p) => p.partitionId === change.partitionId);
+    if (partition) {
+      partition.ownerNodeId = change.newOwner;
+    }
+  }
+  updateConnectionPool(map) {
+    for (const node of map.nodes) {
+      if (node.status === "ACTIVE" || node.status === "JOINING") {
+        this.connectionPool.addNode(node.nodeId, node.endpoints.websocket);
+      }
+    }
+    const currentNodeIds = new Set(map.nodes.map((n) => n.nodeId));
+    for (const nodeId of this.connectionPool.getAllNodes()) {
+      if (!currentNodeIds.has(nodeId)) {
+        this.connectionPool.removeNode(nodeId);
+      }
+    }
+  }
+  async doRefreshPartitionMap() {
+    logger.debug("Requesting partition map refresh");
+    const sent = this.connectionPool.sendToPrimary({
+      type: "PARTITION_MAP_REQUEST",
+      payload: {
+        currentVersion: this.getMapVersion()
+      }
+    });
+    if (!sent) {
+      throw new Error("No connection available to request partition map");
+    }
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.removeListener("partitionMap:updated", onUpdate);
+        reject(new Error("Partition map refresh timeout"));
+      }, 5e3);
+      const onUpdate = () => {
+        clearTimeout(timeout);
+        this.removeListener("partitionMap:updated", onUpdate);
+        resolve();
+      };
+      this.once("partitionMap:updated", onUpdate);
+    });
+  }
+};
+
+// src/cluster/ClusterClient.ts
+var ClusterClient = class {
+  constructor(config) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.initialized = false;
+    this.routingActive = false;
+    this.routingMetrics = {
+      directRoutes: 0,
+      fallbackRoutes: 0,
+      partitionMisses: 0,
+      totalRoutes: 0
+    };
+    // Circuit breaker state per node
+    this.circuits = /* @__PURE__ */ new Map();
+    this.config = config;
+    this.circuitBreakerConfig = {
+      ...DEFAULT_CIRCUIT_BREAKER_CONFIG,
+      ...config.circuitBreaker
+    };
+    const poolConfig = {
+      ...DEFAULT_CONNECTION_POOL_CONFIG2,
+      ...config.connectionPool
+    };
+    this.connectionPool = new ConnectionPool(poolConfig);
+    const routerConfig = {
+      ...DEFAULT_PARTITION_ROUTER_CONFIG2,
+      fallbackMode: config.routingMode === "direct" ? "error" : "forward",
+      ...config.routing
+    };
+    this.partitionRouter = new PartitionRouter(this.connectionPool, routerConfig);
+    this.setupEventHandlers();
+  }
+  // ============================================
+  // Event Emitter Methods (browser-compatible)
+  // ============================================
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+    return this;
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+    return this;
+  }
+  emit(event, ...args) {
+    const eventListeners = this.listeners.get(event);
+    if (!eventListeners || eventListeners.size === 0) {
+      return false;
+    }
+    for (const listener of eventListeners) {
+      try {
+        listener(...args);
+      } catch (err) {
+        logger.error({ event, err }, "Error in event listener");
+      }
+    }
+    return true;
+  }
+  removeAllListeners(event) {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+    return this;
+  }
+  // ============================================
+  // IConnectionProvider Implementation
+  // ============================================
+  /**
+   * Connect to cluster nodes (IConnectionProvider interface).
+   * Alias for start() method.
+   */
+  async connect() {
+    return this.start();
+  }
+  /**
+   * 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) {
+    if (!this.isConnected()) {
+      throw new Error("ClusterClient not connected");
+    }
+    this.routingMetrics.totalRoutes++;
+    if (this.config.routingMode !== "direct" || !this.routingActive) {
+      this.routingMetrics.fallbackRoutes++;
+      return this.getFallbackConnection();
+    }
+    const routing = this.partitionRouter.route(key);
+    if (!routing) {
+      this.routingMetrics.partitionMisses++;
+      logger.debug({ key }, "No partition map available, using fallback");
+      return this.getFallbackConnection();
+    }
+    const owner = routing.nodeId;
+    if (!this.connectionPool.isNodeConnected(owner)) {
+      this.routingMetrics.fallbackRoutes++;
+      logger.debug({ key, owner }, "Partition owner not connected, using fallback");
+      this.requestPartitionMapRefresh();
+      return this.getFallbackConnection();
+    }
+    const socket = this.connectionPool.getConnection(owner);
+    if (!socket) {
+      this.routingMetrics.fallbackRoutes++;
+      logger.debug({ key, owner }, "Could not get connection to owner, using fallback");
+      return this.getFallbackConnection();
+    }
+    this.routingMetrics.directRoutes++;
+    return socket;
+  }
+  /**
+   * Get fallback connection when owner is unavailable.
+   * @throws Error if no connection available
+   */
+  getFallbackConnection() {
+    const conn = this.connectionPool.getAnyHealthyConnection();
+    if (!conn?.socket) {
+      throw new Error("No healthy connection available");
+    }
+    return conn.socket;
+  }
+  /**
+   * Request a partition map refresh in the background.
+   * Called when routing to an unknown/disconnected owner.
+   */
+  requestPartitionMapRefresh() {
+    this.partitionRouter.refreshPartitionMap().catch((err) => {
+      logger.error({ err }, "Failed to refresh partition map");
+    });
+  }
+  /**
+   * Request partition map from a specific node.
+   * Called on first node connection.
+   */
+  requestPartitionMapFromNode(nodeId) {
+    const socket = this.connectionPool.getConnection(nodeId);
+    if (socket) {
+      logger.debug({ nodeId }, "Requesting partition map from node");
+      socket.send(serialize3({
+        type: "PARTITION_MAP_REQUEST",
+        payload: {
+          currentVersion: this.partitionRouter.getMapVersion()
+        }
+      }));
+    }
+  }
+  /**
+   * Check if at least one connection is active (IConnectionProvider interface).
+   */
+  isConnected() {
+    return this.connectionPool.getConnectedNodes().length > 0;
+  }
+  /**
+   * Send data via the appropriate connection (IConnectionProvider interface).
+   * Routes based on key if provided.
+   */
+  send(data, key) {
+    if (!this.isConnected()) {
+      throw new Error("ClusterClient not connected");
+    }
+    const socket = key ? this.getConnection(key) : this.getAnyConnection();
+    socket.send(data);
+  }
+  /**
+   * 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
+   */
+  async sendWithRetry(data, key, options = {}) {
+    const {
+      maxRetries = 3,
+      retryDelayMs = 100,
+      retryOnNotOwner = true
+    } = options;
+    let lastError = null;
+    let nodeId = null;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        if (key && this.routingActive) {
+          const routing = this.partitionRouter.route(key);
+          nodeId = routing?.nodeId ?? null;
+        }
+        if (nodeId && !this.canUseNode(nodeId)) {
+          logger.debug({ nodeId, attempt }, "Circuit open, using fallback");
+          nodeId = null;
+        }
+        const socket = key && nodeId ? this.connectionPool.getConnection(nodeId) : this.getAnyConnection();
+        if (!socket) {
+          throw new Error("No connection available");
+        }
+        socket.send(data);
+        if (nodeId) {
+          this.recordSuccess(nodeId);
+        }
+        return;
+      } catch (error) {
+        lastError = error;
+        if (nodeId) {
+          this.recordFailure(nodeId);
+        }
+        const errorCode = error?.code;
+        if (this.isRetryableError(error)) {
+          logger.debug(
+            { attempt, maxRetries, errorCode, nodeId },
+            "Retryable error, will retry"
+          );
+          if (errorCode === "NOT_OWNER" && retryOnNotOwner) {
+            await this.waitForPartitionMapUpdateInternal(2e3);
+          } else if (errorCode === "CONNECTION_CLOSED" || !this.isConnected()) {
+            await this.waitForConnectionInternal(5e3);
+          }
+          await this.delay(retryDelayMs * (attempt + 1));
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error(
+      `Operation failed after ${maxRetries} retries: ${lastError?.message}`
+    );
+  }
+  /**
+   * Check if an error is retryable.
+   */
+  isRetryableError(error) {
+    const code = error?.code;
+    const message = error?.message || "";
+    return code === "NOT_OWNER" || code === "CONNECTION_CLOSED" || code === "TIMEOUT" || code === "ECONNRESET" || message.includes("No active connections") || message.includes("No connection available") || message.includes("No healthy connection");
+  }
+  /**
+   * Wait for partition map update.
+   */
+  waitForPartitionMapUpdateInternal(timeoutMs) {
+    return new Promise((resolve) => {
+      const timeout = setTimeout(resolve, timeoutMs);
+      const handler2 = () => {
+        clearTimeout(timeout);
+        this.off("partitionMapUpdated", handler2);
+        resolve();
+      };
+      this.on("partitionMapUpdated", handler2);
+    });
+  }
+  /**
+   * Wait for at least one connection to be available.
+   */
+  waitForConnectionInternal(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (this.isConnected()) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        this.off("connected", handler2);
+        reject(new Error("Connection timeout"));
+      }, timeoutMs);
+      const handler2 = () => {
+        clearTimeout(timeout);
+        this.off("connected", handler2);
+        resolve();
+      };
+      this.on("connected", handler2);
+    });
+  }
+  /**
+   * Helper delay function.
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // ============================================
+  // Cluster-Specific Methods
+  // ============================================
+  /**
+   * Initialize cluster connections
+   */
+  async start() {
+    if (this.initialized) return;
+    logger.info({ seedNodes: this.config.seedNodes }, "Starting cluster client");
+    for (let i = 0; i < this.config.seedNodes.length; i++) {
+      const endpoint = this.config.seedNodes[i];
+      const nodeId = `seed-${i}`;
+      await this.connectionPool.addNode(nodeId, endpoint);
     }
-    console.log(`[QueryHandle:${this.mapName}] After merge: ${this.currentResults.size} results`);
-    this.notify();
+    this.connectionPool.startHealthCheck();
+    this.partitionRouter.startPeriodicRefresh();
+    this.initialized = true;
+    await this.waitForPartitionMap();
   }
   /**
-   * Called by SyncEngine when server sends a live update
+   * Set authentication token
    */
-  onUpdate(key, value) {
-    if (value === null) {
-      this.currentResults.delete(key);
-    } else {
-      this.currentResults.set(key, value);
+  setAuthToken(token) {
+    this.connectionPool.setAuthToken(token);
+  }
+  /**
+   * Send operation with automatic routing (legacy API for cluster operations).
+   * @deprecated Use send(data, key) for IConnectionProvider interface
+   */
+  sendMessage(key, message) {
+    if (this.config.routingMode === "direct" && this.routingActive) {
+      return this.sendDirect(key, message);
     }
-    this.notify();
+    return this.sendForward(message);
   }
-  notify() {
-    const results = this.getSortedResults();
-    for (const listener of this.listeners) {
-      listener(results);
+  /**
+   * Send directly to partition owner
+   */
+  sendDirect(key, message) {
+    const connection = this.partitionRouter.routeToConnection(key);
+    if (!connection) {
+      logger.warn({ key }, "No route available for key");
+      return false;
     }
+    const routedMessage = {
+      ...message,
+      _routing: {
+        partitionId: this.partitionRouter.getPartitionId(key),
+        mapVersion: this.partitionRouter.getMapVersion()
+      }
+    };
+    connection.socket.send(serialize3(routedMessage));
+    return true;
   }
-  getSortedResults() {
-    const results = Array.from(this.currentResults.entries()).map(
-      ([key, value]) => ({ ...value, _key: key })
-    );
-    if (this.filter.sort) {
-      results.sort((a, b) => {
-        for (const [field, direction] of Object.entries(this.filter.sort)) {
-          const valA = a[field];
-          const valB = b[field];
-          if (valA < valB) return direction === "asc" ? -1 : 1;
-          if (valA > valB) return direction === "asc" ? 1 : -1;
+  /**
+   * Send to primary node for server-side forwarding
+   */
+  sendForward(message) {
+    return this.connectionPool.sendToPrimary(message);
+  }
+  /**
+   * Send batch of operations with routing
+   */
+  sendBatch(operations) {
+    const results = /* @__PURE__ */ new Map();
+    if (this.config.routingMode === "direct" && this.routingActive) {
+      const nodeMessages = /* @__PURE__ */ new Map();
+      for (const { key, message } of operations) {
+        const routing = this.partitionRouter.route(key);
+        const nodeId = routing?.nodeId ?? "primary";
+        if (!nodeMessages.has(nodeId)) {
+          nodeMessages.set(nodeId, []);
         }
-        return 0;
+        nodeMessages.get(nodeId).push({ key, message });
+      }
+      for (const [nodeId, messages] of nodeMessages) {
+        let success;
+        if (nodeId === "primary") {
+          success = this.connectionPool.sendToPrimary({
+            type: "OP_BATCH",
+            payload: { ops: messages.map((m) => m.message) }
+          });
+        } else {
+          success = this.connectionPool.send(nodeId, {
+            type: "OP_BATCH",
+            payload: { ops: messages.map((m) => m.message) }
+          });
+        }
+        for (const { key } of messages) {
+          results.set(key, success);
+        }
+      }
+    } else {
+      const success = this.connectionPool.sendToPrimary({
+        type: "OP_BATCH",
+        payload: { ops: operations.map((o) => o.message) }
       });
+      for (const { key } of operations) {
+        results.set(key, success);
+      }
     }
     return results;
   }
-  getFilter() {
-    return this.filter;
+  /**
+   * Get connection pool health status
+   */
+  getHealthStatus() {
+    return this.connectionPool.getHealthStatus();
   }
-  getMapName() {
-    return this.mapName;
+  /**
+   * Get partition router stats
+   */
+  getRouterStats() {
+    return this.partitionRouter.getStats();
   }
-};
-
-// src/DistributedLock.ts
-var DistributedLock = class {
-  constructor(syncEngine, name) {
-    this.fencingToken = null;
-    this._isLocked = false;
-    this.syncEngine = syncEngine;
-    this.name = name;
+  /**
+   * Get routing metrics for monitoring smart routing effectiveness.
+   */
+  getRoutingMetrics() {
+    return { ...this.routingMetrics };
   }
-  async lock(ttl = 1e4) {
-    const requestId = crypto.randomUUID();
-    try {
-      const result = await this.syncEngine.requestLock(this.name, requestId, ttl);
-      this.fencingToken = result.fencingToken;
-      this._isLocked = true;
-      return true;
-    } catch (e) {
-      return false;
-    }
+  /**
+   * Reset routing metrics counters.
+   * Useful for monitoring intervals.
+   */
+  resetRoutingMetrics() {
+    this.routingMetrics.directRoutes = 0;
+    this.routingMetrics.fallbackRoutes = 0;
+    this.routingMetrics.partitionMisses = 0;
+    this.routingMetrics.totalRoutes = 0;
   }
-  async unlock() {
-    if (!this._isLocked || this.fencingToken === null) return;
-    const requestId = crypto.randomUUID();
-    try {
-      await this.syncEngine.releaseLock(this.name, requestId, this.fencingToken);
-    } finally {
-      this._isLocked = false;
-      this.fencingToken = null;
-    }
+  /**
+   * Check if cluster routing is active
+   */
+  isRoutingActive() {
+    return this.routingActive;
   }
-  isLocked() {
-    return this._isLocked;
+  /**
+   * Get list of connected nodes
+   */
+  getConnectedNodes() {
+    return this.connectionPool.getConnectedNodes();
   }
-};
-
-// src/TopicHandle.ts
-var TopicHandle = class {
-  constructor(engine, topic) {
-    this.listeners = /* @__PURE__ */ new Set();
-    this.engine = engine;
-    this.topic = topic;
+  /**
+   * Check if cluster client is initialized
+   */
+  isInitialized() {
+    return this.initialized;
   }
-  get id() {
-    return this.topic;
+  /**
+   * Force refresh of partition map
+   */
+  async refreshPartitionMap() {
+    await this.partitionRouter.refreshPartitionMap();
   }
   /**
-   * Publish a message to the topic
+   * Shutdown cluster client (IConnectionProvider interface).
    */
-  publish(data) {
-    this.engine.publishTopic(this.topic, data);
+  async close() {
+    this.partitionRouter.close();
+    this.connectionPool.close();
+    this.initialized = false;
+    this.routingActive = false;
+    logger.info("Cluster client closed");
   }
+  // ============================================
+  // Internal Access for TopGunClient
+  // ============================================
   /**
-   * Subscribe to the topic
+   * Get the connection pool (for internal use)
    */
-  subscribe(callback) {
-    if (this.listeners.size === 0) {
-      this.engine.subscribeToTopic(this.topic, this);
+  getConnectionPool() {
+    return this.connectionPool;
+  }
+  /**
+   * Get the partition router (for internal use)
+   */
+  getPartitionRouter() {
+    return this.partitionRouter;
+  }
+  /**
+   * Get any healthy WebSocket connection (IConnectionProvider interface).
+   * @throws Error if not connected
+   */
+  getAnyConnection() {
+    const conn = this.connectionPool.getAnyHealthyConnection();
+    if (!conn?.socket) {
+      throw new Error("No healthy connection available");
     }
-    this.listeners.add(callback);
-    return () => this.unsubscribe(callback);
+    return conn.socket;
   }
-  unsubscribe(callback) {
-    this.listeners.delete(callback);
-    if (this.listeners.size === 0) {
-      this.engine.unsubscribeFromTopic(this.topic);
+  /**
+   * Get any healthy WebSocket connection, or null if none available.
+   * Use this for optional connection checks.
+   */
+  getAnyConnectionOrNull() {
+    const conn = this.connectionPool.getAnyHealthyConnection();
+    return conn?.socket ?? null;
+  }
+  // ============================================
+  // Circuit Breaker Methods
+  // ============================================
+  /**
+   * Get circuit breaker state for a node.
+   */
+  getCircuit(nodeId) {
+    let circuit = this.circuits.get(nodeId);
+    if (!circuit) {
+      circuit = { failures: 0, lastFailure: 0, state: "closed" };
+      this.circuits.set(nodeId, circuit);
     }
+    return circuit;
   }
   /**
-   * Called by SyncEngine when a message is received
+   * Check if a node can be used (circuit not open).
    */
-  onMessage(data, context) {
-    this.listeners.forEach((cb) => {
-      try {
-        cb(data, context);
-      } catch (e) {
-        console.error("Error in topic listener", e);
+  canUseNode(nodeId) {
+    const circuit = this.getCircuit(nodeId);
+    if (circuit.state === "closed") {
+      return true;
+    }
+    if (circuit.state === "open") {
+      if (Date.now() - circuit.lastFailure > this.circuitBreakerConfig.resetTimeoutMs) {
+        circuit.state = "half-open";
+        logger.debug({ nodeId }, "Circuit breaker half-open, allowing test request");
+        this.emit("circuit:half-open", nodeId);
+        return true;
+      }
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Record a successful operation to a node.
+   * Resets circuit breaker on success.
+   */
+  recordSuccess(nodeId) {
+    const circuit = this.getCircuit(nodeId);
+    const wasOpen = circuit.state !== "closed";
+    circuit.failures = 0;
+    circuit.state = "closed";
+    if (wasOpen) {
+      logger.info({ nodeId }, "Circuit breaker closed after success");
+      this.emit("circuit:closed", nodeId);
+    }
+  }
+  /**
+   * Record a failed operation to a node.
+   * Opens circuit breaker after threshold failures.
+   */
+  recordFailure(nodeId) {
+    const circuit = this.getCircuit(nodeId);
+    circuit.failures++;
+    circuit.lastFailure = Date.now();
+    if (circuit.failures >= this.circuitBreakerConfig.failureThreshold) {
+      if (circuit.state !== "open") {
+        circuit.state = "open";
+        logger.warn({ nodeId, failures: circuit.failures }, "Circuit breaker opened");
+        this.emit("circuit:open", nodeId);
+      }
+    }
+  }
+  /**
+   * Get all circuit breaker states.
+   */
+  getCircuitStates() {
+    return new Map(this.circuits);
+  }
+  /**
+   * Reset circuit breaker for a specific node.
+   */
+  resetCircuit(nodeId) {
+    this.circuits.delete(nodeId);
+    logger.debug({ nodeId }, "Circuit breaker reset");
+  }
+  /**
+   * Reset all circuit breakers.
+   */
+  resetAllCircuits() {
+    this.circuits.clear();
+    logger.debug("All circuit breakers reset");
+  }
+  // ============================================
+  // Private Methods
+  // ============================================
+  setupEventHandlers() {
+    this.connectionPool.on("node:connected", (nodeId) => {
+      logger.debug({ nodeId }, "Node connected");
+      if (this.partitionRouter.getMapVersion() === 0) {
+        this.requestPartitionMapFromNode(nodeId);
+      }
+      if (this.connectionPool.getConnectedNodes().length === 1) {
+        this.emit("connected");
+      }
+    });
+    this.connectionPool.on("node:disconnected", (nodeId, reason) => {
+      logger.debug({ nodeId, reason }, "Node disconnected");
+      if (this.connectionPool.getConnectedNodes().length === 0) {
+        this.routingActive = false;
+        this.emit("disconnected", reason);
+      }
+    });
+    this.connectionPool.on("node:unhealthy", (nodeId, reason) => {
+      logger.warn({ nodeId, reason }, "Node unhealthy");
+    });
+    this.connectionPool.on("error", (nodeId, error) => {
+      this.emit("error", error);
+    });
+    this.connectionPool.on("message", (nodeId, data) => {
+      this.emit("message", nodeId, data);
+    });
+    this.partitionRouter.on("partitionMap:updated", (version, changesCount) => {
+      if (!this.routingActive && this.partitionRouter.hasPartitionMap()) {
+        this.routingActive = true;
+        logger.info({ version }, "Direct routing activated");
+        this.emit("routing:active");
       }
+      this.emit("partitionMap:ready", version);
+      this.emit("partitionMapUpdated");
+    });
+    this.partitionRouter.on("routing:miss", (key, expected, actual) => {
+      logger.debug({ key, expected, actual }, "Routing miss detected");
+    });
+  }
+  async waitForPartitionMap(timeoutMs = 1e4) {
+    if (this.partitionRouter.hasPartitionMap()) {
+      this.routingActive = true;
+      return;
+    }
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        this.partitionRouter.off("partitionMap:updated", onUpdate);
+        logger.warn("Partition map not received, using fallback routing");
+        resolve();
+      }, timeoutMs);
+      const onUpdate = () => {
+        clearTimeout(timeout);
+        this.partitionRouter.off("partitionMap:updated", onUpdate);
+        this.routingActive = true;
+        resolve();
+      };
+      this.partitionRouter.once("partitionMap:updated", onUpdate);
     });
   }
 };
 
 // src/TopGunClient.ts
+var DEFAULT_CLUSTER_CONFIG = {
+  connectionsPerNode: 1,
+  smartRouting: true,
+  partitionMapRefreshMs: 3e4,
+  connectionTimeoutMs: 5e3,
+  retryAttempts: 3
+};
 var TopGunClient = class {
   constructor(config) {
     this.maps = /* @__PURE__ */ new Map();
     this.topicHandles = /* @__PURE__ */ new Map();
+    if (config.serverUrl && config.cluster) {
+      throw new Error("Cannot specify both serverUrl and cluster config");
+    }
+    if (!config.serverUrl && !config.cluster) {
+      throw new Error("Must specify either serverUrl or cluster config");
+    }
     this.nodeId = config.nodeId || crypto.randomUUID();
     this.storageAdapter = config.storage;
-    const syncEngineConfig = {
-      nodeId: this.nodeId,
-      serverUrl: config.serverUrl,
-      storageAdapter: this.storageAdapter,
-      backoff: config.backoff,
-      backpressure: config.backpressure
-    };
-    this.syncEngine = new SyncEngine(syncEngineConfig);
+    this.isClusterMode = !!config.cluster;
+    if (config.cluster) {
+      if (!config.cluster.seeds || config.cluster.seeds.length === 0) {
+        throw new Error("Cluster config requires at least one seed node");
+      }
+      this.clusterConfig = {
+        seeds: config.cluster.seeds,
+        connectionsPerNode: config.cluster.connectionsPerNode ?? DEFAULT_CLUSTER_CONFIG.connectionsPerNode,
+        smartRouting: config.cluster.smartRouting ?? DEFAULT_CLUSTER_CONFIG.smartRouting,
+        partitionMapRefreshMs: config.cluster.partitionMapRefreshMs ?? DEFAULT_CLUSTER_CONFIG.partitionMapRefreshMs,
+        connectionTimeoutMs: config.cluster.connectionTimeoutMs ?? DEFAULT_CLUSTER_CONFIG.connectionTimeoutMs,
+        retryAttempts: config.cluster.retryAttempts ?? DEFAULT_CLUSTER_CONFIG.retryAttempts
+      };
+      this.clusterClient = new ClusterClient({
+        enabled: true,
+        seedNodes: this.clusterConfig.seeds,
+        routingMode: this.clusterConfig.smartRouting ? "direct" : "forward",
+        connectionPool: {
+          maxConnectionsPerNode: this.clusterConfig.connectionsPerNode,
+          connectionTimeoutMs: this.clusterConfig.connectionTimeoutMs
+        },
+        routing: {
+          mapRefreshIntervalMs: this.clusterConfig.partitionMapRefreshMs
+        }
+      });
+      this.syncEngine = new SyncEngine({
+        nodeId: this.nodeId,
+        connectionProvider: this.clusterClient,
+        storageAdapter: this.storageAdapter,
+        backoff: config.backoff,
+        backpressure: config.backpressure
+      });
+      logger.info({ seeds: this.clusterConfig.seeds }, "TopGunClient initialized in cluster mode");
+    } else {
+      this.syncEngine = new SyncEngine({
+        nodeId: this.nodeId,
+        serverUrl: config.serverUrl,
+        storageAdapter: this.storageAdapter,
+        backoff: config.backoff,
+        backpressure: config.backpressure
+      });
+      logger.info({ serverUrl: config.serverUrl }, "TopGunClient initialized in single-server mode");
+    }
   }
   async start() {
     await this.storageAdapter.initialize("topgun_offline_db");
@@ -1652,9 +3664,69 @@ var TopGunClient = class {
    * Closes the client, disconnecting from the server and cleaning up resources.
    */
   close() {
+    if (this.clusterClient) {
+      this.clusterClient.close();
+    }
     this.syncEngine.close();
   }
   // ============================================
+  // Cluster Mode API
+  // ============================================
+  /**
+   * Check if running in cluster mode
+   */
+  isCluster() {
+    return this.isClusterMode;
+  }
+  /**
+   * Get list of connected cluster nodes (cluster mode only)
+   * @returns Array of connected node IDs, or empty array in single-server mode
+   */
+  getConnectedNodes() {
+    if (!this.clusterClient) return [];
+    return this.clusterClient.getConnectedNodes();
+  }
+  /**
+   * Get the current partition map version (cluster mode only)
+   * @returns Partition map version, or 0 in single-server mode
+   */
+  getPartitionMapVersion() {
+    if (!this.clusterClient) return 0;
+    return this.clusterClient.getRouterStats().mapVersion;
+  }
+  /**
+   * 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() {
+    if (!this.clusterClient) return false;
+    return this.clusterClient.isRoutingActive();
+  }
+  /**
+   * Get health status for all cluster nodes (cluster mode only)
+   * @returns Map of node IDs to their health status
+   */
+  getClusterHealth() {
+    if (!this.clusterClient) return /* @__PURE__ */ new Map();
+    return this.clusterClient.getHealthStatus();
+  }
+  /**
+   * Force refresh of partition map (cluster mode only)
+   * Use this after detecting routing errors.
+   */
+  async refreshPartitionMap() {
+    if (!this.clusterClient) return;
+    await this.clusterClient.refreshPartitionMap();
+  }
+  /**
+   * Get cluster router statistics (cluster mode only)
+   */
+  getClusterStats() {
+    if (!this.clusterClient) return null;
+    return this.clusterClient.getRouterStats();
+  }
+  // ============================================
   // Connection State API
   // ============================================
   /**
@@ -2005,14 +4077,14 @@ var CollectionWrapper = class {
 };
 
 // src/crypto/EncryptionManager.ts
-import { serialize as serialize2, deserialize as deserialize2 } from "@topgunbuild/core";
+import { serialize as serialize4, deserialize as deserialize3 } from "@topgunbuild/core";
 var _EncryptionManager = class _EncryptionManager {
   /**
    * Encrypts data using AES-GCM.
    * Serializes data to MessagePack before encryption.
    */
   static async encrypt(key, data) {
-    const encoded = serialize2(data);
+    const encoded = serialize4(data);
     const iv = window.crypto.getRandomValues(new Uint8Array(_EncryptionManager.IV_LENGTH));
     const ciphertext = await window.crypto.subtle.encrypt(
       {
@@ -2041,7 +4113,7 @@ var _EncryptionManager = class _EncryptionManager {
         key,
         record.data
       );
-      return deserialize2(new Uint8Array(plaintextBuffer));
+      return deserialize3(new Uint8Array(plaintextBuffer));
     } catch (err) {
       console.error("Decryption failed", err);
       throw new Error("Failed to decrypt data: " + err);
@@ -2168,12 +4240,17 @@ var EncryptedStorageAdapter = class {
 import { LWWMap as LWWMap3, Predicates } from "@topgunbuild/core";
 export {
   BackpressureError,
+  ClusterClient,
+  ConnectionPool,
   DEFAULT_BACKPRESSURE_CONFIG,
+  DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
   IDBAdapter,
   LWWMap3 as LWWMap,
+  PartitionRouter,
   Predicates,
   QueryHandle,
+  SingleServerProvider,
   SyncEngine,
   SyncState,
   SyncStateMachine,