@topgunbuild/server 0.9.0 → 0.10.0

package/dist/index.mjs

@@ -9,13 +9,13 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 import { createServer as createHttpServer } from "http";
 import { createServer as createHttpsServer } from "https";
 import { readFileSync as readFileSync2 } from "fs";
-import { WebSocketServer as WebSocketServer2, WebSocket as WebSocket3 } from "ws";
-import { HLC as HLC2, LWWMap as LWWMap3, ORMap as ORMap2, serialize as serialize4, deserialize, MessageSchema, WriteConcern as WriteConcern2, ConsistencyLevel as ConsistencyLevel3, DEFAULT_REPLICATION_CONFIG as DEFAULT_REPLICATION_CONFIG2, IndexedLWWMap as IndexedLWWMap2, IndexedORMap as IndexedORMap2 } from "@topgunbuild/core";
+import { WebSocketServer as WebSocketServer2, WebSocket as WebSocket5 } from "ws";
+import { HLC as HLC2, LWWMap as LWWMap3, ORMap as ORMap2, serialize as serialize4, deserialize, MessageSchema, WriteConcern as WriteConcern2, ConsistencyLevel as ConsistencyLevel3, DEFAULT_REPLICATION_CONFIG as DEFAULT_REPLICATION_CONFIG2, IndexedLWWMap as IndexedLWWMap2, IndexedORMap as IndexedORMap2, QueryCursor as QueryCursor2, DEFAULT_QUERY_CURSOR_MAX_AGE_MS as DEFAULT_QUERY_CURSOR_MAX_AGE_MS2 } from "@topgunbuild/core";
 import * as jwt from "jsonwebtoken";
 import * as crypto from "crypto";
 
 // src/query/Matcher.ts
-import { evaluatePredicate } from "@topgunbuild/core";
+import { evaluatePredicate, QueryCursor, DEFAULT_QUERY_CURSOR_MAX_AGE_MS } from "@topgunbuild/core";
 function matchesQuery(record, query) {
   const data = record.value;
   if (!data) return false;
@@ -64,6 +64,10 @@ function matchesQuery(record, query) {
   return true;
 }
 function executeQuery(records, query) {
+  const result = executeQueryWithCursor(records, query);
+  return result.results;
+}
+function executeQueryWithCursor(records, query) {
   if (!query) {
     query = {};
   }
@@ -81,9 +85,13 @@ function executeQuery(records, query) {
       }
     }
   }
