@topgunbuild/client 0.2.1 → 0.4.0

package/dist/index.mjs

@@ -203,6 +203,464 @@ 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/ConflictResolverClient.ts
+var _ConflictResolverClient = class _ConflictResolverClient {
+  // 10 seconds
+  constructor(syncEngine) {
+    this.rejectionListeners = /* @__PURE__ */ new Set();
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.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,
+   * });
+   * ```
+   */
+  async register(mapName, resolver) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Register resolver request timed out"));
+      }, _ConflictResolverClient.REQUEST_TIMEOUT);
+      this.pendingRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+        timeout
+      });
+      try {
+        this.syncEngine.send({
+          type: "REGISTER_RESOLVER",
+          requestId,
+          mapName,
+          resolver: {
+            name: resolver.name,
+            code: resolver.code || "",
+            priority: resolver.priority,
+            keyPattern: resolver.keyPattern
+          }
+        });
+      } catch {
+        this.pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve({ success: false, error: "Not connected to server" });
+      }
+    });
+  }
+  /**
+   * 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
+   */
+  async unregister(mapName, resolverName) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Unregister resolver request timed out"));
+      }, _ConflictResolverClient.REQUEST_TIMEOUT);
+      this.pendingRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+        timeout
+      });
+      try {
+        this.syncEngine.send({
+          type: "UNREGISTER_RESOLVER",
+          requestId,
+          mapName,
+          resolverName
+        });
+      } catch {
+        this.pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve({ success: false, error: "Not connected to server" });
+      }
+    });
+  }
+  /**
+   * List registered conflict resolvers on the server.
+   *
+   * @param mapName Optional - filter by map name
+   * @returns Promise resolving to list of resolver info
+   */
+  async list(mapName) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("List resolvers request timed out"));
+      }, _ConflictResolverClient.REQUEST_TIMEOUT);
+      this.pendingRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result.resolvers);
+        },
+        reject,
+        timeout
+      });
+      try {
+        this.syncEngine.send({
+          type: "LIST_RESOLVERS",
+          requestId,
+          mapName
+        });
+      } catch {
+        this.pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve([]);
+      }
+    });
+  }
+  /**
+   * 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) {
+    this.rejectionListeners.add(listener);
+    return () => this.rejectionListeners.delete(listener);
+  }
+  /**
+   * Handle REGISTER_RESOLVER_RESPONSE from server.
+   * Called by SyncEngine.
+   */
+  handleRegisterResponse(message) {
+    const pending = this.pendingRequests.get(message.requestId);
+    if (pending) {
+      this.pendingRequests.delete(message.requestId);
+      pending.resolve({ success: message.success, error: message.error });
+    }
+  }
+  /**
+   * Handle UNREGISTER_RESOLVER_RESPONSE from server.
+   * Called by SyncEngine.
+   */
+  handleUnregisterResponse(message) {
+    const pending = this.pendingRequests.get(message.requestId);
+    if (pending) {
+      this.pendingRequests.delete(message.requestId);
+      pending.resolve({ success: message.success, error: message.error });
+    }
+  }
+  /**
+   * Handle LIST_RESOLVERS_RESPONSE from server.
+   * Called by SyncEngine.
+   */
+  handleListResponse(message) {
+    const pending = this.pendingRequests.get(message.requestId);
+    if (pending) {
+      this.pendingRequests.delete(message.requestId);
+      pending.resolve({ resolvers: message.resolvers });
+    }
+  }
+  /**
+   * Handle MERGE_REJECTED from server.
+   * Called by SyncEngine.
+   */
+  handleMergeRejected(message) {
+    const rejection = {
+      mapName: message.mapName,
+      key: message.key,
+      attemptedValue: message.attemptedValue,
+      reason: message.reason,
+      timestamp: message.timestamp,
+      nodeId: ""
+      // Not provided by server in this message
+    };
+    logger.debug({ rejection }, "Merge rejected by server");
+    for (const listener of this.rejectionListeners) {
+      try {
+        listener(rejection);
+      } catch (e) {
+        logger.error({ error: e }, "Error in rejection listener");
+      }
+    }
+  }
+  /**
+   * Clear all pending requests (e.g., on disconnect).
+   */
+  clearPending() {
+    for (const [requestId, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Connection lost"));
+    }
+    this.pendingRequests.clear();
+  }
+  /**
+   * Get the number of registered rejection listeners.
+   */
+  get rejectionListenerCount() {
+    return this.rejectionListeners.size;
+  }
+};
+_ConflictResolverClient.REQUEST_TIMEOUT = 1e4;
+var ConflictResolverClient = _ConflictResolverClient;
+
 // src/SyncEngine.ts
 var DEFAULT_BACKOFF_CONFIG = {
   initialDelayMs: 1e3,
@@ -211,7 +669,7 @@ var DEFAULT_BACKOFF_CONFIG = {
   jitter: true,
   maxRetries: 10
 };
-var SyncEngine = class {
+var _SyncEngine = class _SyncEngine {
   constructor(config) {
     this.websocket = null;
     this.opLog = [];
@@ -234,8 +692,28 @@ var SyncEngine = class {
     this.backpressureListeners = /* @__PURE__ */ new Map();
     // Write Concern state (Phase 5.01)
     this.pendingWriteConcernPromises = /* @__PURE__ */ new Map();
+    // ============================================
+    // PN Counter Methods (Phase 5.2)
+    // ============================================
+    /** Counter update listeners by name */
+    this.counterUpdateListeners = /* @__PURE__ */ new Map();
+    // ============================================
+    // Entry Processor Methods (Phase 5.03)
+    // ============================================
+    /** Pending entry processor requests by requestId */
+    this.pendingProcessorRequests = /* @__PURE__ */ new Map();
+    /** Pending batch entry processor requests by requestId */
+    this.pendingBatchProcessorRequests = /* @__PURE__ */ new Map();
+    // ============================================
+    // Event Journal Methods (Phase 5.04)
+    // ============================================
+    /** Message listeners for journal and other generic messages */
+    this.messageListeners = /* @__PURE__ */ new Set();
+    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();
@@ -252,7 +730,16 @@ 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.conflictResolverClient = new ConflictResolverClient(this);
     this.loadOpLog();
   }
   // ============================================
@@ -303,6 +790,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);
@@ -378,6 +924,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) {
@@ -424,36 +1004,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
-        }));
+        });
       }
     }
   }
@@ -494,10 +1072,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);
@@ -514,27 +1092,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
@@ -571,21 +1149,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()) {
@@ -600,10 +1178,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);
@@ -622,10 +1205,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);
@@ -634,6 +1222,7 @@ var SyncEngine = class {
     });
   }
   async handleServerMessage(message) {
+    this.emitMessage(message);
     switch (message.type) {
       case "BATCH": {
         const batchData = message.data;
@@ -804,11 +1393,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": {
@@ -818,10 +1407,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");
           }
@@ -843,10 +1432,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 }
-              }));
+              });
             }
           }
         }
@@ -879,10 +1468,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");
           }
@@ -904,10 +1493,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)) {
@@ -960,6 +1549,51 @@ var SyncEngine = class {
         }
         break;
       }
+      // ============ PN Counter Message Handlers (Phase 5.2) ============
+      case "COUNTER_UPDATE": {
+        const { name, state } = message.payload;
+        logger.debug({ name }, "Received COUNTER_UPDATE");
+        this.handleCounterUpdate(name, state);
+        break;
+      }
+      case "COUNTER_RESPONSE": {
+        const { name, state } = message.payload;
+        logger.debug({ name }, "Received COUNTER_RESPONSE");
+        this.handleCounterUpdate(name, state);
+        break;
+      }
+      // ============ Entry Processor Message Handlers (Phase 5.03) ============
+      case "ENTRY_PROCESS_RESPONSE": {
+        logger.debug({ requestId: message.requestId, success: message.success }, "Received ENTRY_PROCESS_RESPONSE");
+        this.handleEntryProcessResponse(message);
+        break;
+      }
+      case "ENTRY_PROCESS_BATCH_RESPONSE": {
+        logger.debug({ requestId: message.requestId }, "Received ENTRY_PROCESS_BATCH_RESPONSE");
+        this.handleEntryProcessBatchResponse(message);
+        break;
+      }
+      // ============ Conflict Resolver Message Handlers (Phase 5.05) ============
+      case "REGISTER_RESOLVER_RESPONSE": {
+        logger.debug({ requestId: message.requestId, success: message.success }, "Received REGISTER_RESOLVER_RESPONSE");
+        this.conflictResolverClient.handleRegisterResponse(message);
+        break;
+      }
+      case "UNREGISTER_RESOLVER_RESPONSE": {
+        logger.debug({ requestId: message.requestId, success: message.success }, "Received UNREGISTER_RESOLVER_RESPONSE");
+        this.conflictResolverClient.handleUnregisterResponse(message);
+        break;
+      }
+      case "LIST_RESOLVERS_RESPONSE": {
+        logger.debug({ requestId: message.requestId }, "Received LIST_RESOLVERS_RESPONSE");
+        this.conflictResolverClient.handleListResponse(message);
+        break;
+      }
+      case "MERGE_REJECTED": {
+        logger.debug({ mapName: message.mapName, key: message.key, reason: message.reason }, "Received MERGE_REJECTED");
+        this.conflictResolverClient.handleMergeRejected(message);
+        break;
+      }
     }
     if (message.timestamp) {
       this.hlc.update(message.timestamp);
@@ -998,7 +1632,11 @@ 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;
@@ -1015,7 +1653,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);
@@ -1063,12 +1794,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);
     }
   }
   /**
@@ -1147,13 +1878,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");
     }
   }
@@ -1376,16 +2107,371 @@ var SyncEngine = class {
     }
     this.pendingWriteConcernPromises.clear();
   }
+  /**
+   * Subscribe to counter updates from server.
+   * @param name Counter name
+   * @param listener Callback when counter state is updated
+   * @returns Unsubscribe function
+   */
+  onCounterUpdate(name, listener) {
+    if (!this.counterUpdateListeners.has(name)) {
+      this.counterUpdateListeners.set(name, /* @__PURE__ */ new Set());
+    }
+    this.counterUpdateListeners.get(name).add(listener);
+    return () => {
+      this.counterUpdateListeners.get(name)?.delete(listener);
+      if (this.counterUpdateListeners.get(name)?.size === 0) {
+        this.counterUpdateListeners.delete(name);
+      }
+    };
+  }
+  /**
+   * Request initial counter state from server.
+   * @param name Counter name
+   */
+  requestCounter(name) {
+    if (this.isAuthenticated()) {
+      this.sendMessage({
+        type: "COUNTER_REQUEST",
+        payload: { name }
+      });
+    }
+  }
+  /**
+   * Sync local counter state to server.
+   * @param name Counter name
+   * @param state Counter state to sync
+   */
+  syncCounter(name, state) {
+    if (this.isAuthenticated()) {
+      const stateObj = {
+        positive: Object.fromEntries(state.positive),
+        negative: Object.fromEntries(state.negative)
+      };
+      this.sendMessage({
+        type: "COUNTER_SYNC",
+        payload: {
+          name,
+          state: stateObj
+        }
+      });
+    }
+  }
+  /**
+   * Handle incoming counter update from server.
+   * Called by handleServerMessage for COUNTER_UPDATE messages.
+   */
+  handleCounterUpdate(name, stateObj) {
+    const state = {
+      positive: new Map(Object.entries(stateObj.positive)),
+      negative: new Map(Object.entries(stateObj.negative))
+    };
+    const listeners = this.counterUpdateListeners.get(name);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(state);
+        } catch (e) {
+          logger.error({ err: e, counterName: name }, "Counter update listener error");
+        }
+      }
+    }
+  }
+  /**
+   * 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
+   */
+  async executeOnKey(mapName, key, processor) {
+    if (!this.isAuthenticated()) {
+      return {
+        success: false,
+        error: "Not connected to server"
+      };
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingProcessorRequests.delete(requestId);
+        reject(new Error("Entry processor request timed out"));
+      }, _SyncEngine.PROCESSOR_TIMEOUT);
+      this.pendingProcessorRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+        timeout
+      });
+      const sent = this.sendMessage({
+        type: "ENTRY_PROCESS",
+        requestId,
+        mapName,
+        key,
+        processor: {
+          name: processor.name,
+          code: processor.code,
+          args: processor.args
+        }
+      }, key);
+      if (!sent) {
+        this.pendingProcessorRequests.delete(requestId);
+        clearTimeout(timeout);
+        reject(new Error("Failed to send entry processor request"));
+      }
+    });
+  }
+  /**
+   * 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
+   */
+  async executeOnKeys(mapName, keys, processor) {
+    if (!this.isAuthenticated()) {
+      const results = /* @__PURE__ */ new Map();
+      const error = {
+        success: false,
+        error: "Not connected to server"
+      };
+      for (const key of keys) {
+        results.set(key, error);
+      }
+      return results;
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingBatchProcessorRequests.delete(requestId);
+        reject(new Error("Entry processor batch request timed out"));
+      }, _SyncEngine.PROCESSOR_TIMEOUT);
+      this.pendingBatchProcessorRequests.set(requestId, {
+        resolve: (results) => {
+          clearTimeout(timeout);
+          resolve(results);
+        },
+        reject,
+        timeout
+      });
+      const sent = this.sendMessage({
+        type: "ENTRY_PROCESS_BATCH",
+        requestId,
+        mapName,
+        keys,
+        processor: {
+          name: processor.name,
+          code: processor.code,
+          args: processor.args
+        }
+      });
+      if (!sent) {
+        this.pendingBatchProcessorRequests.delete(requestId);
+        clearTimeout(timeout);
+        reject(new Error("Failed to send entry processor batch request"));
+      }
+    });
+  }
+  /**
+   * Handle entry processor response from server.
+   * Called by handleServerMessage for ENTRY_PROCESS_RESPONSE messages.
+   */
+  handleEntryProcessResponse(message) {
+    const pending = this.pendingProcessorRequests.get(message.requestId);
+    if (pending) {
+      this.pendingProcessorRequests.delete(message.requestId);
+      pending.resolve({
+        success: message.success,
+        result: message.result,
+        newValue: message.newValue,
+        error: message.error
+      });
+    }
+  }
+  /**
+   * Handle entry processor batch response from server.
+   * Called by handleServerMessage for ENTRY_PROCESS_BATCH_RESPONSE messages.
+   */
+  handleEntryProcessBatchResponse(message) {
+    const pending = this.pendingBatchProcessorRequests.get(message.requestId);
+    if (pending) {
+      this.pendingBatchProcessorRequests.delete(message.requestId);
+      const resultsMap = /* @__PURE__ */ new Map();
+      for (const [key, result] of Object.entries(message.results)) {
+        resultsMap.set(key, {
+          success: result.success,
+          result: result.result,
+          newValue: result.newValue,
+          error: result.error
+        });
+      }
+      pending.resolve(resultsMap);
+    }
+  }
+  /**
+   * 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, handler2) {
+    if (event === "message") {
+      this.messageListeners.add(handler2);
+    }
+  }
+  /**
+   * Unsubscribe from incoming messages.
+   *
+   * @param event Event type (currently only 'message')
+   * @param handler Message handler to remove
+   */
+  off(event, handler2) {
+    if (event === "message") {
+      this.messageListeners.delete(handler2);
+    }
+  }
+  /**
+   * Send a message to the server.
+   * Public method for EventJournalReader and other components.
+   *
+   * @param message Message object to send
+   */
+  send(message) {
+    this.sendMessage(message);
+  }
+  /**
+   * Emit message to all listeners.
+   * Called internally when a message is received.
+   */
+  emitMessage(message) {
+    for (const listener of this.messageListeners) {
+      try {
+        listener(message);
+      } catch (e) {
+        logger.error({ err: e }, "Message listener error");
+      }
+    }
+  }
+  // ============================================
+  // Conflict Resolver Client (Phase 5.05)
+  // ============================================
+  /**
+   * Get the conflict resolver client for registering custom resolvers
+   * and subscribing to merge rejection events.
+   */
+  getConflictResolverClient() {
+    return this.conflictResolverClient;
+  }
 };
+/** Default timeout for entry processor requests (ms) */
+_SyncEngine.PROCESSOR_TIMEOUT = 3e4;
+var SyncEngine = _SyncEngine;
 
 // src/TopGunClient.ts
 import { LWWMap as LWWMap2, ORMap as ORMap2 } from "@topgunbuild/core";
 
+// src/utils/deepEqual.ts
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return a === b;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(b)) return false;
+  const objA = a;
+  const objB = b;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(objB, key)) return false;
+    if (!deepEqual(objA[key], objB[key])) return false;
+  }
+  return true;
+}
+
+// src/ChangeTracker.ts
+var ChangeTracker = class {
+  constructor() {
+    this.previousSnapshot = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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, timestamp) {
+    const changes = [];
+    for (const [key, value] of current) {
+      const previous = this.previousSnapshot.get(key);
+      if (previous === void 0) {
+        changes.push({ type: "add", key, value, timestamp });
+      } else if (!deepEqual(previous, value)) {
+        changes.push({
+          type: "update",
+          key,
+          value,
+          previousValue: previous,
+          timestamp
+        });
+      }
+    }
+    for (const [key, value] of this.previousSnapshot) {
+      if (!current.has(key)) {
+        changes.push({
+          type: "remove",
+          key,
+          previousValue: value,
+          timestamp
+        });
+      }
+    }
+    this.previousSnapshot = new Map(
+      Array.from(current.entries()).map(([k, v]) => [
+        k,
+        typeof v === "object" && v !== null ? { ...v } : v
+      ])
+    );
+    return changes;
+  }
+  /**
+   * Reset tracker (e.g., on query change or reconnect)
+   */
+  reset() {
+    this.previousSnapshot.clear();
+  }
+  /**
+   * Get current snapshot size for debugging/metrics
+   */
+  get size() {
+    return this.previousSnapshot.size;
+  }
+};
+
 // src/QueryHandle.ts
 var QueryHandle = class {
   constructor(syncEngine, mapName, filter = {}) {
     this.listeners = /* @__PURE__ */ new Set();
     this.currentResults = /* @__PURE__ */ new Map();
+    // Change tracking (Phase 5.1)
+    this.changeTracker = new ChangeTracker();
+    this.pendingChanges = [];
+    this.changeListeners = /* @__PURE__ */ new Set();
     // Track if we've received authoritative server response
     this.hasReceivedServerData = false;
     this.id = crypto.randomUUID();
@@ -1428,14 +2514,15 @@ var QueryHandle = class {
    * - Works with any async storage adapter (PostgreSQL, SQLite, Redis, etc.)
    */
   onResult(items, source = "server") {
-    console.log(`[QueryHandle:${this.mapName}] onResult called with ${items.length} items`, {
+    logger.debug({
+      mapName: this.mapName,
+      itemCount: items.length,
       source,
       currentResultsCount: this.currentResults.size,
-      newItemKeys: items.map((i) => i.key),
       hasReceivedServerData: this.hasReceivedServerData
-    });
+    }, "QueryHandle onResult");
     if (source === "server" && items.length === 0 && !this.hasReceivedServerData) {
-      console.log(`[QueryHandle:${this.mapName}] Ignoring empty server response - waiting for authoritative data`);
+      logger.debug({ mapName: this.mapName }, "QueryHandle ignoring empty server response - waiting for authoritative data");
       return;
     }
     if (source === "server" && items.length > 0) {
@@ -1450,12 +2537,20 @@ var QueryHandle = class {
       }
     }
     if (removedKeys.length > 0) {
-      console.log(`[QueryHandle:${this.mapName}] Removed ${removedKeys.length} keys:`, removedKeys);
+      logger.debug({
+        mapName: this.mapName,
+        removedCount: removedKeys.length,
+        removedKeys
+      }, "QueryHandle removed keys");
     }
     for (const item of items) {
       this.currentResults.set(item.key, item.value);
     }
-    console.log(`[QueryHandle:${this.mapName}] After merge: ${this.currentResults.size} results`);
+    logger.debug({
+      mapName: this.mapName,
+      resultCount: this.currentResults.size
+    }, "QueryHandle after merge");
+    this.computeAndNotifyChanges(Date.now());
     this.notify();
   }
   /**
@@ -1467,8 +2562,80 @@ var QueryHandle = class {
     } else {
       this.currentResults.set(key, value);
     }
+    this.computeAndNotifyChanges(Date.now());
     this.notify();
   }
+  /**
+   * 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) {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+  /**
+   * Get and clear pending changes (Phase 5.1).
+   * Call this to retrieve all changes since the last consume.
+   */
+  consumeChanges() {
+    const changes = [...this.pendingChanges];
+    this.pendingChanges = [];
+    return changes;
+  }
+  /**
+   * Get last change without consuming (Phase 5.1).
+   * Returns null if no pending changes.
+   */
+  getLastChange() {
+    return this.pendingChanges.length > 0 ? this.pendingChanges[this.pendingChanges.length - 1] : null;
+  }
+  /**
+   * Get all pending changes without consuming (Phase 5.1).
+   */
+  getPendingChanges() {
+    return [...this.pendingChanges];
+  }
+  /**
+   * Clear all pending changes (Phase 5.1).
+   */
+  clearChanges() {
+    this.pendingChanges = [];
+  }
+  /**
+   * Reset change tracker (Phase 5.1).
+   * Use when query filter changes or on reconnect.
+   */
+  resetChangeTracker() {
+    this.changeTracker.reset();
+    this.pendingChanges = [];
+  }
+  computeAndNotifyChanges(timestamp) {
+    const changes = this.changeTracker.computeChanges(this.currentResults, timestamp);
+    if (changes.length > 0) {
+      this.pendingChanges.push(...changes);
+      this.notifyChangeListeners(changes);
+    }
+  }
+  notifyChangeListeners(changes) {
+    for (const listener of this.changeListeners) {
+      try {
+        listener(changes);
+      } catch (e) {
+        logger.error({ err: e }, "QueryHandle change listener error");
+      }
+    }
+  }
   notify() {
     const results = this.getSortedResults();
     for (const listener of this.listeners) {
@@ -1487,114 +2654,1877 @@ var QueryHandle = class {
           if (valA < valB) return direction === "asc" ? -1 : 1;
           if (valA > valB) return direction === "asc" ? 1 : -1;
         }
-        return 0;
+        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/PNCounterHandle.ts
+import { PNCounterImpl } from "@topgunbuild/core";
+var COUNTER_STORAGE_PREFIX = "__counter__:";
+var PNCounterHandle = class {
+  constructor(name, nodeId, syncEngine, storageAdapter) {
+    this.syncScheduled = false;
+    this.persistScheduled = false;
+    this.name = name;
+    this.syncEngine = syncEngine;
+    this.storageAdapter = storageAdapter;
+    this.counter = new PNCounterImpl({ nodeId });
+    this.restoreFromStorage();
+    this.unsubscribeFromUpdates = this.syncEngine.onCounterUpdate(name, (state) => {
+      this.counter.merge(state);
+      this.schedulePersist();
+    });
+    this.syncEngine.requestCounter(name);
+    logger.debug({ name, nodeId }, "PNCounterHandle created");
+  }
+  /**
+   * Restore counter state from local storage.
+   * Called during construction to recover offline state.
+   */
+  async restoreFromStorage() {
+    if (!this.storageAdapter) {
+      return;
+    }
+    try {
+      const storageKey = COUNTER_STORAGE_PREFIX + this.name;
+      const stored = await this.storageAdapter.getMeta(storageKey);
+      if (stored && typeof stored === "object" && "p" in stored && "n" in stored) {
+        const state = PNCounterImpl.objectToState(stored);
+        this.counter.merge(state);
+        logger.debug({ name: this.name, value: this.counter.get() }, "PNCounter restored from storage");
+      }
+    } catch (err) {
+      logger.error({ err, name: this.name }, "Failed to restore PNCounter from storage");
+    }
+  }
+  /**
+   * Persist counter state to local storage.
+   * Debounced to avoid excessive writes during rapid operations.
+   */
+  schedulePersist() {
+    if (!this.storageAdapter || this.persistScheduled) return;
+    this.persistScheduled = true;
+    setTimeout(() => {
+      this.persistScheduled = false;
+      this.persistToStorage();
+    }, 100);
+  }
+  /**
+   * Actually persist state to storage.
+   */
+  async persistToStorage() {
+    if (!this.storageAdapter) return;
+    try {
+      const storageKey = COUNTER_STORAGE_PREFIX + this.name;
+      const stateObj = PNCounterImpl.stateToObject(this.counter.getState());
+      await this.storageAdapter.setMeta(storageKey, stateObj);
+      logger.debug({ name: this.name, value: this.counter.get() }, "PNCounter persisted to storage");
+    } catch (err) {
+      logger.error({ err, name: this.name }, "Failed to persist PNCounter to storage");
+    }
+  }
+  /**
+   * Get current counter value.
+   */
+  get() {
+    return this.counter.get();
+  }
+  /**
+   * Increment by 1 and return new value.
+   */
+  increment() {
+    const value = this.counter.increment();
+    this.scheduleSync();
+    this.schedulePersist();
+    return value;
+  }
+  /**
+   * Decrement by 1 and return new value.
+   */
+  decrement() {
+    const value = this.counter.decrement();
+    this.scheduleSync();
+    this.schedulePersist();
+    return value;
+  }
+  /**
+   * Add delta (positive or negative) and return new value.
+   */
+  addAndGet(delta) {
+    const value = this.counter.addAndGet(delta);
+    if (delta !== 0) {
+      this.scheduleSync();
+      this.schedulePersist();
+    }
+    return value;
+  }
+  /**
+   * Get state for sync.
+   */
+  getState() {
+    return this.counter.getState();
+  }
+  /**
+   * Merge remote state.
+   */
+  merge(remote) {
+    this.counter.merge(remote);
+  }
+  /**
+   * Subscribe to value changes.
+   */
+  subscribe(listener) {
+    return this.counter.subscribe(listener);
+  }
+  /**
+   * Get the counter name.
+   */
+  getName() {
+    return this.name;
+  }
+  /**
+   * Cleanup resources.
+   */
+  dispose() {
+    if (this.unsubscribeFromUpdates) {
+      this.unsubscribeFromUpdates();
+    }
+  }
+  /**
+   * Schedule sync to server with debouncing.
+   * Batches rapid increments to avoid network spam.
+   */
+  scheduleSync() {
+    if (this.syncScheduled) return;
+    this.syncScheduled = true;
+    setTimeout(() => {
+      this.syncScheduled = false;
+      this.syncEngine.syncCounter(this.name, this.counter.getState());
+    }, 50);
+  }
+};
+
+// src/EventJournalReader.ts
+var EventJournalReader = class {
+  constructor(syncEngine) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.subscriptionCounter = 0;
+    this.syncEngine = syncEngine;
+  }
+  /**
+   * Read events from sequence with optional limit.
+   *
+   * @param sequence Starting sequence (inclusive)
+   * @param limit Maximum events to return (default: 100)
+   * @returns Promise resolving to array of events
+   */
+  async readFrom(sequence, limit = 100) {
+    const requestId = this.generateRequestId();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("Journal read timeout"));
+      }, 1e4);
+      const handleResponse = (message) => {
+        if (message.type === "JOURNAL_READ_RESPONSE" && message.requestId === requestId) {
+          clearTimeout(timeout);
+          this.syncEngine.off("message", handleResponse);
+          const events = message.events.map((e) => this.parseEvent(e));
+          resolve(events);
+        }
+      };
+      this.syncEngine.on("message", handleResponse);
+      this.syncEngine.send({
+        type: "JOURNAL_READ",
+        requestId,
+        fromSequence: sequence.toString(),
+        limit
+      });
+    });
+  }
+  /**
+   * 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)
+   */
+  async readMapEvents(mapName, sequence = 0n, limit = 100) {
+    const requestId = this.generateRequestId();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("Journal read timeout"));
+      }, 1e4);
+      const handleResponse = (message) => {
+        if (message.type === "JOURNAL_READ_RESPONSE" && message.requestId === requestId) {
+          clearTimeout(timeout);
+          this.syncEngine.off("message", handleResponse);
+          const events = message.events.map((e) => this.parseEvent(e));
+          resolve(events);
+        }
+      };
+      this.syncEngine.on("message", handleResponse);
+      this.syncEngine.send({
+        type: "JOURNAL_READ",
+        requestId,
+        fromSequence: sequence.toString(),
+        limit,
+        mapName
+      });
+    });
+  }
+  /**
+   * Subscribe to new journal events.
+   *
+   * @param listener Callback for each event
+   * @param options Subscription options
+   * @returns Unsubscribe function
+   */
+  subscribe(listener, options = {}) {
+    const subscriptionId = this.generateRequestId();
+    this.listeners.set(subscriptionId, listener);
+    const handleEvent = (message) => {
+      if (message.type === "JOURNAL_EVENT") {
+        const event = this.parseEvent(message.event);
+        if (options.mapName && event.mapName !== options.mapName) return;
+        if (options.types && !options.types.includes(event.type)) return;
+        const listenerFn = this.listeners.get(subscriptionId);
+        if (listenerFn) {
+          try {
+            listenerFn(event);
+          } catch (e) {
+            logger.error({ err: e }, "Journal listener error");
+          }
+        }
+      }
+    };
+    this.syncEngine.on("message", handleEvent);
+    this.syncEngine.send({
+      type: "JOURNAL_SUBSCRIBE",
+      requestId: subscriptionId,
+      fromSequence: options.fromSequence?.toString(),
+      mapName: options.mapName,
+      types: options.types
+    });
+    return () => {
+      this.listeners.delete(subscriptionId);
+      this.syncEngine.off("message", handleEvent);
+      this.syncEngine.send({
+        type: "JOURNAL_UNSUBSCRIBE",
+        subscriptionId
+      });
+    };
+  }
+  /**
+   * Get the latest sequence number from server.
+   */
+  async getLatestSequence() {
+    const events = await this.readFrom(0n, 1);
+    if (events.length === 0) return 0n;
+    return events[events.length - 1].sequence;
+  }
+  /**
+   * Parse network event data to JournalEvent.
+   */
+  parseEvent(raw) {
+    return {
+      sequence: BigInt(raw.sequence),
+      type: raw.type,
+      mapName: raw.mapName,
+      key: raw.key,
+      value: raw.value,
+      previousValue: raw.previousValue,
+      timestamp: raw.timestamp,
+      nodeId: raw.nodeId,
+      metadata: raw.metadata
+    };
+  }
+  /**
+   * Generate unique request ID.
+   */
+  generateRequestId() {
+    return `journal_${Date.now()}_${++this.subscriptionCounter}`;
+  }
+};
+
+// 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);
+    }
+    this.connectionPool.startHealthCheck();
+    this.partitionRouter.startPeriodicRefresh();
+    this.initialized = true;
+    await this.waitForPartitionMap();
+  }
+  /**
+   * Set authentication token
+   */
+  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);
+    }
+    return this.sendForward(message);
+  }
+  /**
+   * 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;
+  }
+  /**
+   * 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, []);
+        }
+        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
+  // ============================================
+  /**
+   * Get the connection pool (for internal use)
+   */
+  getConnectionPool() {
+    return this.connectionPool;
   }
   /**
-   * Subscribe to the topic
+   * Get the partition router (for internal use)
    */
-  subscribe(callback) {
-    if (this.listeners.size === 0) {
-      this.engine.subscribeToTopic(this.topic, this);
+  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();
+    this.counters = /* @__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");
@@ -1628,6 +4558,34 @@ var TopGunClient = class {
     }
     return this.topicHandles.get(name);
   }
+  /**
+   * 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) {
+    let counter = this.counters.get(name);
+    if (!counter) {
+      counter = new PNCounterHandle(name, this.nodeId, this.syncEngine, this.storageAdapter);
+      this.counters.set(name, counter);
+    }
+    return counter;
+  }
   /**
    * Retrieves an LWWMap instance. If the map doesn't exist locally, it's created.
    * @param name The name of the map.
@@ -1754,9 +4712,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
   // ============================================
   /**
@@ -1840,6 +4858,175 @@ var TopGunClient = class {
   onBackpressure(event, listener) {
     return this.syncEngine.onBackpressure(event, listener);
   }
+  // ============================================
+  // Entry Processor API (Phase 5.03)
+  // ============================================
+  /**
+   * 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)
+   * );
+   * ```
+   */
+  async executeOnKey(mapName, key, processor) {
+    const result = await this.syncEngine.executeOnKey(mapName, key, processor);
+    if (result.success && result.newValue !== void 0) {
+      const map = this.maps.get(mapName);
+      if (map instanceof LWWMap2) {
+        map.set(key, result.newValue);
+      }
+    }
+    return result;
+  }
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async executeOnKeys(mapName, keys, processor) {
+    const results = await this.syncEngine.executeOnKeys(mapName, keys, processor);
+    const map = this.maps.get(mapName);
+    if (map instanceof LWWMap2) {
+      for (const [key, result] of results) {
+        if (result.success && result.newValue !== void 0) {
+          map.set(key, result.newValue);
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * 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() {
+    if (!this.journalReader) {
+      this.journalReader = new EventJournalReader(this.syncEngine);
+    }
+    return this.journalReader;
+  }
+  // ============================================
+  // Conflict Resolver API (Phase 5.05)
+  // ============================================
+  /**
+   * 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() {
+    return this.syncEngine.getConflictResolverClient();
+  }
 };
 
 // src/adapters/IDBAdapter.ts
@@ -2107,14 +5294,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(
       {
@@ -2143,7 +5330,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);
@@ -2270,12 +5457,21 @@ var EncryptedStorageAdapter = class {
 import { LWWMap as LWWMap3, Predicates } from "@topgunbuild/core";
 export {
   BackpressureError,
+  ChangeTracker,
+  ClusterClient,
+  ConflictResolverClient,
+  ConnectionPool,
   DEFAULT_BACKPRESSURE_CONFIG,
+  DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
+  EventJournalReader,
   IDBAdapter,
   LWWMap3 as LWWMap,
+  PNCounterHandle,
+  PartitionRouter,
   Predicates,
   QueryHandle,
+  SingleServerProvider,
   SyncEngine,
   SyncState,
   SyncStateMachine,