-  if (query.sort) {
+  const sort = query.sort || {};
+  const sortEntries = Object.entries(sort);
+  const sortField = sortEntries.length > 0 ? sortEntries[0][0] : "_key";
+  const sortDirection = sortEntries.length > 0 ? sortEntries[0][1] : "asc";
+  if (sortEntries.length > 0) {
     results.sort((a, b) => {
-      for (const [field, direction] of Object.entries(query.sort)) {
+      for (const [field, direction] of sortEntries) {
         const valA = a.record.value[field];
         const valB = b.record.value[field];
         if (valA < valB) return direction === "asc" ? -1 : 1;
@@ -92,16 +100,55 @@ function executeQuery(records, query) {
       return 0;
     });
   }
-  if (query.offset || query.limit) {
-    const offset = query.offset || 0;
-    const limit = query.limit || results.length;
-    results = results.slice(offset, offset + limit);
+  let cursorStatus = "none";
+  if (query.cursor) {
+    const cursorData = QueryCursor.decode(query.cursor);
+    if (!cursorData) {
+      cursorStatus = "invalid";
+    } else if (!QueryCursor.isValid(cursorData, query.predicate ?? query.where, sort)) {
+      if (Date.now() - cursorData.timestamp > DEFAULT_QUERY_CURSOR_MAX_AGE_MS) {
+        cursorStatus = "expired";
+      } else {
+        cursorStatus = "invalid";
+      }
+    } else {
+      cursorStatus = "valid";
+      results = results.filter((r) => {
+        const sortValue = r.record.value[sortField];
+        return QueryCursor.isAfterCursor(
+          { key: r.key, sortValue },
+          cursorData
+        );
+      });
+    }
+  }
+  const hasLimit = query.limit !== void 0 && query.limit > 0;
+  const totalBeforeLimit = results.length;
+  if (hasLimit) {
+    results = results.slice(0, query.limit);
+  }
+  const hasMore = hasLimit && totalBeforeLimit > query.limit;
+  let nextCursor;
+  if (hasMore && results.length > 0) {
+    const lastResult = results[results.length - 1];
+    const sortValue = lastResult.record.value[sortField];
+    nextCursor = QueryCursor.fromLastResult(
+      { key: lastResult.key, sortValue },
+      sort,
+      query.predicate ?? query.where
+    );
   }
-  return results.map((r) => ({ key: r.key, value: r.record.value }));
+  return {
+    results: results.map((r) => ({ key: r.key, value: r.record.value })),
+    nextCursor,
+    hasMore,
+    cursorStatus
+  };
 }
 
 // src/query/QueryRegistry.ts
 import { serialize, IndexedLWWMap } from "@topgunbuild/core";
+import { WebSocket } from "ws";
 
 // src/utils/logger.ts
 import pino from "pino";
@@ -290,6 +337,106 @@ var QueryRegistry = class {
       }
     }
   }
+  /**
+   * Set the ClusterManager for distributed subscriptions.
+   */
+  setClusterManager(clusterManager, nodeId) {
+    this.clusterManager = clusterManager;
+    this.nodeId = nodeId;
+  }
+  /**
+   * Set the callback for getting maps by name.
+   * Required for distributed subscriptions to return initial results.
+   */
+  setMapGetter(getter) {
+    this.getMap = getter;
+  }
+  /**
+   * Register a distributed subscription from a remote coordinator.
+   * Called when receiving CLUSTER_SUB_REGISTER message.
+   *
+   * @param subscriptionId - Unique subscription ID
+   * @param mapName - Map name to query
+   * @param query - Query predicate
+   * @param coordinatorNodeId - Node ID of the coordinator (receives updates)
+   * @returns Initial query results from this node
+   */
+  registerDistributed(subscriptionId, mapName, query, coordinatorNodeId) {
+    const dummySocket = {
+      readyState: 1,
+      send: () => {
+      }
+      // Updates go via cluster messages, not socket
+    };
+    let initialResults = [];
+    const previousResultKeys = /* @__PURE__ */ new Set();
+    if (this.getMap) {
+      const map = this.getMap(mapName);
+      if (map) {
+        const records = this.getMapRecords(map);
+        const queryResults = executeQuery(records, query);
+        initialResults = queryResults.map((r) => {
+          previousResultKeys.add(r.key);
+          return { key: r.key, value: r.value };
+        });
+      }
+    }
+    const sub = {
+      id: subscriptionId,
+      clientId: `cluster:${coordinatorNodeId}`,
+      mapName,
+      query,
+      socket: dummySocket,
+      previousResultKeys,
+      coordinatorNodeId,
+      isDistributed: true
+    };
+    this.register(sub);
+    logger.debug(
+      { subscriptionId, mapName, coordinatorNodeId, resultCount: initialResults.length },
+      "Distributed query subscription registered"
+    );
+    return initialResults;
+  }
+  /**
+   * Get a distributed subscription by ID.
+   * Returns undefined if not found or not distributed.
+   */
+  getDistributedSubscription(subscriptionId) {
+    for (const subs of this.subscriptions.values()) {
+      for (const sub of subs) {
+        if (sub.id === subscriptionId && sub.isDistributed) {
+          return sub;
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Unregister all distributed subscriptions where the given node was the coordinator.
+   * Called when a cluster node disconnects.
+   *
+   * @param coordinatorNodeId - Node ID of the disconnected coordinator
+   */
+  unregisterByCoordinator(coordinatorNodeId) {
+    const subscriptionsToRemove = [];
+    for (const subs of this.subscriptions.values()) {
+      for (const sub of subs) {
+        if (sub.isDistributed && sub.coordinatorNodeId === coordinatorNodeId) {
+          subscriptionsToRemove.push(sub.id);
+        }
+      }
+    }
+    for (const subId of subscriptionsToRemove) {
+      this.unregister(subId);
+    }
+    if (subscriptionsToRemove.length > 0) {
+      logger.debug(
+        { coordinatorNodeId, count: subscriptionsToRemove.length },
+        "Cleaned up distributed query subscriptions for disconnected coordinator"
+      );
+    }
+  }
   /**
    * Returns all active subscriptions for a specific map.
    * Used for subscription-based event routing to avoid broadcasting to all clients.
@@ -572,7 +719,9 @@ var QueryRegistry = class {
     return record.value;
   }
   sendUpdate(sub, key, value, type) {
-    if (sub.socket.readyState === 1) {
+    if (sub.isDistributed && sub.coordinatorNodeId && this.clusterManager) {
+      this.sendDistributedUpdate(sub, key, value, type);
+    } else if (sub.socket.readyState === WebSocket.OPEN) {
       sub.socket.send(serialize({
         type: "QUERY_UPDATE",
         payload: {
@@ -584,6 +733,26 @@ var QueryRegistry = class {
       }));
     }
   }
+  /**
+   * Send update to remote coordinator node for a distributed subscription.
+   */
+  sendDistributedUpdate(sub, key, value, type) {
+    if (!this.clusterManager || !sub.coordinatorNodeId) return;
+    const changeType = type === "UPDATE" ? sub.previousResultKeys.has(key) ? "UPDATE" : "ENTER" : "LEAVE";
+    const payload = {
+      subscriptionId: sub.id,
+      sourceNodeId: this.nodeId || "unknown",
+      key,
+      value,
+      changeType,
+      timestamp: Date.now()
+    };
+    this.clusterManager.send(sub.coordinatorNodeId, "CLUSTER_SUB_UPDATE", payload);
+    logger.debug(
+      { subscriptionId: sub.id, key, changeType, coordinator: sub.coordinatorNodeId },
+      "Sent distributed query update"
+    );
+  }
   analyzeQueryFields(query) {
     const fields = /* @__PURE__ */ new Set();
     try {
@@ -722,7 +891,7 @@ var TopicManager = class {
 };
 
 // src/cluster/ClusterManager.ts
-import { WebSocket, WebSocketServer } from "ws";
+import { WebSocket as WebSocket2, WebSocketServer } from "ws";
 import { EventEmitter as EventEmitter2 } from "events";
 import * as dns from "dns";
 import { readFileSync } from "fs";
@@ -1115,7 +1284,7 @@ var ClusterManager = class extends EventEmitter2 {
   sendHeartbeatToAll() {
     for (const [nodeId, member] of this.members) {
       if (member.isSelf) continue;
-      if (member.socket && member.socket.readyState === WebSocket.OPEN) {
+      if (member.socket && member.socket.readyState === WebSocket2.OPEN) {
         this.send(nodeId, "HEARTBEAT", { timestamp: Date.now() });
       }
     }
@@ -1149,7 +1318,7 @@ var ClusterManager = class extends EventEmitter2 {
   broadcastMemberList() {
     for (const [nodeId, member] of this.members) {
       if (member.isSelf) continue;
-      if (member.socket && member.socket.readyState === WebSocket.OPEN) {
+      if (member.socket && member.socket.readyState === WebSocket2.OPEN) {
         this.sendMemberList(nodeId);
       }
     }
@@ -1174,7 +1343,7 @@ var ClusterManager = class extends EventEmitter2 {
     const member = this.members.get(nodeId);
     if (!member) return;
     logger.warn({ nodeId }, "Removing failed node from cluster");
-    if (member.socket && member.socket.readyState !== WebSocket.CLOSED) {
+    if (member.socket && member.socket.readyState !== WebSocket2.CLOSED) {
       try {
         member.socket.terminate();
       } catch (e) {
@@ -1248,9 +1417,9 @@ var ClusterManager = class extends EventEmitter2 {
         if (this.config.tls.caCertPath) {
           wsOptions.ca = readFileSync(this.config.tls.caCertPath);
         }
-        ws = new WebSocket(`${protocol}${peerAddress}`, wsOptions);
+        ws = new WebSocket2(`${protocol}${peerAddress}`, wsOptions);
       } else {
-        ws = new WebSocket(`ws://${peerAddress}`);
+        ws = new WebSocket2(`ws://${peerAddress}`);
       }
       ws.on("open", () => {
         this.pendingConnections.delete(peerAddress);
@@ -1337,7 +1506,7 @@ var ClusterManager = class extends EventEmitter2 {
   }
   send(nodeId, type, payload) {
     const member = this.members.get(nodeId);
-    if (member && member.socket && member.socket.readyState === WebSocket.OPEN) {
+    if (member && member.socket && member.socket.readyState === WebSocket2.OPEN) {
       const msg = {
         type,
         senderId: this.config.nodeId,
@@ -2452,7 +2621,7 @@ var SecurityManager = class {
 };
 
 // src/monitoring/MetricsService.ts
-import { Registry, Gauge, Counter, Summary, collectDefaultMetrics } from "prom-client";
+import { Registry, Gauge, Counter, Summary, Histogram, collectDefaultMetrics } from "prom-client";
 var MetricsService = class {
   constructor() {
     this.registry = new Registry();
@@ -2564,6 +2733,90 @@ var MetricsService = class {
       help: "Current connection rate per second",
       registers: [this.registry]
     });
+    this.distributedSearchTotal = new Counter({
+      name: "topgun_distributed_search_total",
+      help: "Total number of distributed search requests",
+      labelNames: ["map", "status"],
+      registers: [this.registry]
+    });
+    this.distributedSearchDuration = new Summary({
+      name: "topgun_distributed_search_duration_ms",
+      help: "Distribution of distributed search execution times in milliseconds",
+      labelNames: ["map"],
+      percentiles: [0.5, 0.9, 0.95, 0.99],
+      registers: [this.registry]
+    });
+    this.distributedSearchFailedNodes = new Counter({
+      name: "topgun_distributed_search_failed_nodes_total",
+      help: "Total number of node failures during distributed search",
+      registers: [this.registry]
+    });
+    this.distributedSearchPartialResults = new Counter({
+      name: "topgun_distributed_search_partial_results_total",
+      help: "Total number of searches that returned partial results due to node failures",
+      registers: [this.registry]
+    });
+    this.distributedSubTotal = new Counter({
+      name: "topgun_distributed_sub_total",
+      help: "Total distributed subscriptions created",
+      labelNames: ["type", "status"],
+      registers: [this.registry]
+    });
+    this.distributedSubUnsubscribeTotal = new Counter({
+      name: "topgun_distributed_sub_unsubscribe_total",
+      help: "Total unsubscriptions from distributed subscriptions",
+      labelNames: ["type"],
+      registers: [this.registry]
+    });
+    this.distributedSubActive = new Gauge({
+      name: "topgun_distributed_sub_active",
+      help: "Currently active distributed subscriptions",
+      labelNames: ["type"],
+      registers: [this.registry]
+    });
+    this.distributedSubPendingAcks = new Gauge({
+      name: "topgun_distributed_sub_pending_acks",
+      help: "Subscriptions waiting for ACKs from cluster nodes",
+      registers: [this.registry]
+    });
+    this.distributedSubUpdates = new Counter({
+      name: "topgun_distributed_sub_updates_total",
+      help: "Delta updates processed for distributed subscriptions",
+      labelNames: ["direction", "change_type"],
+      registers: [this.registry]
+    });
+    this.distributedSubAckTotal = new Counter({
+      name: "topgun_distributed_sub_ack_total",
+      help: "Node ACK responses for distributed subscriptions",
+      labelNames: ["status"],
+      registers: [this.registry]
+    });
+    this.distributedSubNodeDisconnect = new Counter({
+      name: "topgun_distributed_sub_node_disconnect_total",
+      help: "Node disconnects affecting distributed subscriptions",
+      registers: [this.registry]
+    });
+    this.distributedSubRegistrationDuration = new Histogram({
+      name: "topgun_distributed_sub_registration_duration_ms",
+      help: "Time to register subscription on all nodes",
+      labelNames: ["type"],
+      buckets: [10, 50, 100, 250, 500, 1e3, 2500],
+      registers: [this.registry]
+    });
+    this.distributedSubUpdateLatency = new Histogram({
+      name: "topgun_distributed_sub_update_latency_ms",
+      help: "Latency from data change to client notification",
+      labelNames: ["type"],
+      buckets: [1, 5, 10, 25, 50, 100, 250],
+      registers: [this.registry]
+    });
+    this.distributedSubInitialResultsCount = new Histogram({
+      name: "topgun_distributed_sub_initial_results_count",
+      help: "Initial result set size for distributed subscriptions",
+      labelNames: ["type"],
+      buckets: [0, 1, 5, 10, 25, 50, 100],
+      registers: [this.registry]
+    });
   }
   destroy() {
     this.registry.clear();
@@ -2674,6 +2927,115 @@ var MetricsService = class {
   setConnectionRatePerSecond(rate) {
     this.connectionRatePerSecond.set(rate);
   }
+  // === Distributed search metric methods (Phase 14) ===
+  /**
+   * Record a distributed search request.
+   * @param mapName - Name of the map being searched
+   * @param status - 'success', 'partial', or 'error'
+   */
+  incDistributedSearch(mapName, status) {
+    this.distributedSearchTotal.inc({ map: mapName, status });
+  }
+  /**
+   * Record the duration of a distributed search.
+   * @param mapName - Name of the map being searched
+   * @param durationMs - Duration in milliseconds
+   */
+  recordDistributedSearchDuration(mapName, durationMs) {
+    this.distributedSearchDuration.observe({ map: mapName }, durationMs);
+  }
+  /**
+   * Increment counter for failed nodes during distributed search.
+   * @param count - Number of nodes that failed (default 1)
+   */
+  incDistributedSearchFailedNodes(count = 1) {
+    this.distributedSearchFailedNodes.inc(count);
+  }
+  /**
+   * Increment counter for searches returning partial results.
+   */
+  incDistributedSearchPartialResults() {
+    this.distributedSearchPartialResults.inc();
+  }
+  // === Distributed subscription metric methods (Phase 14.2) ===
+  /**
+   * Record a distributed subscription creation.
+   * @param type - Subscription type (SEARCH or QUERY)
+   * @param status - Result status (success, failed, timeout)
+   */
+  incDistributedSub(type, status) {
+    this.distributedSubTotal.inc({ type, status });
+    if (status === "success") {
+      this.distributedSubActive.inc({ type });
+    }
+  }
+  /**
+   * Record a distributed subscription unsubscription.
+   * @param type - Subscription type (SEARCH or QUERY)
+   */
+  incDistributedSubUnsubscribe(type) {
+    this.distributedSubUnsubscribeTotal.inc({ type });
+  }
+  /**
+   * Decrement the active distributed subscriptions gauge.
+   * @param type - Subscription type (SEARCH or QUERY)
+   */
+  decDistributedSubActive(type) {
+    this.distributedSubActive.dec({ type });
+  }
+  /**
+   * Set the number of subscriptions waiting for ACKs.
+   * @param count - Number of pending ACKs
+   */
+  setDistributedSubPendingAcks(count) {
+    this.distributedSubPendingAcks.set(count);
+  }
+  /**
+   * Record a delta update for distributed subscriptions.
+   * @param direction - Direction of update (sent or received)
+   * @param changeType - Type of change (ENTER, UPDATE, LEAVE)
+   */
+  incDistributedSubUpdates(direction, changeType) {
+    this.distributedSubUpdates.inc({ direction, change_type: changeType });
+  }
+  /**
+   * Record node ACK responses.
+   * @param status - ACK status (success, failed, timeout)
+   * @param count - Number of ACKs to record (default 1)
+   */
+  incDistributedSubAck(status, count = 1) {
+    this.distributedSubAckTotal.inc({ status }, count);
+  }
+  /**
+   * Record a node disconnect affecting distributed subscriptions.
+   */
+  incDistributedSubNodeDisconnect() {
+    this.distributedSubNodeDisconnect.inc();
+  }
+  /**
+   * Record the time to register a subscription on all nodes.
+   * @param type - Subscription type (SEARCH or QUERY)
+   * @param durationMs - Duration in milliseconds
+   */
+  recordDistributedSubRegistration(type, durationMs) {
+    this.distributedSubRegistrationDuration.observe({ type }, durationMs);
+  }
+  /**
+   * Record the latency from data change to client notification.
+   * @param type - Subscription type (SEARCH or QUERY)
+   * @param latencyMs - Latency in milliseconds
+   */
+  recordDistributedSubUpdateLatency(type, latencyMs) {
+    this.distributedSubUpdateLatency.observe({ type }, latencyMs);
+  }
+  /**
+   * Record the initial result set size for a subscription.
+   * @param type - Subscription type (SEARCH or QUERY)
+   * @param count - Number of initial results
+   */
+  recordDistributedSubInitialResultsCount(type, count) {
+    this.distributedSubInitialResultsCount.observe({ type }, count);
+  }
   async getMetrics() {
     return this.registry.metrics();
   }
@@ -3204,7 +3566,7 @@ var BackpressureRegulator = class {
 };
 
 // src/utils/CoalescingWriter.ts
-import { WebSocket as WebSocket2 } from "ws";
+import { WebSocket as WebSocket3 } from "ws";
 import { serialize as serialize3 } from "@topgunbuild/core";
 
 // src/memory/BufferPool.ts
@@ -3774,7 +4136,7 @@ var CoalescingWriter = class {
     }
     this.state = 2 /* FLUSHING */;
     try {
-      if (this.socket.readyState !== WebSocket2.OPEN) {
+      if (this.socket.readyState !== WebSocket3.OPEN) {
         this.queue = [];
         this.pendingBytes = 0;
         this.state = 0 /* IDLE */;
@@ -3847,7 +4209,7 @@ var CoalescingWriter = class {
    * Send a message immediately without batching.
    */
   sendImmediate(data) {
-    if (this.socket.readyState !== WebSocket2.OPEN) {
+    if (this.socket.readyState !== WebSocket3.OPEN) {
       return;
     }
     try {
@@ -7437,7 +7799,7 @@ var RepairScheduler = class extends EventEmitter12 {
     this.processTimer = setInterval(() => {
       this.processRepairQueue();
     }, 1e3);
-    setTimeout(() => {
+    this.initialScanTimer = setTimeout(() => {
       this.scheduleFullScan();
     }, 6e4);
   }
@@ -7455,9 +7817,13 @@ var RepairScheduler = class extends EventEmitter12 {
       clearInterval(this.processTimer);
       this.processTimer = void 0;
     }
+    if (this.initialScanTimer) {
+      clearTimeout(this.initialScanTimer);
+      this.initialScanTimer = void 0;
+    }
     this.repairQueue = [];
     this.activeRepairs.clear();
-    for (const [id, req] of this.pendingRequests) {
+    for (const [, req] of this.pendingRequests) {
       clearTimeout(req.timer);
       req.reject(new Error("Scheduler stopped"));
     }
@@ -9188,11 +9554,13 @@ var EventJournalService = class extends EventJournalImpl {
 };
 
 // src/search/SearchCoordinator.ts
+import { EventEmitter as EventEmitter13 } from "events";
 import {
   FullTextIndex
 } from "@topgunbuild/core";
-var SearchCoordinator = class {
+var SearchCoordinator = class extends EventEmitter13 {
   constructor() {
+    super();
     /** Map name → FullTextIndex */
     this.indexes = /* @__PURE__ */ new Map();
     /** Map name → FullTextIndexConfig (for reference) */
@@ -9217,6 +9585,13 @@ var SearchCoordinator = class {
     this.BATCH_INTERVAL = 16;
     logger.debug("SearchCoordinator initialized");
   }
+  /**
+   * Set the node ID for this server.
+   * Required for distributed subscriptions.
+   */
+  setNodeId(nodeId) {
+    this.nodeId = nodeId;
+  }
   /**
    * Set the callback for sending updates to clients.
    * Called by ServerCoordinator during initialization.
@@ -9518,9 +9893,112 @@ var SearchCoordinator = class {
   getSubscriptionCount() {
     return this.subscriptions.size;
   }
+  // ============================================
+  // Phase 14.2: Distributed Subscription Methods
+  // ============================================
+  /**
+   * Register a distributed subscription from a remote coordinator.
+   * Called when receiving CLUSTER_SUB_REGISTER message.
+   *
+   * @param subscriptionId - Unique subscription ID
+   * @param mapName - Map name to search
+   * @param query - Search query string
+   * @param options - Search options
+   * @param coordinatorNodeId - Node ID of the coordinator (receives updates)
+   * @returns Initial search results from this node
+   */
+  registerDistributedSubscription(subscriptionId, mapName, query, options, coordinatorNodeId) {
+    const index = this.indexes.get(mapName);
+    if (!index) {
+      logger.warn({ mapName }, "Distributed subscription for map without FTS enabled");
+      return { results: [], totalHits: 0 };
+    }
+    const queryTerms = index.tokenizeQuery(query);
+    const searchResults = index.search(query, options);
+    const currentResults = /* @__PURE__ */ new Map();
+    const results = [];
+    for (const result of searchResults) {
+      const value = this.getDocumentValue ? this.getDocumentValue(mapName, result.docId) : void 0;
+      currentResults.set(result.docId, {
+        score: result.score,
+        matchedTerms: result.matchedTerms || []
+      });
+      results.push({
+        key: result.docId,
+        value,
+        score: result.score,
+        matchedTerms: result.matchedTerms || []
+      });
+    }
+    const subscription = {
+      id: subscriptionId,
+      clientId: `cluster:${coordinatorNodeId}`,
+      // Virtual client ID
+      mapName,
+      query,
+      queryTerms,
+      options: options || {},
+      currentResults,
+      // Distributed fields
+      coordinatorNodeId,
+      isDistributed: true
+    };
+    this.subscriptions.set(subscriptionId, subscription);
+    if (!this.subscriptionsByMap.has(mapName)) {
+      this.subscriptionsByMap.set(mapName, /* @__PURE__ */ new Set());
+    }
+    this.subscriptionsByMap.get(mapName).add(subscriptionId);
+    if (!this.subscriptionsByClient.has(subscription.clientId)) {
+      this.subscriptionsByClient.set(subscription.clientId, /* @__PURE__ */ new Set());
+    }
+    this.subscriptionsByClient.get(subscription.clientId).add(subscriptionId);
+    logger.debug(
+      { subscriptionId, mapName, query, coordinatorNodeId, resultCount: results.length },
+      "Distributed search subscription registered"
+    );
+    return {
+      results,
+      totalHits: results.length
+    };
+  }
+  /**
+   * Get a distributed subscription by ID.
+   * Returns undefined if not found or not distributed.
+   */
+  getDistributedSubscription(subscriptionId) {
+    const sub = this.subscriptions.get(subscriptionId);
+    if (sub?.isDistributed) {
+      return sub;
+    }
+    return void 0;
+  }
+  /**
+   * Unsubscribe all distributed subscriptions where the given node was the coordinator.
+   * Called when a cluster node disconnects.
+   *
+   * @param coordinatorNodeId - Node ID of the disconnected coordinator
+   */
+  unsubscribeByCoordinator(coordinatorNodeId) {
+    const subscriptionsToRemove = [];
+    for (const [subId, sub] of this.subscriptions) {
+      if (sub.isDistributed && sub.coordinatorNodeId === coordinatorNodeId) {
+        subscriptionsToRemove.push(subId);
+      }
+    }
+    for (const subId of subscriptionsToRemove) {
+      this.unsubscribe(subId);
+    }
+    if (subscriptionsToRemove.length > 0) {
+      logger.debug(
+        { coordinatorNodeId, count: subscriptionsToRemove.length },
+        "Cleaned up distributed subscriptions for disconnected coordinator"
+      );
+    }
+  }
   /**
    * Notify subscribers about a document change.
    * Computes delta (ENTER/UPDATE/LEAVE) for each affected subscription.
+   * For distributed subscriptions, emits 'distributedUpdate' event instead of sending to client.
    *
    * @param mapName - Name of the map that changed
    * @param key - Document key that changed
@@ -9528,9 +10006,6 @@ var SearchCoordinator = class {
    * @param changeType - Type of change
    */
   notifySubscribers(mapName, key, value, changeType) {
-    if (!this.sendUpdate) {
-      return;
-    }
     const subscriptionIds = this.subscriptionsByMap.get(mapName);
     if (!subscriptionIds || subscriptionIds.size === 0) {
       return;
@@ -9571,18 +10046,50 @@ var SearchCoordinator = class {
       }
       logger.debug({ subId, key, wasInResults, isInResults, updateType, newScore }, "Update decision");
       if (updateType) {
-        this.sendUpdate(
-          sub.clientId,
-          subId,
-          key,
-          value,
-          newScore,
-          matchedTerms,
-          updateType
-        );
+        if (sub.isDistributed && sub.coordinatorNodeId) {
+          this.sendDistributedUpdate(sub, key, value, newScore, matchedTerms, updateType);
+        } else if (this.sendUpdate) {
+          this.sendUpdate(
+            sub.clientId,
+            subId,
+            key,
+            value,
+            newScore,
+            matchedTerms,
+            updateType
+          );
+        }
       }
     }
   }
+  /**
+   * Send update to remote coordinator node for a distributed subscription.
+   * Emits 'distributedUpdate' event with ClusterSubUpdatePayload.
+   *
+   * @param sub - The distributed subscription
+   * @param key - Document key
+   * @param value - Document value
+   * @param score - Search score
+   * @param matchedTerms - Matched search terms
+   * @param changeType - Change type (ENTER/UPDATE/LEAVE)
+   */
+  sendDistributedUpdate(sub, key, value, score, matchedTerms, changeType) {
+    const payload = {
+      subscriptionId: sub.id,
+      sourceNodeId: this.nodeId || "unknown",
+      key,
+      value,
+      score,
+      matchedTerms,
+      changeType,
+      timestamp: Date.now()
+    };
+    this.emit("distributedUpdate", payload);
+    logger.debug(
+      { subscriptionId: sub.id, key, changeType, coordinator: sub.coordinatorNodeId },
+      "Emitted distributed update"
+    );
+  }
   /**
    * Score a single document against a subscription's query.
    *
@@ -9737,44 +10244,1223 @@ var SearchCoordinator = class {
   }
 };
 
-// src/ServerCoordinator.ts
-var GC_INTERVAL_MS = 60 * 60 * 1e3;
-var GC_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
-var CLIENT_HEARTBEAT_TIMEOUT_MS = 2e4;
-var CLIENT_HEARTBEAT_CHECK_INTERVAL_MS = 5e3;
-var ServerCoordinator = class {
-  constructor(config) {
-    this.clients = /* @__PURE__ */ new Map();
-    // Interceptors
-    this.interceptors = [];
-    // In-memory storage (partitioned later)
-    this.maps = /* @__PURE__ */ new Map();
-    this.pendingClusterQueries = /* @__PURE__ */ new Map();
-    // GC Consensus State
-    this.gcReports = /* @__PURE__ */ new Map();
-    // Track map loading state to avoid returning empty results during async load
-    this.mapLoadingPromises = /* @__PURE__ */ new Map();
-    // Track pending batch operations for testing purposes
-    this.pendingBatchOperations = /* @__PURE__ */ new Set();
-    this.journalSubscriptions = /* @__PURE__ */ new Map();
-    this._actualPort = 0;
-    this._actualClusterPort = 0;
-    this._readyPromise = new Promise((resolve) => {
-      this._readyResolve = resolve;
-    });
-    this._nodeId = config.nodeId;
-    this.hlc = new HLC2(config.nodeId);
-    this.storage = config.storage;
-    const rawSecret = config.jwtSecret || process.env.JWT_SECRET || "topgun-secret-dev";
-    this.jwtSecret = rawSecret.replace(/\\n/g, "\n");
-    this.queryRegistry = new QueryRegistry();
-    this.securityManager = new SecurityManager(config.securityPolicies || []);
-    this.interceptors = config.interceptors || [];
-    this.metricsService = new MetricsService();
-    this.eventExecutor = new StripedEventExecutor({
-      stripeCount: config.eventStripeCount ?? 4,
-      queueCapacity: config.eventQueueCapacity ?? 1e4,
-      name: `${config.nodeId}-event-executor`,
+// src/search/ClusterSearchCoordinator.ts
+import { EventEmitter as EventEmitter14 } from "events";
+import {
+  ReciprocalRankFusion,
+  SearchCursor,
+  ClusterSearchReqPayloadSchema,
+  ClusterSearchRespPayloadSchema
+} from "@topgunbuild/core";
+var DEFAULT_CONFIG6 = {
+  rrfK: 60,
+  defaultTimeoutMs: 5e3,
+  defaultMinResponses: 0
+};
+var ClusterSearchCoordinator = class extends EventEmitter14 {
+  constructor(clusterManager, partitionService, localSearchCoordinator, config, metricsService) {
+    super();
+    /** Pending requests awaiting responses */
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.clusterManager = clusterManager;
+    this.partitionService = partitionService;
+    this.localSearchCoordinator = localSearchCoordinator;
+    this.config = { ...DEFAULT_CONFIG6, ...config };
+    this.rrf = new ReciprocalRankFusion({ k: this.config.rrfK });
+    this.metricsService = metricsService;
+    this.clusterManager.on("message", this.handleClusterMessage.bind(this));
+  }
+  /**
+   * Execute a distributed search across the cluster.
+   *
+   * @param mapName - Name of the map to search
+   * @param query - Search query text
+   * @param options - Search options
+   * @returns Promise resolving to merged search results
+   */
+  async search(mapName, query, options = { limit: 10 }) {
+    const startTime = performance.now();
+    const requestId = this.generateRequestId();
+    const timeoutMs = options.timeoutMs ?? this.config.defaultTimeoutMs;
+    const allNodes = new Set(this.clusterManager.getMembers());
+    const myNodeId = this.clusterManager.config.nodeId;
+    if (allNodes.size === 1 && allNodes.has(myNodeId)) {
+      return this.executeLocalSearch(mapName, query, options, startTime);
+    }
+    const perNodeLimit = this.calculatePerNodeLimit(options.limit, options.cursor);
+    let cursorData = null;
+    if (options.cursor) {
+      cursorData = SearchCursor.decode(options.cursor);
+      if (cursorData && !SearchCursor.isValid(cursorData, query)) {
+        cursorData = null;
+        logger.warn({ requestId }, "Invalid or expired cursor, ignoring");
+      }
+    }
+    const promise = new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.resolvePartialResults(requestId);
+      }, timeoutMs);
+      this.pendingRequests.set(requestId, {
+        resolve,
+        reject,
+        responses: /* @__PURE__ */ new Map(),
+        expectedNodes: allNodes,
+        startTime,
+        timeoutHandle,
+        options,
+        mapName,
+        query
+      });
+    });
+    const payload = {
+      requestId,
+      mapName,
+      query,
+      options: {
+        limit: perNodeLimit,
+        minScore: options.minScore,
+        boost: options.boost,
+        includeMatchedTerms: true,
+        // Add cursor position if available
+        ...cursorData ? {
+          afterScore: cursorData.nodeScores[myNodeId],
+          afterKey: cursorData.nodeKeys[myNodeId]
+        } : {}
+      },
+      timeoutMs
+    };
+    for (const nodeId of allNodes) {
+      if (nodeId === myNodeId) {
+        this.executeLocalAndRespond(requestId, mapName, query, perNodeLimit, cursorData);
+      } else {
+        this.clusterManager.send(nodeId, "CLUSTER_SEARCH_REQ", payload);
+      }
+    }
+    return promise;
+  }
+  /**
+   * Handle incoming cluster messages.
+   */
+  handleClusterMessage(msg) {
+    switch (msg.type) {
+      case "CLUSTER_SEARCH_REQ":
+        this.handleSearchRequest(msg.senderId, msg.payload);
+        break;
+      case "CLUSTER_SEARCH_RESP":
+        this.handleSearchResponse(msg.senderId, msg.payload);
+        break;
+    }
+  }
+  /**
+   * Handle incoming search request from another node.
+   */
+  async handleSearchRequest(senderId, rawPayload) {
+    const startTime = performance.now();
+    const myNodeId = this.clusterManager.config.nodeId;
+    const parsed = ClusterSearchReqPayloadSchema.safeParse(rawPayload);
+    if (!parsed.success) {
+      logger.warn(
+        { senderId, error: parsed.error.message },
+        "Invalid cluster search request payload"
+      );
+      this.clusterManager.send(senderId, "CLUSTER_SEARCH_RESP", {
+        requestId: rawPayload?.requestId ?? "unknown",
+        nodeId: myNodeId,
+        results: [],
+        totalHits: 0,
+        executionTimeMs: performance.now() - startTime,
+        error: "Invalid request payload"
+      });
+      return;
+    }
+    const payload = parsed.data;
+    try {
+      const localResult = this.localSearchCoordinator.search(
+        payload.mapName,
+        payload.query,
+        {
+          limit: payload.options.limit,
+          minScore: payload.options.minScore,
+          boost: payload.options.boost
+        }
+      );
+      let results = localResult.results;
+      if (payload.options.afterScore !== void 0) {
+        results = results.filter((r) => {
+          if (r.score < payload.options.afterScore) {
+            return true;
+          }
+          if (r.score === payload.options.afterScore && payload.options.afterKey) {
+            return r.key > payload.options.afterKey;
+          }
+          return false;
+        });
+      }
+      const response = {
+        requestId: payload.requestId,
+        nodeId: myNodeId,
+        results: results.map((r) => ({
+          key: r.key,
+          value: r.value,
+          score: r.score,
+          matchedTerms: r.matchedTerms
+        })),
+        totalHits: localResult.totalCount ?? results.length,
+        executionTimeMs: performance.now() - startTime
+      };
+      this.clusterManager.send(senderId, "CLUSTER_SEARCH_RESP", response);
+    } catch (error) {
+      this.clusterManager.send(senderId, "CLUSTER_SEARCH_RESP", {
+        requestId: payload.requestId,
+        nodeId: myNodeId,
+        results: [],
+        totalHits: 0,
+        executionTimeMs: performance.now() - startTime,
+        error: error instanceof Error ? error.message : "Unknown error"
+      });
+    }
+  }
+  /**
+   * Handle search response from a node.
+   */
+  handleSearchResponse(_senderId, rawPayload) {
+    const parsed = ClusterSearchRespPayloadSchema.safeParse(rawPayload);
+    if (!parsed.success) {
+      logger.warn(
+        { error: parsed.error.message },
+        "Invalid cluster search response payload"
+      );
+      return;
+    }
+    const payload = parsed.data;
+    const pending = this.pendingRequests.get(payload.requestId);
+    if (!pending) {
+      logger.warn({ requestId: payload.requestId }, "Received response for unknown request");
+      return;
+    }
+    pending.responses.set(payload.nodeId, payload);
+    const minResponses = pending.options.minResponses ?? this.config.defaultMinResponses;
+    const requiredResponses = minResponses > 0 ? minResponses : pending.expectedNodes.size;
+    if (pending.responses.size >= requiredResponses) {
+      clearTimeout(pending.timeoutHandle);
+      this.mergeAndResolve(payload.requestId);
+    }
+  }
+  /**
+   * Merge results from all nodes using RRF and resolve the promise.
+   */
+  mergeAndResolve(requestId) {
+    const pending = this.pendingRequests.get(requestId);
+    if (!pending) return;
+    const resultSets = [];
+    const respondedNodes = [];
+    const failedNodes = [];
+    let totalHits = 0;
+    const resultsWithNodes = [];
+    for (const [nodeId, response] of pending.responses) {
+      if (response.error) {
+        failedNodes.push(nodeId);
+        logger.warn({ nodeId, error: response.error }, "Node returned error for search");
+      } else {
+        respondedNodes.push(nodeId);
+        totalHits += response.totalHits;
+        const rankedResults = response.results.map((r) => ({
+          docId: r.key,
+          score: r.score,
+          source: nodeId
+        }));
+        resultSets.push(rankedResults);
+        for (const r of response.results) {
+          resultsWithNodes.push({
+            key: r.key,
+            score: r.score,
+            nodeId,
+            value: r.value,
+            matchedTerms: r.matchedTerms || []
+          });
+        }
+      }
+    }
+    for (const nodeId of pending.expectedNodes) {
+      if (!pending.responses.has(nodeId)) {
+        failedNodes.push(nodeId);
+      }
+    }
+    const merged = this.rrf.merge(resultSets);
+    const limit = pending.options.limit;
+    const results = [];
+    const cursorResults = [];
+    for (const mergedResult of merged.slice(0, limit)) {
+      const original = resultsWithNodes.find((r) => r.key === mergedResult.docId);
+      if (original) {
+        results.push({
+          key: original.key,
+          value: original.value,
+          score: mergedResult.score,
+          // Use RRF score
+          matchedTerms: original.matchedTerms
+        });
+        cursorResults.push({
+          key: original.key,
+          score: original.score,
+          // Use original score for cursor
+          nodeId: original.nodeId
+        });
+      }
+    }
+    let nextCursor;
+    if (merged.length > limit && cursorResults.length > 0) {
+      nextCursor = SearchCursor.fromResults(cursorResults, pending.query);
+    }
+    const executionTimeMs = performance.now() - pending.startTime;
+    if (this.metricsService) {
+      const status = failedNodes.length === 0 ? "success" : respondedNodes.length === 0 ? "error" : "partial";
+      this.metricsService.incDistributedSearch(pending.mapName, status);
+      this.metricsService.recordDistributedSearchDuration(pending.mapName, executionTimeMs);
+      if (failedNodes.length > 0) {
+        this.metricsService.incDistributedSearchFailedNodes(failedNodes.length);
+        if (respondedNodes.length > 0) {
+          this.metricsService.incDistributedSearchPartialResults();
+        }
+      }
+    }
+    pending.resolve({
+      results,
+      totalHits,
+      nextCursor,
+      respondedNodes,
+      failedNodes,
+      executionTimeMs
+    });
+    this.pendingRequests.delete(requestId);
+    logger.debug({
+      requestId,
+      mapName: pending.mapName,
+      query: pending.query,
+      resultCount: results.length,
+      totalHits,
+      respondedNodes: respondedNodes.length,
+      failedNodes: failedNodes.length,
+      executionTimeMs
+    }, "Distributed search completed");
+  }
+  /**
+   * Resolve with partial results when timeout occurs.
+   */
+  resolvePartialResults(requestId) {
+    const pending = this.pendingRequests.get(requestId);
+    if (!pending) return;
+    logger.warn(
+      {
+        requestId,
+        received: pending.responses.size,
+        expected: pending.expectedNodes.size
+      },
+      "Search request timed out, returning partial results"
+    );
+    this.mergeAndResolve(requestId);
+  }
+  /**
+   * Execute local search and add response to pending request.
+   */
+  async executeLocalAndRespond(requestId, mapName, query, limit, cursorData) {
+    const startTime = performance.now();
+    const myNodeId = this.clusterManager.config.nodeId;
+    const pending = this.pendingRequests.get(requestId);
+    if (!pending) return;
+    try {
+      const localResult = this.localSearchCoordinator.search(mapName, query, {
+        limit,
+        minScore: pending.options.minScore,
+        boost: pending.options.boost
+      });
+      let results = localResult.results;
+      if (cursorData) {
+        const position = SearchCursor.getNodePosition(cursorData, myNodeId);
+        if (position) {
+          results = results.filter((r) => {
+            if (r.score < position.afterScore) {
+              return true;
+            }
+            if (r.score === position.afterScore) {
+              return r.key > position.afterKey;
+            }
+            return false;
+          });
+        }
+      }
+      const response = {
+        requestId,
+        nodeId: myNodeId,
+        results: results.map((r) => ({
+          key: r.key,
+          value: r.value,
+          score: r.score,
+          matchedTerms: r.matchedTerms
+        })),
+        totalHits: localResult.totalCount ?? results.length,
+        executionTimeMs: performance.now() - startTime
+      };
+      this.handleSearchResponse(myNodeId, response);
+    } catch (error) {
+      this.handleSearchResponse(myNodeId, {
+        requestId,
+        nodeId: myNodeId,
+        results: [],
+        totalHits: 0,
+        executionTimeMs: performance.now() - startTime,
+        error: error instanceof Error ? error.message : "Unknown error"
+      });
+    }
+  }
+  /**
+   * Execute search locally only (single-node optimization).
+   */
+  async executeLocalSearch(mapName, query, options, startTime) {
+    const myNodeId = this.clusterManager.config.nodeId;
+    const localResult = this.localSearchCoordinator.search(mapName, query, {
+      limit: options.limit,
+      minScore: options.minScore,
+      boost: options.boost
+    });
+    let results = localResult.results;
+    if (options.cursor) {
+      const cursorData = SearchCursor.decode(options.cursor);
+      if (cursorData && SearchCursor.isValid(cursorData, query)) {
+        const position = SearchCursor.getNodePosition(cursorData, myNodeId);
+        if (position) {
+          results = results.filter((r) => {
+            if (r.score < position.afterScore) {
+              return true;
+            }
+            if (r.score === position.afterScore) {
+              return r.key > position.afterKey;
+            }
+            return false;
+          });
+        }
+      }
+    }
+    results = results.slice(0, options.limit);
+    const totalCount = localResult.totalCount ?? localResult.results.length;
+    let nextCursor;
+    if (totalCount > options.limit && results.length > 0) {
+      const lastResult = results[results.length - 1];
+      nextCursor = SearchCursor.fromResults(
+        [{ key: lastResult.key, score: lastResult.score, nodeId: myNodeId }],
+        query
+      );
+    }
+    const executionTimeMs = performance.now() - startTime;
+    if (this.metricsService) {
+      this.metricsService.incDistributedSearch(mapName, "success");
+      this.metricsService.recordDistributedSearchDuration(mapName, executionTimeMs);
+    }
+    return {
+      results,
+      totalHits: localResult.totalCount ?? results.length,
+      nextCursor,
+      respondedNodes: [myNodeId],
+      failedNodes: [],
+      executionTimeMs
+    };
+  }
+  /**
+   * Calculate per-node limit for distributed query.
+   *
+   * For quality RRF merge, each node should return more than the final limit.
+   * Rule of thumb: 2x limit for good merge quality.
+   */
+  calculatePerNodeLimit(limit, cursor) {
+    if (cursor) {
+      return limit;
+    }
+    return Math.min(limit * 2, 1e3);
+  }
+  /**
+   * Generate unique request ID.
+   */
+  generateRequestId() {
+    return `search-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+  /**
+   * Get RRF constant k.
+   */
+  getRrfK() {
+    return this.config.rrfK;
+  }
+  /**
+   * Clean up resources.
+   */
+  destroy() {
+    for (const [requestId, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeoutHandle);
+      pending.reject(new Error("ClusterSearchCoordinator destroyed"));
+    }
+    this.pendingRequests.clear();
+    this.removeAllListeners();
+  }
+};
+
+// src/subscriptions/DistributedSubscriptionCoordinator.ts
+import { EventEmitter as EventEmitter15 } from "events";
+import {
+  ReciprocalRankFusion as ReciprocalRankFusion2,
+  ClusterSubRegisterPayloadSchema,
+  ClusterSubAckPayloadSchema,
+  ClusterSubUpdatePayloadSchema,
+  ClusterSubUnregisterPayloadSchema
+} from "@topgunbuild/core";
+import { WebSocket as WebSocket4 } from "ws";
+var DEFAULT_CONFIG7 = {
+  ackTimeoutMs: 5e3,
+  rrfK: 60
+};
+var DistributedSubscriptionCoordinator = class extends EventEmitter15 {
+  constructor(clusterManager, queryRegistry, searchCoordinator, config, metricsService) {
+    super();
+    /**
+     * Active subscriptions where this node is coordinator.
+     * subscriptionId → SubscriptionState
+     */
+    this.subscriptions = /* @__PURE__ */ new Map();
+    /**
+     * Track which nodes have acknowledged subscription registration.
+     * subscriptionId → Set<nodeId>
+     */
+    this.nodeAcks = /* @__PURE__ */ new Map();
+    /**
+     * Pending ACK promises for subscription registration.
+     * subscriptionId → { resolve, reject, timeout, startTime }
+     */
+    this.pendingAcks = /* @__PURE__ */ new Map();
+    this.clusterManager = clusterManager;
+    this.localQueryRegistry = queryRegistry;
+    this.localSearchCoordinator = searchCoordinator;
+    this.config = { ...DEFAULT_CONFIG7, ...config };
+    this.rrf = new ReciprocalRankFusion2({ k: this.config.rrfK });
+    this.metricsService = metricsService;
+    this.clusterManager.on("message", this.handleClusterMessage.bind(this));
+    this.localSearchCoordinator.on("distributedUpdate", this.handleLocalSearchUpdate.bind(this));
+    this.clusterManager.on("memberLeft", this.handleMemberLeft.bind(this));
+    logger.debug("DistributedSubscriptionCoordinator initialized");
+  }
+  /**
+   * Create a new distributed search subscription.
+   *
+   * @param subscriptionId - Unique subscription ID
+   * @param clientSocket - Client WebSocket for sending updates
+   * @param mapName - Map name to search
+   * @param query - Search query string
+   * @param options - Search options
+   * @returns Promise resolving to initial results
+   */
+  async subscribeSearch(subscriptionId, clientSocket, mapName, query, options = {}) {
+    const myNodeId = this.clusterManager.config.nodeId;
+    const allNodes = new Set(this.clusterManager.getMembers());
+    logger.debug(
+      { subscriptionId, mapName, query, nodes: Array.from(allNodes) },
+      "Creating distributed search subscription"
+    );
+    const subscription = {
+      id: subscriptionId,
+      type: "SEARCH",
+      coordinatorNodeId: myNodeId,
+      clientSocket,
+      mapName,
+      searchQuery: query,
+      searchOptions: options,
+      registeredNodes: /* @__PURE__ */ new Set(),
+      pendingResults: /* @__PURE__ */ new Map(),
+      createdAt: Date.now(),
+      currentResults: /* @__PURE__ */ new Map()
+    };
+    this.subscriptions.set(subscriptionId, subscription);
+    this.nodeAcks.set(subscriptionId, /* @__PURE__ */ new Set());
+    const registerPayload = {
+      subscriptionId,
+      coordinatorNodeId: myNodeId,
+      mapName,
+      type: "SEARCH",
+      searchQuery: query,
+      searchOptions: {
+        limit: options.limit,
+        minScore: options.minScore,
+        boost: options.boost
+      }
+    };
+    const localResult = this.registerLocalSearchSubscription(subscription);
+    this.handleLocalAck(subscriptionId, myNodeId, localResult);
+    for (const nodeId of allNodes) {
+      if (nodeId !== myNodeId) {
+        this.clusterManager.send(nodeId, "CLUSTER_SUB_REGISTER", registerPayload);
+      }
+    }
+    return this.waitForAcks(subscriptionId, allNodes);
+  }
+  /**
+   * Create a new distributed query subscription.
+   *
+   * @param subscriptionId - Unique subscription ID
+   * @param clientSocket - Client WebSocket for sending updates
+   * @param mapName - Map name to query
+   * @param query - Query predicate
+   * @returns Promise resolving to initial results
+   */
+  async subscribeQuery(subscriptionId, clientSocket, mapName, query) {
+    const myNodeId = this.clusterManager.config.nodeId;
+    const allNodes = new Set(this.clusterManager.getMembers());
+    logger.debug(
+      { subscriptionId, mapName, nodes: Array.from(allNodes) },
+      "Creating distributed query subscription"
+    );
+    const subscription = {
+      id: subscriptionId,
+      type: "QUERY",
+      coordinatorNodeId: myNodeId,
+      clientSocket,
+      mapName,
+      queryPredicate: query,
+      registeredNodes: /* @__PURE__ */ new Set(),
+      pendingResults: /* @__PURE__ */ new Map(),
+      createdAt: Date.now(),
+      currentResults: /* @__PURE__ */ new Map()
+    };
+    this.subscriptions.set(subscriptionId, subscription);
+    this.nodeAcks.set(subscriptionId, /* @__PURE__ */ new Set());
+    const registerPayload = {
+      subscriptionId,
+      coordinatorNodeId: myNodeId,
+      mapName,
+      type: "QUERY",
+      queryPredicate: query
+    };
+    const localResults = this.registerLocalQuerySubscription(subscription);
+    this.handleLocalAck(subscriptionId, myNodeId, { results: localResults, totalHits: localResults.length });
+    for (const nodeId of allNodes) {
+      if (nodeId !== myNodeId) {
+        this.clusterManager.send(nodeId, "CLUSTER_SUB_REGISTER", registerPayload);
+      }
+    }
+    return this.waitForAcks(subscriptionId, allNodes);
+  }
+  /**
+   * Unsubscribe from a distributed subscription.
+   *
+   * @param subscriptionId - Subscription ID to unsubscribe
+   */
+  async unsubscribe(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) {
+      logger.warn({ subscriptionId }, "Attempt to unsubscribe from unknown subscription");
+      return;
+    }
+    logger.debug({ subscriptionId }, "Unsubscribing from distributed subscription");
+    const myNodeId = this.clusterManager.config.nodeId;
+    const payload = { subscriptionId };
+    for (const nodeId of subscription.registeredNodes) {
+      if (nodeId !== myNodeId) {
+        this.clusterManager.send(nodeId, "CLUSTER_SUB_UNREGISTER", payload);
+      }
+    }
+    this.unregisterLocalSubscription(subscription);
+    this.subscriptions.delete(subscriptionId);
+    this.nodeAcks.delete(subscriptionId);
+    const pendingAck = this.pendingAcks.get(subscriptionId);
+    if (pendingAck) {
+      clearTimeout(pendingAck.timeoutHandle);
+      this.pendingAcks.delete(subscriptionId);
+    }
+    this.metricsService?.incDistributedSubUnsubscribe(subscription.type);
+    this.metricsService?.decDistributedSubActive(subscription.type);
+    this.metricsService?.setDistributedSubPendingAcks(this.pendingAcks.size);
+  }
+  /**
+   * Handle client disconnect - unsubscribe all their subscriptions.
+   */
+  unsubscribeClient(clientSocket) {
+    const subscriptionsToRemove = [];
+    for (const [subId, sub] of this.subscriptions) {
+      if (sub.clientSocket === clientSocket) {
+        subscriptionsToRemove.push(subId);
+      }
+    }
+    for (const subId of subscriptionsToRemove) {
+      this.unsubscribe(subId);
+    }
+  }
+  /**
+   * Get active subscription count.
+   */
+  getActiveSubscriptionCount() {
+    return this.subscriptions.size;
+  }
+  /**
+   * Handle incoming cluster messages with Zod validation.
+   */
+  handleClusterMessage(msg) {
+    switch (msg.type) {
+      case "CLUSTER_SUB_REGISTER": {
+        const parsed = ClusterSubRegisterPayloadSchema.safeParse(msg.payload);
+        if (!parsed.success) {
+          logger.warn(
+            { senderId: msg.senderId, error: parsed.error.message },
+            "Invalid CLUSTER_SUB_REGISTER payload"
+          );
+          return;
+        }
+        this.handleSubRegister(msg.senderId, parsed.data);
+        break;
+      }
+      case "CLUSTER_SUB_ACK": {
+        const parsed = ClusterSubAckPayloadSchema.safeParse(msg.payload);
+        if (!parsed.success) {
+          logger.warn(
+            { senderId: msg.senderId, error: parsed.error.message },
+            "Invalid CLUSTER_SUB_ACK payload"
+          );
+          return;
+        }
+        this.handleSubAck(msg.senderId, parsed.data);
+        break;
+      }
+      case "CLUSTER_SUB_UPDATE": {
+        const parsed = ClusterSubUpdatePayloadSchema.safeParse(msg.payload);
+        if (!parsed.success) {
+          logger.warn(
+            { senderId: msg.senderId, error: parsed.error.message },
+            "Invalid CLUSTER_SUB_UPDATE payload"
+          );
+          return;
+        }
+        this.handleSubUpdate(msg.senderId, parsed.data);
+        break;
+      }
+      case "CLUSTER_SUB_UNREGISTER": {
+        const parsed = ClusterSubUnregisterPayloadSchema.safeParse(msg.payload);
+        if (!parsed.success) {
+          logger.warn(
+            { senderId: msg.senderId, error: parsed.error.message },
+            "Invalid CLUSTER_SUB_UNREGISTER payload"
+          );
+          return;
+        }
+        this.handleSubUnregister(msg.senderId, parsed.data);
+        break;
+      }
+    }
+  }
+  /**
+   * Handle cluster node disconnect - cleanup subscriptions involving this node.
+   */
+  handleMemberLeft(nodeId) {
+    logger.debug({ nodeId }, "Handling member left for distributed subscriptions");
+    const subscriptionsToRemove = [];
+    const myNodeId = this.clusterManager.config.nodeId;
+    for (const [subId, subscription] of this.subscriptions) {
+      if (subscription.registeredNodes.has(nodeId)) {
+        subscription.registeredNodes.delete(nodeId);
+        for (const [key, result] of subscription.currentResults) {
+          if (result.sourceNode === nodeId) {
+            subscription.currentResults.delete(key);
+          }
+        }
+        logger.debug(
+          { subscriptionId: subId, nodeId, remainingNodes: subscription.registeredNodes.size },
+          "Removed disconnected node from subscription"
+        );
+      }
+    }
+    for (const [subId, pending] of this.pendingAcks) {
+      const acks = this.nodeAcks.get(subId);
+      if (acks && !acks.has(nodeId)) {
+        acks.add(nodeId);
+        this.checkAcksComplete(subId);
+      }
+    }
+    this.localSearchCoordinator.unsubscribeByCoordinator(nodeId);
+    this.localQueryRegistry.unregisterByCoordinator(nodeId);
+    this.metricsService?.incDistributedSubNodeDisconnect();
+  }
+  /**
+   * Handle CLUSTER_SUB_REGISTER from coordinator (we are a data node).
+   */
+  handleSubRegister(senderId, payload) {
+    const myNodeId = this.clusterManager.config.nodeId;
+    logger.debug(
+      { subscriptionId: payload.subscriptionId, coordinator: payload.coordinatorNodeId },
+      "Received distributed subscription registration"
+    );
+    let ackPayload;
+    try {
+      if (payload.type === "SEARCH") {
+        const result = this.localSearchCoordinator.registerDistributedSubscription(
+          payload.subscriptionId,
+          payload.mapName,
+          payload.searchQuery,
+          payload.searchOptions || {},
+          payload.coordinatorNodeId
+        );
+        ackPayload = {
+          subscriptionId: payload.subscriptionId,
+          nodeId: myNodeId,
+          success: true,
+          initialResults: result.results.map((r) => ({
+            key: r.key,
+            value: r.value,
+            score: r.score,
+            matchedTerms: r.matchedTerms
+          })),
+          totalHits: result.totalHits
+        };
+      } else {
+        const results = this.localQueryRegistry.registerDistributed(
+          payload.subscriptionId,
+          payload.mapName,
+          payload.queryPredicate,
+          payload.coordinatorNodeId
+        );
+        ackPayload = {
+          subscriptionId: payload.subscriptionId,
+          nodeId: myNodeId,
+          success: true,
+          initialResults: results.map((r) => ({
+            key: r.key,
+            value: r.value
+          })),
+          totalHits: results.length
+        };
+      }
+    } catch (error) {
+      logger.error(
+        { subscriptionId: payload.subscriptionId, error },
+        "Failed to register distributed subscription locally"
+      );
+      ackPayload = {
+        subscriptionId: payload.subscriptionId,
+        nodeId: myNodeId,
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+    this.clusterManager.send(payload.coordinatorNodeId, "CLUSTER_SUB_ACK", ackPayload);
+  }
+  /**
+   * Handle CLUSTER_SUB_ACK from a data node.
+   */
+  handleSubAck(senderId, payload) {
+    const subscription = this.subscriptions.get(payload.subscriptionId);
+    if (!subscription) {
+      logger.warn(
+        { subscriptionId: payload.subscriptionId, nodeId: payload.nodeId },
+        "Received ACK for unknown subscription"
+      );
+      return;
+    }
+    const acks = this.nodeAcks.get(payload.subscriptionId);
+    if (!acks) return;
+    logger.debug(
+      { subscriptionId: payload.subscriptionId, nodeId: payload.nodeId, success: payload.success },
+      "Received subscription ACK"
+    );
+    if (payload.success) {
+      subscription.registeredNodes.add(payload.nodeId);
+      subscription.pendingResults.set(payload.nodeId, payload);
+    }
+    acks.add(payload.nodeId);
+    this.checkAcksComplete(payload.subscriptionId);
+  }
+  /**
+   * Handle CLUSTER_SUB_UPDATE from a data node.
+   */
+  handleSubUpdate(senderId, payload) {
+    const subscription = this.subscriptions.get(payload.subscriptionId);
+    if (!subscription) {
+      logger.warn(
+        { subscriptionId: payload.subscriptionId },
+        "Update for unknown subscription"
+      );
+      return;
+    }
+    logger.debug(
+      { subscriptionId: payload.subscriptionId, key: payload.key, changeType: payload.changeType },
+      "Received subscription update"
+    );
+    if (payload.changeType === "LEAVE") {
+      subscription.currentResults.delete(payload.key);
+    } else {
+      subscription.currentResults.set(payload.key, {
+        value: payload.value,
+        score: payload.score,
+        sourceNode: payload.sourceNodeId
+      });
+    }
+    this.forwardUpdateToClient(subscription, payload);
+    this.metricsService?.incDistributedSubUpdates("received", payload.changeType);
+    if (payload.timestamp) {
+      const latencyMs = Date.now() - payload.timestamp;
+      this.metricsService?.recordDistributedSubUpdateLatency(subscription.type, latencyMs);
+    }
+  }
+  /**
+   * Handle CLUSTER_SUB_UNREGISTER from coordinator.
+   */
+  handleSubUnregister(senderId, payload) {
+    logger.debug(
+      { subscriptionId: payload.subscriptionId },
+      "Received subscription unregister request"
+    );
+    this.localSearchCoordinator.unsubscribe(payload.subscriptionId);
+    this.localQueryRegistry.unregister(payload.subscriptionId);
+  }
+  /**
+   * Handle local search update (emitted by SearchCoordinator for distributed subscriptions).
+   */
+  handleLocalSearchUpdate(payload) {
+    const coordinatorNodeId = this.getCoordinatorForSubscription(payload.subscriptionId);
+    if (!coordinatorNodeId) return;
+    const myNodeId = this.clusterManager.config.nodeId;
+    if (coordinatorNodeId === myNodeId) {
+      this.handleSubUpdate(myNodeId, payload);
+    } else {
+      this.clusterManager.send(coordinatorNodeId, "CLUSTER_SUB_UPDATE", payload);
+    }
+    this.metricsService?.incDistributedSubUpdates("sent", payload.changeType);
+  }
+  /**
+   * Register a local search subscription for a distributed coordinator.
+   */
+  registerLocalSearchSubscription(subscription) {
+    return this.localSearchCoordinator.registerDistributedSubscription(
+      subscription.id,
+      subscription.mapName,
+      subscription.searchQuery,
+      subscription.searchOptions || {},
+      subscription.coordinatorNodeId
+    );
+  }
+  /**
+   * Register a local query subscription for a distributed coordinator.
+   */
+  registerLocalQuerySubscription(subscription) {
+    return this.localQueryRegistry.registerDistributed(
+      subscription.id,
+      subscription.mapName,
+      subscription.queryPredicate,
+      subscription.coordinatorNodeId
+    );
+  }
+  /**
+   * Unregister local subscription.
+   */
+  unregisterLocalSubscription(subscription) {
+    if (subscription.type === "SEARCH") {
+      this.localSearchCoordinator.unsubscribe(subscription.id);
+    } else {
+      this.localQueryRegistry.unregister(subscription.id);
+    }
+  }
+  /**
+   * Handle local ACK (from this node's registration).
+   */
+  handleLocalAck(subscriptionId, nodeId, result) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return;
+    const acks = this.nodeAcks.get(subscriptionId);
+    if (!acks) return;
+    subscription.registeredNodes.add(nodeId);
+    subscription.pendingResults.set(nodeId, {
+      subscriptionId,
+      nodeId,
+      success: true,
+      initialResults: (result.results || []).map((r) => ({
+        key: r.key,
+        value: r.value,
+        score: r.score,
+        matchedTerms: r.matchedTerms
+      })),
+      totalHits: result.totalHits || (result.results?.length ?? 0)
+    });
+    acks.add(nodeId);
+    this.checkAcksComplete(subscriptionId);
+  }
+  /**
+   * Wait for all node ACKs with timeout.
+   */
+  waitForAcks(subscriptionId, expectedNodes) {
+    return new Promise((resolve, reject) => {
+      const startTime = performance.now();
+      const timeoutHandle = setTimeout(() => {
+        this.resolveWithPartialAcks(subscriptionId);
+      }, this.config.ackTimeoutMs);
+      this.pendingAcks.set(subscriptionId, { resolve, reject, timeoutHandle, startTime });
+      this.metricsService?.setDistributedSubPendingAcks(this.pendingAcks.size);
+      this.checkAcksComplete(subscriptionId);
+    });
+  }
+  /**
+   * Check if all ACKs have been received.
+   */
+  checkAcksComplete(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    const acks = this.nodeAcks.get(subscriptionId);
+    const pendingAck = this.pendingAcks.get(subscriptionId);
+    if (!subscription || !acks || !pendingAck) return;
+    const allNodes = new Set(this.clusterManager.getMembers());
+    if (acks.size >= allNodes.size) {
+      clearTimeout(pendingAck.timeoutHandle);
+      this.pendingAcks.delete(subscriptionId);
+      const duration = performance.now() - pendingAck.startTime;
+      const result = this.mergeInitialResults(subscription);
+      const hasFailures = result.failedNodes.length > 0;
+      this.recordCompletionMetrics(
+        subscription,
+        result,
+        duration,
+        hasFailures ? "timeout" : "success"
+      );
+      pendingAck.resolve(result);
+    }
+  }
+  /**
+   * Resolve with partial ACKs (on timeout).
+   */
+  resolveWithPartialAcks(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    const pendingAck = this.pendingAcks.get(subscriptionId);
+    if (!subscription || !pendingAck) return;
+    this.pendingAcks.delete(subscriptionId);
+    logger.warn(
+      { subscriptionId, registeredNodes: Array.from(subscription.registeredNodes) },
+      "Subscription ACK timeout, resolving with partial results"
+    );
+    const duration = performance.now() - pendingAck.startTime;
+    const result = this.mergeInitialResults(subscription);
+    this.recordCompletionMetrics(subscription, result, duration, "timeout");
+    pendingAck.resolve(result);
+  }
+  /**
+   * Record metrics when subscription registration completes.
+   */
+  recordCompletionMetrics(subscription, result, durationMs, status) {
+    this.metricsService?.incDistributedSub(subscription.type, status);
+    this.metricsService?.recordDistributedSubRegistration(subscription.type, durationMs);
+    this.metricsService?.recordDistributedSubInitialResultsCount(subscription.type, result.results.length);
+    this.metricsService?.setDistributedSubPendingAcks(this.pendingAcks.size);
+    this.metricsService?.incDistributedSubAck("success", subscription.registeredNodes.size);
+    this.metricsService?.incDistributedSubAck("timeout", result.failedNodes.length);
+  }
+  /**
+   * Merge initial results from all nodes.
+   */
+  mergeInitialResults(subscription) {
+    const allNodes = new Set(this.clusterManager.getMembers());
+    const failedNodes = Array.from(allNodes).filter((n) => !subscription.registeredNodes.has(n));
+    if (subscription.type === "SEARCH") {
+      return this.mergeSearchResults(subscription, failedNodes);
+    } else {
+      return this.mergeQueryResults(subscription, failedNodes);
+    }
+  }
+  /**
+   * Merge search results using RRF.
+   */
+  mergeSearchResults(subscription, failedNodes) {
+    const resultSets = [];
+    const resultDataMap = /* @__PURE__ */ new Map();
+    for (const [nodeId, ack] of subscription.pendingResults) {
+      if (ack.success && ack.initialResults) {
+        const rankedResults = [];
+        for (const r of ack.initialResults) {
+          rankedResults.push({
+            docId: r.key,
+            score: r.score ?? 0,
+            source: nodeId
+          });
+          if (!resultDataMap.has(r.key)) {
+            resultDataMap.set(r.key, {
+              key: r.key,
+              value: r.value,
+              score: r.score ?? 0,
+              matchedTerms: r.matchedTerms,
+              nodeId
+            });
+          }
+        }
+        if (rankedResults.length > 0) {
+          resultSets.push(rankedResults);
+        }
+      }
+    }
+    const mergedResults = this.rrf.merge(resultSets);
+    const limit = subscription.searchOptions?.limit ?? 10;
+    const results = [];
+    for (const merged of mergedResults.slice(0, limit)) {
+      const original = resultDataMap.get(merged.docId);
+      if (original) {
+        results.push({
+          key: original.key,
+          value: original.value,
+          score: merged.score,
+          // Use RRF score
+          matchedTerms: original.matchedTerms
+        });
+        subscription.currentResults.set(original.key, {
+          value: original.value,
+          score: merged.score,
+          sourceNode: original.nodeId
+        });
+      }
+    }
+    let totalHits = 0;
+    for (const ack of subscription.pendingResults.values()) {
+      totalHits += ack.totalHits ?? 0;
+    }
+    return {
+      subscriptionId: subscription.id,
+      results,
+      totalHits,
+      registeredNodes: Array.from(subscription.registeredNodes),
+      failedNodes
+    };
+  }
+  /**
+   * Merge query results (simple dedupe by key).
+   */
+  mergeQueryResults(subscription, failedNodes) {
+    const resultMap = /* @__PURE__ */ new Map();
+    for (const [nodeId, ack] of subscription.pendingResults) {
+      if (ack.success && ack.initialResults) {
+        for (const result of ack.initialResults) {
+          if (!resultMap.has(result.key)) {
+            resultMap.set(result.key, { key: result.key, value: result.value });
+            subscription.currentResults.set(result.key, {
+              value: result.value,
+              sourceNode: nodeId
+            });
+          }
+        }
+      }
+    }
+    const results = Array.from(resultMap.values());
+    return {
+      subscriptionId: subscription.id,
+      results,
+      totalHits: results.length,
+      registeredNodes: Array.from(subscription.registeredNodes),
+      failedNodes
+    };
+  }
+  /**
+   * Forward update to client WebSocket.
+   */
+  forwardUpdateToClient(subscription, payload) {
+    if (subscription.clientSocket.readyState !== WebSocket4.OPEN) {
+      logger.warn(
+        { subscriptionId: subscription.id },
+        "Cannot forward update, client socket not open"
+      );
+      return;
+    }
+    const message = subscription.type === "SEARCH" ? {
+      type: "SEARCH_UPDATE",
+      payload: {
+        subscriptionId: payload.subscriptionId,
+        key: payload.key,
+        value: payload.value,
+        score: payload.score,
+        matchedTerms: payload.matchedTerms,
+        type: payload.changeType
+      }
+    } : {
+      type: "QUERY_UPDATE",
+      payload: {
+        queryId: payload.subscriptionId,
+        key: payload.key,
+        value: payload.value,
+        type: payload.changeType
+      }
+    };
+    try {
+      subscription.clientSocket.send(JSON.stringify(message));
+    } catch (error) {
+      logger.error(
+        { subscriptionId: subscription.id, error },
+        "Failed to send update to client"
+      );
+    }
+  }
+  /**
+   * Get coordinator node for a subscription.
+   * For remote subscriptions (where we are a data node), this returns the coordinator.
+   */
+  getCoordinatorForSubscription(subscriptionId) {
+    if (this.subscriptions.has(subscriptionId)) {
+      return this.clusterManager.config.nodeId;
+    }
+    const searchSub = this.localSearchCoordinator.getDistributedSubscription(subscriptionId);
+    if (searchSub?.coordinatorNodeId) {
+      return searchSub.coordinatorNodeId;
+    }
+    const querySub = this.localQueryRegistry.getDistributedSubscription(subscriptionId);
+    if (querySub?.coordinatorNodeId) {
+      return querySub.coordinatorNodeId;
+    }
+    return null;
+  }
+  /**
+   * Cleanup on destroy.
+   */
+  destroy() {
+    for (const subscriptionId of this.subscriptions.keys()) {
+      this.unsubscribe(subscriptionId);
+    }
+    for (const pending of this.pendingAcks.values()) {
+      clearTimeout(pending.timeoutHandle);
+    }
+    this.pendingAcks.clear();
+    this.removeAllListeners();
+  }
+};
+
+// src/ServerCoordinator.ts
+var GC_INTERVAL_MS = 60 * 60 * 1e3;
+var GC_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+var CLIENT_HEARTBEAT_TIMEOUT_MS = 2e4;
+var CLIENT_HEARTBEAT_CHECK_INTERVAL_MS = 5e3;
+var ServerCoordinator = class {
+  constructor(config) {
+    this.clients = /* @__PURE__ */ new Map();
+    // Interceptors
+    this.interceptors = [];
+    // In-memory storage (partitioned later)
+    this.maps = /* @__PURE__ */ new Map();
+    this.pendingClusterQueries = /* @__PURE__ */ new Map();
+    // GC Consensus State
+    this.gcReports = /* @__PURE__ */ new Map();
+    // Track map loading state to avoid returning empty results during async load
+    this.mapLoadingPromises = /* @__PURE__ */ new Map();
+    // Track pending batch operations for testing purposes
+    this.pendingBatchOperations = /* @__PURE__ */ new Set();
+    this.journalSubscriptions = /* @__PURE__ */ new Map();
+    this._actualPort = 0;
+    this._actualClusterPort = 0;
+    this._readyPromise = new Promise((resolve) => {
+      this._readyResolve = resolve;
+    });
+    this._nodeId = config.nodeId;
+    this.hlc = new HLC2(config.nodeId);
+    this.storage = config.storage;
+    const rawSecret = config.jwtSecret || process.env.JWT_SECRET || "topgun-secret-dev";
+    this.jwtSecret = rawSecret.replace(/\\n/g, "\n");
+    this.queryRegistry = new QueryRegistry();
+    this.securityManager = new SecurityManager(config.securityPolicies || []);
+    this.interceptors = config.interceptors || [];
+    this.metricsService = new MetricsService();
+    this.eventExecutor = new StripedEventExecutor({
+      stripeCount: config.eventStripeCount ?? 4,
+      queueCapacity: config.eventQueueCapacity ?? 1e4,
+      name: `${config.nodeId}-event-executor`,
       onReject: (task) => {
         logger.warn({ nodeId: config.nodeId, key: task.key }, "Event task rejected due to queue capacity");
         this.metricsService.incEventQueueRejected();
@@ -9922,7 +11608,7 @@ var ServerCoordinator = class {
         cluster: this.cluster,
         sendToClient: (clientId, message) => {
           const client = this.clients.get(clientId);
-          if (client && client.socket.readyState === WebSocket3.OPEN) {
+          if (client && client.socket.readyState === WebSocket5.OPEN) {
             client.writer.write(message);
           }
         }
@@ -10022,6 +11708,26 @@ var ServerCoordinator = class {
           logger.info({ mapName, fields: ftsConfig.fields }, "FTS enabled for map");
         }
       }
+      this.clusterSearchCoordinator = new ClusterSearchCoordinator(
+        this.cluster,
+        this.partitionService,
+        this.searchCoordinator,
+        config.distributedSearch,
+        this.metricsService
+      );
+      logger.info("ClusterSearchCoordinator initialized for distributed search");
+      this.distributedSubCoordinator = new DistributedSubscriptionCoordinator(
+        this.cluster,
+        this.queryRegistry,
+        this.searchCoordinator,
+        void 0,
+        // Use default config
+        this.metricsService
+      );
+      logger.info("DistributedSubscriptionCoordinator initialized for distributed live subscriptions");
+      this.searchCoordinator.setNodeId(config.nodeId);
+      this.queryRegistry.setClusterManager(this.cluster, config.nodeId);
+      this.queryRegistry.setMapGetter((name) => this.getMap(name));
       this.systemManager = new SystemManager(
         this.cluster,
         this.metricsService,
@@ -10290,7 +11996,7 @@ var ServerCoordinator = class {
     const shutdownMsg = serialize4({ type: "SHUTDOWN_PENDING", retryAfter: 5e3 });
     for (const client of this.clients.values()) {
       try {
-        if (client.socket.readyState === WebSocket3.OPEN) {
+        if (client.socket.readyState === WebSocket5.OPEN) {
           client.socket.send(shutdownMsg);
           if (client.writer) {
             client.writer.close();
@@ -10353,6 +12059,12 @@ var ServerCoordinator = class {
     if (this.eventJournalService) {
       this.eventJournalService.dispose();
     }
+    if (this.clusterSearchCoordinator) {
+      this.clusterSearchCoordinator.destroy();
+    }
+    if (this.distributedSubCoordinator) {
+      this.distributedSubCoordinator.destroy();
+    }
     logger.info("Server Coordinator shutdown complete.");
   }
   async handleConnection(ws) {
@@ -10461,6 +12173,9 @@ var ServerCoordinator = class {
       this.topicManager.unsubscribeAll(clientId);
       this.counterHandler.unsubscribeAll(clientId);
       this.searchCoordinator.unsubscribeClient(clientId);
+      if (this.distributedSubCoordinator && connection) {
+        this.distributedSubCoordinator.unsubscribeClient(connection.socket);
+      }
       const members = this.cluster.getMembers();
       for (const memberId of members) {
         if (!this.cluster.isLocal(memberId)) {
@@ -10535,70 +12250,115 @@ var ServerCoordinator = class {
         }
         logger.info({ clientId: client.id, mapName, query }, "Client subscribed");
         this.metricsService.incOp("SUBSCRIBE", mapName);
-        const allMembers = this.cluster.getMembers();
-        let remoteMembers = allMembers.filter((id) => !this.cluster.isLocal(id));
-        const queryKey = query._id || query.where?._id;
-        if (queryKey && typeof queryKey === "string" && this.readReplicaHandler) {
-          try {
-            const targetNode = this.readReplicaHandler.selectReadNode({
+        if (this.distributedSubCoordinator && this.cluster && this.cluster.getMembers().length > 1) {
+          this.distributedSubCoordinator.subscribeQuery(
+            queryId,
+            client.socket,
+            mapName,
+            query
+          ).then((result) => {
+            const filteredResults = result.results.map((res) => {
+              const filteredValue = this.securityManager.filterObject(res.value, client.principal, mapName);
+              return { ...res, value: filteredValue };
+            });
+            client.writer.write({
+              type: "QUERY_RESP",
+              payload: {
+                queryId,
+                results: filteredResults
+              }
+            });
+            client.subscriptions.add(queryId);
+            logger.debug({
+              clientId: client.id,
+              queryId,
               mapName,
-              key: queryKey,
-              options: {
-                // Default to EVENTUAL for read scaling unless specified otherwise
-                // In future, we could extract consistency from query options if available
-                consistency: ConsistencyLevel3.EVENTUAL
+              resultCount: result.results.length,
+              totalHits: result.totalHits,
+              nodes: result.registeredNodes
+            }, "Distributed query subscription created");
+          }).catch((err) => {
+            logger.error({ err, queryId }, "Distributed query subscription failed");
+            client.writer.write({
+              type: "QUERY_RESP",
+              payload: {
+                queryId,
+                results: [],
+                error: "Failed to create distributed subscription"
               }
             });
-            if (targetNode) {
-              if (this.cluster.isLocal(targetNode)) {
-                remoteMembers = [];
-                logger.debug({ clientId: client.id, mapName, key: queryKey }, "Read optimization: Serving locally");
-              } else if (remoteMembers.includes(targetNode)) {
-                remoteMembers = [targetNode];
-                logger.debug({ clientId: client.id, mapName, key: queryKey, targetNode }, "Read optimization: Routing to replica");
+          });
+        } else {
+          const allMembers = this.cluster.getMembers();
+          let remoteMembers = allMembers.filter((id) => !this.cluster.isLocal(id));
+          const queryKey = query._id || query.where?._id;
+          if (queryKey && typeof queryKey === "string" && this.readReplicaHandler) {
+            try {
+              const targetNode = this.readReplicaHandler.selectReadNode({
+                mapName,
+                key: queryKey,
+                options: {
+                  // Default to EVENTUAL for read scaling unless specified otherwise
+                  // In future, we could extract consistency from query options if available
+                  consistency: ConsistencyLevel3.EVENTUAL
+                }
+              });
+              if (targetNode) {
+                if (this.cluster.isLocal(targetNode)) {
+                  remoteMembers = [];
+                  logger.debug({ clientId: client.id, mapName, key: queryKey }, "Read optimization: Serving locally");
+                } else if (remoteMembers.includes(targetNode)) {
+                  remoteMembers = [targetNode];
+                  logger.debug({ clientId: client.id, mapName, key: queryKey, targetNode }, "Read optimization: Routing to replica");
+                }
               }
+            } catch (e) {
+              logger.warn({ err: e }, "Error in ReadReplicaHandler selection");
             }
-          } catch (e) {
-            logger.warn({ err: e }, "Error in ReadReplicaHandler selection");
           }
-        }
-        const requestId = crypto.randomUUID();
-        const pending = {
-          requestId,
-          client,
-          queryId,
-          mapName,
-          query,
-          results: [],
-          // Will populate with local results first
-          expectedNodes: new Set(remoteMembers),
-          respondedNodes: /* @__PURE__ */ new Set(),
-          timer: setTimeout(() => this.finalizeClusterQuery(requestId, true), 5e3)
-          // 5s timeout
-        };
-        this.pendingClusterQueries.set(requestId, pending);
-        try {
-          const localResults = await this.executeLocalQuery(mapName, query);
-          pending.results.push(...localResults);
-          if (remoteMembers.length > 0) {
-            for (const nodeId of remoteMembers) {
-              this.cluster.send(nodeId, "CLUSTER_QUERY_EXEC", {
-                requestId,
-                mapName,
-                query
-              });
+          const requestId = crypto.randomUUID();
+          const pending = {
+            requestId,
+            client,
+            queryId,
+            mapName,
+            query,
+            results: [],
+            // Will populate with local results first
+            expectedNodes: new Set(remoteMembers),
+            respondedNodes: /* @__PURE__ */ new Set(),
+            timer: setTimeout(() => this.finalizeClusterQuery(requestId, true), 5e3)
+            // 5s timeout
+          };
+          this.pendingClusterQueries.set(requestId, pending);
+          try {
+            const localResults = await this.executeLocalQuery(mapName, query);
+            pending.results.push(...localResults);
+            if (remoteMembers.length > 0) {
+              for (const nodeId of remoteMembers) {
+                this.cluster.send(nodeId, "CLUSTER_QUERY_EXEC", {
+                  requestId,
+                  mapName,
+                  query
+                });
+              }
+            } else {
+              this.finalizeClusterQuery(requestId);
             }
-          } else {
+          } catch (err) {
+            logger.error({ err, mapName }, "Failed to execute local query");
             this.finalizeClusterQuery(requestId);
           }
-        } catch (err) {
-          logger.error({ err, mapName }, "Failed to execute local query");
-          this.finalizeClusterQuery(requestId);
         }
         break;
       }
       case "QUERY_UNSUB": {
         const { queryId: unsubId } = message.payload;
+        if (this.distributedSubCoordinator && this.cluster && this.cluster.getMembers().length > 1) {
+          this.distributedSubCoordinator.unsubscribe(unsubId).catch((err) => {
+            logger.warn({ err, queryId: unsubId }, "Failed to unsubscribe from distributed coordinator");
+          });
+        }
         this.queryRegistry.unregister(unsubId);
         client.subscriptions.delete(unsubId);
         break;
@@ -10922,7 +12682,7 @@ var ServerCoordinator = class {
         client.writer.write(result.response);
         for (const targetClientId of result.broadcastTo) {
           const targetClient = this.clients.get(targetClientId);
-          if (targetClient && targetClient.socket.readyState === WebSocket3.OPEN) {
+          if (targetClient && targetClient.socket.readyState === WebSocket5.OPEN) {
             targetClient.writer.write(result.broadcastMessage);
           }
         }
@@ -11402,7 +13162,7 @@ var ServerCoordinator = class {
         });
         break;
       }
-      // Phase 11.1: Full-Text Search
+      // Phase 11.1: Full-Text Search (Phase 14: Distributed Search)
       case "SEARCH": {
         const { requestId: searchReqId, mapName: searchMapName, query: searchQuery, options: searchOptions } = message.payload;
         if (!this.securityManager.checkPermission(client.principal, searchMapName, "READ")) {
@@ -11430,18 +13190,58 @@ var ServerCoordinator = class {
           });
           break;
         }
-        const searchResult = this.searchCoordinator.search(searchMapName, searchQuery, searchOptions);
-        searchResult.requestId = searchReqId;
-        logger.debug({
-          clientId: client.id,
-          mapName: searchMapName,
-          query: searchQuery,
-          resultCount: searchResult.results.length
-        }, "Search executed");
-        client.writer.write({
-          type: "SEARCH_RESP",
-          payload: searchResult
-        });
+        if (this.clusterSearchCoordinator && this.cluster.getMembers().length > 1) {
+          this.clusterSearchCoordinator.search(searchMapName, searchQuery, {
+            limit: searchOptions?.limit ?? 10,
+            minScore: searchOptions?.minScore,
+            boost: searchOptions?.boost
+          }).then((distributedResult) => {
+            logger.debug({
+              clientId: client.id,
+              mapName: searchMapName,
+              query: searchQuery,
+              resultCount: distributedResult.results.length,
+              totalHits: distributedResult.totalHits,
+              respondedNodes: distributedResult.respondedNodes.length,
+              failedNodes: distributedResult.failedNodes.length,
+              executionTimeMs: distributedResult.executionTimeMs
+            }, "Distributed search executed");
+            client.writer.write({
+              type: "SEARCH_RESP",
+              payload: {
+                requestId: searchReqId,
+                results: distributedResult.results,
+                totalCount: distributedResult.totalHits,
+                // Include cursor for pagination if available
+                nextCursor: distributedResult.nextCursor
+              }
+            });
+          }).catch((err) => {
+            logger.error({ err, mapName: searchMapName, query: searchQuery }, "Distributed search failed");
+            client.writer.write({
+              type: "SEARCH_RESP",
+              payload: {
+                requestId: searchReqId,
+                results: [],
+                totalCount: 0,
+                error: `Distributed search failed: ${err.message}`
+              }
+            });
+          });
+        } else {
+          const searchResult = this.searchCoordinator.search(searchMapName, searchQuery, searchOptions);
+          searchResult.requestId = searchReqId;
+          logger.debug({
+            clientId: client.id,
+            mapName: searchMapName,
+            query: searchQuery,
+            resultCount: searchResult.results.length
+          }, "Local search executed");
+          client.writer.write({
+            type: "SEARCH_RESP",
+            payload: searchResult
+          });
+        }
         break;
       }
       // Phase 11.1b: Live Search Subscriptions
@@ -11472,33 +13272,75 @@ var ServerCoordinator = class {
           });
           break;
         }
-        const initialResults = this.searchCoordinator.subscribe(
-          client.id,
-          subscriptionId,
-          subMapName,
-          subQuery,
-          subOptions
-        );
-        logger.debug({
-          clientId: client.id,
-          subscriptionId,
-          mapName: subMapName,
-          query: subQuery,
-          resultCount: initialResults.length
-        }, "Search subscription created");
-        client.writer.write({
-          type: "SEARCH_RESP",
-          payload: {
-            requestId: subscriptionId,
-            results: initialResults,
-            totalCount: initialResults.length
-          }
-        });
+        if (this.distributedSubCoordinator && this.cluster && this.cluster.getMembers().length > 1) {
+          this.distributedSubCoordinator.subscribeSearch(
+            subscriptionId,
+            client.socket,
+            subMapName,
+            subQuery,
+            subOptions || {}
+          ).then((result) => {
+            client.writer.write({
+              type: "SEARCH_RESP",
+              payload: {
+                requestId: subscriptionId,
+                results: result.results,
+                totalCount: result.totalHits
+              }
+            });
+            logger.debug({
+              clientId: client.id,
+              subscriptionId,
+              mapName: subMapName,
+              query: subQuery,
+              resultCount: result.results.length,
+              totalHits: result.totalHits,
+              nodes: result.registeredNodes
+            }, "Distributed search subscription created");
+          }).catch((err) => {
+            logger.error({ err, subscriptionId }, "Distributed search subscription failed");
+            client.writer.write({
+              type: "SEARCH_RESP",
+              payload: {
+                requestId: subscriptionId,
+                results: [],
+                totalCount: 0,
+                error: "Failed to create distributed subscription"
+              }
+            });
+          });
+        } else {
+          const initialResults = this.searchCoordinator.subscribe(
+            client.id,
+            subscriptionId,
+            subMapName,
+            subQuery,
+            subOptions
+          );
+          logger.debug({
+            clientId: client.id,
+            subscriptionId,
+            mapName: subMapName,
+            query: subQuery,
+            resultCount: initialResults.length
+          }, "Search subscription created (local)");
+          client.writer.write({
+            type: "SEARCH_RESP",
+            payload: {
+              requestId: subscriptionId,
+              results: initialResults,
+              totalCount: initialResults.length
+            }
+          });
+        }
         break;
       }
       case "SEARCH_UNSUB": {
         const { subscriptionId: unsubId } = message.payload;
         this.searchCoordinator.unsubscribe(unsubId);
+        if (this.distributedSubCoordinator) {
+          this.distributedSubCoordinator.unsubscribe(unsubId);
+        }
         logger.debug({ clientId: client.id, subscriptionId: unsubId }, "Search unsubscription");
         break;
       }
@@ -11539,7 +13381,7 @@ var ServerCoordinator = class {
     };
     let broadcastCount = 0;
     for (const client of this.clients.values()) {
-      if (client.isAuthenticated && client.socket.readyState === WebSocket3.OPEN && client.writer) {
+      if (client.isAuthenticated && client.socket.readyState === WebSocket5.OPEN && client.writer) {
         client.writer.write(message);
         broadcastCount++;
       }
@@ -11971,7 +13813,7 @@ var ServerCoordinator = class {
   async executeLocalQuery(mapName, query) {
     const map = await this.getMapAsync(mapName);
     const localQuery = { ...query };
-    delete localQuery.offset;
+    delete localQuery.cursor;
     delete localQuery.limit;
     if (map instanceof IndexedLWWMap2) {
       const coreQuery = this.convertToCoreQuery(localQuery);
@@ -12090,7 +13932,7 @@ var ServerCoordinator = class {
     };
     return mapping[op] || null;
   }
-  finalizeClusterQuery(requestId, timeout = false) {
+  async finalizeClusterQuery(requestId, timeout = false) {
     const pending = this.pendingClusterQueries.get(requestId);
     if (!pending) return;
     if (timeout) {
@@ -12115,7 +13957,49 @@ var ServerCoordinator = class {
         return 0;
       });
     }
-    const slicedResults = query.offset || query.limit ? finalResults.slice(query.offset || 0, (query.offset || 0) + (query.limit || finalResults.length)) : finalResults;
+    let slicedResults = finalResults;
+    let nextCursor;
+    let hasMore = false;
+    let cursorStatus = "none";
+    if (query.cursor || query.limit) {
+      const sort = query.sort || {};
+      const sortEntries = Object.entries(sort);
+      const sortField = sortEntries.length > 0 ? sortEntries[0][0] : "_key";
+      if (query.cursor) {
+        const cursorData = QueryCursor2.decode(query.cursor);
+        if (!cursorData) {
+          cursorStatus = "invalid";
+        } else if (!QueryCursor2.isValid(cursorData, query.predicate ?? query.where, sort)) {
+          if (Date.now() - cursorData.timestamp > DEFAULT_QUERY_CURSOR_MAX_AGE_MS2) {
+            cursorStatus = "expired";
+          } else {
+            cursorStatus = "invalid";
+          }
+        } else {
+          cursorStatus = "valid";
+          slicedResults = finalResults.filter((r) => {
+            const sortValue = r.value[sortField];
+            return QueryCursor2.isAfterCursor(
+              { key: r.key, sortValue },
+              cursorData
+            );
+          });
+        }
+      }
+      if (query.limit) {
+        hasMore = slicedResults.length > query.limit;
+        slicedResults = slicedResults.slice(0, query.limit);
+        if (hasMore && slicedResults.length > 0) {
+          const lastResult = slicedResults[slicedResults.length - 1];
+          const sortValue = lastResult.value[sortField];
+          nextCursor = QueryCursor2.fromLastResult(
+            { key: lastResult.key, sortValue },
+            sort,
+            query.predicate ?? query.where
+          );
+        }
+      }
+    }
     const resultKeys = new Set(slicedResults.map((r) => r.key));
     const sub = {
       id: queryId,
@@ -12134,7 +14018,7 @@ var ServerCoordinator = class {
     });
     client.writer.write({
       type: "QUERY_RESP",
-      payload: { queryId, results: filteredResults }
+      payload: { queryId, results: filteredResults, nextCursor, hasMore, cursorStatus }
     });
   }
   /**
@@ -12246,17 +14130,6 @@ var ServerCoordinator = class {
     }
     return { eventPayload, oldRecord };
   }
-  /**
-   * Broadcast event to cluster members (excluding self).
-   */
-  broadcastToCluster(eventPayload) {
-    const members = this.cluster.getMembers();
-    for (const memberId of members) {
-      if (!this.cluster.isLocal(memberId)) {
-        this.cluster.send(memberId, "CLUSTER_EVENT", eventPayload);
-      }
-    }
-  }
   /**
    * Apply replicated operation from another node (callback for ReplicationPipeline)
    * This is called when we receive a replicated operation as a backup node
@@ -12382,7 +14255,6 @@ var ServerCoordinator = class {
       payload: eventPayload,
       timestamp: this.hlc.now()
     }, originalSenderId);
-    this.broadcastToCluster(eventPayload);
     this.runAfterInterceptors(op, context);
   }
   /**
@@ -12509,7 +14381,6 @@ var ServerCoordinator = class {
       });
     }
     batchedEvents.push(eventPayload);
-    this.broadcastToCluster(eventPayload);
     this.runAfterInterceptors(op, context);
   }
   handleClusterEvent(payload) {
@@ -12754,7 +14625,7 @@ var ServerCoordinator = class {
           idleTime: now - client.lastPingReceived,
           timeoutMs: CLIENT_HEARTBEAT_TIMEOUT_MS
         }, "Evicting dead client (heartbeat timeout)");
-        if (client.socket.readyState === WebSocket3.OPEN) {
+        if (client.socket.readyState === WebSocket5.OPEN) {
           client.socket.close(4002, "Heartbeat timeout");
         }
       }
@@ -12852,11 +14723,18 @@ var ServerCoordinator = class {
                   payload: eventPayload,
                   timestamp: this.hlc.now()
                 });
-                const members = this.cluster.getMembers();
-                for (const memberId of members) {
-                  if (!this.cluster.isLocal(memberId)) {
-                    this.cluster.send(memberId, "CLUSTER_EVENT", eventPayload);
-                  }
+                this.queryRegistry.processChange(name, map, key, tombstone, record);
+                if (this.replicationPipeline) {
+                  const op = {
+                    opType: "set",
+                    mapName: name,
+                    key,
+                    record: tombstone
+                  };
+                  const opId = `ttl:${name}:${key}:${Date.now()}`;
+                  this.replicationPipeline.replicate(op, opId, key).catch((err) => {
+                    logger.warn({ opId, key, err }, "TTL expiration replication failed (non-fatal)");
+                  });
                 }
               }
             }
@@ -12889,6 +14767,7 @@ var ServerCoordinator = class {
         }
         for (const { key, tag } of tagsToExpire) {
           logger.info({ mapName: name, key, tag }, "ORMap Record expired (TTL). Removing.");
+          const oldRecords = map.getRecords(key);
           map.applyTombstone(tag);
           if (this.storage) {
             const records = map.getRecords(key);
@@ -12914,11 +14793,19 @@ var ServerCoordinator = class {
             payload: eventPayload,
             timestamp: this.hlc.now()
           });
-          const members = this.cluster.getMembers();
-          for (const memberId of members) {
-            if (!this.cluster.isLocal(memberId)) {
-              this.cluster.send(memberId, "CLUSTER_EVENT", eventPayload);
-            }
+          const newRecords = map.getRecords(key);
+          this.queryRegistry.processChange(name, map, key, newRecords, oldRecords);
+          if (this.replicationPipeline) {
+            const op = {
+              opType: "OR_REMOVE",
+              mapName: name,
+              key,
+              orTag: tag
+            };
+            const opId = `ttl:${name}:${key}:${tag}:${Date.now()}`;
+            this.replicationPipeline.replicate(op, opId, key).catch((err) => {
+              logger.warn({ opId, key, err }, "ORMap TTL expiration replication failed (non-fatal)");
+            });
           }
         }
         const removedTags = map.prune(olderThan);
@@ -13512,7 +15399,7 @@ function logNativeStatus() {
 }
 
 // src/cluster/ClusterCoordinator.ts
-import { EventEmitter as EventEmitter13 } from "events";
+import { EventEmitter as EventEmitter16 } from "events";
 import {
   DEFAULT_MIGRATION_CONFIG as DEFAULT_MIGRATION_CONFIG3,
   DEFAULT_REPLICATION_CONFIG as DEFAULT_REPLICATION_CONFIG3
@@ -13523,7 +15410,7 @@ var DEFAULT_CLUSTER_COORDINATOR_CONFIG = {
   replication: DEFAULT_REPLICATION_CONFIG3,
   replicationEnabled: true
 };
-var ClusterCoordinator = class extends EventEmitter13 {
+var ClusterCoordinator = class extends EventEmitter16 {
   constructor(config) {
     super();
     this.replicationPipeline = null;