@topgunbuild/server 0.2.1 → 0.3.0

package/dist/index.js

@@ -31,16 +31,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BufferPool: () => BufferPool,
+  ClusterCoordinator: () => ClusterCoordinator,
+  ClusterManager: () => ClusterManager,
   ConnectionRateLimiter: () => ConnectionRateLimiter,
+  DEFAULT_CLUSTER_COORDINATOR_CONFIG: () => DEFAULT_CLUSTER_COORDINATOR_CONFIG,
+  DEFAULT_LAG_TRACKER_CONFIG: () => DEFAULT_LAG_TRACKER_CONFIG,
   FilterTasklet: () => FilterTasklet,
   ForEachTasklet: () => ForEachTasklet,
   IteratorTasklet: () => IteratorTasklet,
+  LagTracker: () => LagTracker,
+  LockManager: () => LockManager,
   MapTasklet: () => MapTasklet,
   MemoryServerAdapter: () => MemoryServerAdapter,
+  MigrationManager: () => MigrationManager,
   ObjectPool: () => ObjectPool,
+  PartitionService: () => PartitionService,
   PostgresAdapter: () => PostgresAdapter,
   RateLimitInterceptor: () => RateLimitInterceptor,
   ReduceTasklet: () => ReduceTasklet,
+  ReplicationPipeline: () => ReplicationPipeline,
   SecurityManager: () => SecurityManager,
   ServerCoordinator: () => ServerCoordinator,
   TaskletScheduler: () => TaskletScheduler,
@@ -73,7 +82,7 @@ var import_http = require("http");
 var import_https = require("https");
 var import_fs2 = require("fs");
 var import_ws3 = require("ws");
-var import_core7 = require("@topgunbuild/core");
+var import_core10 = require("@topgunbuild/core");
 var jwt = __toESM(require("jsonwebtoken"));
 var crypto = __toESM(require("crypto"));
 
@@ -633,11 +642,268 @@ var TopicManager = class {
 
 // src/cluster/ClusterManager.ts
 var import_ws = require("ws");
-var import_events = require("events");
+var import_events2 = require("events");
 var dns = __toESM(require("dns"));
 var import_fs = require("fs");
 var https = __toESM(require("https"));
-var ClusterManager = class extends import_events.EventEmitter {
+
+// src/cluster/FailureDetector.ts
+var import_events = require("events");
+var DEFAULT_FAILURE_DETECTOR_CONFIG = {
+  heartbeatIntervalMs: 1e3,
+  suspicionTimeoutMs: 5e3,
+  confirmationTimeoutMs: 1e4,
+  phiThreshold: 8,
+  minSamples: 10,
+  maxSamples: 100,
+  initialHeartbeatIntervalMs: 1e3
+};
+var FailureDetector = class extends import_events.EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.nodeStates = /* @__PURE__ */ new Map();
+    this.monitoringNodes = /* @__PURE__ */ new Set();
+    this.confirmationTimers = /* @__PURE__ */ new Map();
+    this.started = false;
+    this.config = { ...DEFAULT_FAILURE_DETECTOR_CONFIG, ...config };
+  }
+  /**
+   * Start the failure detector monitoring loop.
+   */
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.checkTimer = setInterval(() => {
+      this.checkAllNodes();
+    }, this.config.heartbeatIntervalMs);
+    logger.info({ config: this.config }, "FailureDetector started");
+  }
+  /**
+   * Stop the failure detector and clean up.
+   */
+  stop() {
+    if (!this.started) return;
+    this.started = false;
+    if (this.checkTimer) {
+      clearInterval(this.checkTimer);
+      this.checkTimer = void 0;
+    }
+    for (const timer of this.confirmationTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.confirmationTimers.clear();
+    logger.info("FailureDetector stopped");
+  }
+  /**
+   * Start monitoring a node.
+   */
+  startMonitoring(nodeId) {
+    if (this.monitoringNodes.has(nodeId)) return;
+    this.monitoringNodes.add(nodeId);
+    this.nodeStates.set(nodeId, {
+      lastHeartbeat: Date.now(),
+      intervalHistory: [],
+      isSuspected: false,
+      isConfirmedFailed: false
+    });
+    logger.debug({ nodeId }, "Started monitoring node");
+  }
+  /**
+   * Stop monitoring a node.
+   */
+  stopMonitoring(nodeId) {
+    this.monitoringNodes.delete(nodeId);
+    this.nodeStates.delete(nodeId);
+    const timer = this.confirmationTimers.get(nodeId);
+    if (timer) {
+      clearTimeout(timer);
+      this.confirmationTimers.delete(nodeId);
+    }
+    logger.debug({ nodeId }, "Stopped monitoring node");
+  }
+  /**
+   * Record a heartbeat from a node.
+   * This updates the node's state and clears any suspicion.
+   */
+  recordHeartbeat(nodeId) {
+    const state = this.nodeStates.get(nodeId);
+    if (!state) {
+      this.startMonitoring(nodeId);
+      return;
+    }
+    const now = Date.now();
+    const interval = now - state.lastHeartbeat;
+    state.intervalHistory.push(interval);
+    if (state.intervalHistory.length > this.config.maxSamples) {
+      state.intervalHistory.shift();
+    }
+    state.lastHeartbeat = now;
+    if (state.isSuspected) {
+      state.isSuspected = false;
+      state.suspicionStartTime = void 0;
+      state.isConfirmedFailed = false;
+      const timer = this.confirmationTimers.get(nodeId);
+      if (timer) {
+        clearTimeout(timer);
+        this.confirmationTimers.delete(nodeId);
+      }
+      this.emit("nodeRecovered", { nodeId });
+      logger.info({ nodeId }, "Node recovered");
+    }
+  }
+  /**
+   * Check all monitored nodes for failure.
+   */
+  checkAllNodes() {
+    for (const nodeId of this.monitoringNodes) {
+      const phi = this.calculatePhi(nodeId);
+      const state = this.nodeStates.get(nodeId);
+      if (!state) continue;
+      if (phi > this.config.phiThreshold) {
+        if (!state.isSuspected) {
+          state.isSuspected = true;
+          state.suspicionStartTime = Date.now();
+          this.emit("nodeSuspected", { nodeId, phi });
+          logger.warn({ nodeId, phi }, "Node suspected");
+          this.scheduleConfirmation(nodeId);
+        }
+      }
+    }
+  }
+  /**
+   * Schedule failure confirmation after suspicion timeout.
+   */
+  scheduleConfirmation(nodeId) {
+    const existingTimer = this.confirmationTimers.get(nodeId);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+    const timer = setTimeout(() => {
+      this.confirmFailure(nodeId);
+    }, this.config.confirmationTimeoutMs);
+    this.confirmationTimers.set(nodeId, timer);
+  }
+  /**
+   * Confirm node failure after confirmation timeout.
+   */
+  confirmFailure(nodeId) {
+    const state = this.nodeStates.get(nodeId);
+    if (!state) return;
+    if (state.isSuspected && !state.isConfirmedFailed) {
+      state.isConfirmedFailed = true;
+      this.emit("nodeConfirmedFailed", { nodeId });
+      logger.error({ nodeId }, "Node failure confirmed");
+    }
+    this.confirmationTimers.delete(nodeId);
+  }
+  /**
+   * Calculate the phi value for a node using the Phi Accrual algorithm.
+   *
+   * Phi = -log10(P_later(t_now - t_last))
+   *
+   * where P_later is the probability that a heartbeat will arrive later than expected.
+   */
+  calculatePhi(nodeId) {
+    const state = this.nodeStates.get(nodeId);
+    if (!state) return 0;
+    const now = Date.now();
+    const timeSinceLastHeartbeat = now - state.lastHeartbeat;
+    if (state.intervalHistory.length < this.config.minSamples) {
+      const expectedInterval = this.config.initialHeartbeatIntervalMs;
+      return timeSinceLastHeartbeat / expectedInterval;
+    }
+    const mean = this.calculateMean(state.intervalHistory);
+    const variance = this.calculateVariance(state.intervalHistory, mean);
+    const stdDev = Math.sqrt(variance);
+    if (timeSinceLastHeartbeat <= mean) {
+      return 0;
+    }
+    const deviations = stdDev > 0 ? (timeSinceLastHeartbeat - mean) / stdDev : 0;
+    const phi = Math.max(0, deviations);
+    return phi;
+  }
+  /**
+   * Calculate mean of an array of numbers.
+   */
+  calculateMean(values) {
+    if (values.length === 0) return 0;
+    return values.reduce((sum, v) => sum + v, 0) / values.length;
+  }
+  /**
+   * Calculate variance of an array of numbers.
+   */
+  calculateVariance(values, mean) {
+    if (values.length < 2) return 0;
+    return values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length;
+  }
+  /**
+   * Get list of currently suspected nodes.
+   */
+  getSuspectedNodes() {
+    const suspected = [];
+    for (const [nodeId, state] of this.nodeStates) {
+      if (state.isSuspected) {
+        suspected.push(nodeId);
+      }
+    }
+    return suspected;
+  }
+  /**
+   * Get list of confirmed failed nodes.
+   */
+  getConfirmedFailedNodes() {
+    const failed = [];
+    for (const [nodeId, state] of this.nodeStates) {
+      if (state.isConfirmedFailed) {
+        failed.push(nodeId);
+      }
+    }
+    return failed;
+  }
+  /**
+   * Check if a specific node is suspected.
+   */
+  isSuspected(nodeId) {
+    return this.nodeStates.get(nodeId)?.isSuspected ?? false;
+  }
+  /**
+   * Check if a specific node's failure is confirmed.
+   */
+  isConfirmedFailed(nodeId) {
+    return this.nodeStates.get(nodeId)?.isConfirmedFailed ?? false;
+  }
+  /**
+   * Get the current phi value for a node.
+   */
+  getPhi(nodeId) {
+    return this.calculatePhi(nodeId);
+  }
+  /**
+   * Get all monitored nodes.
+   */
+  getMonitoredNodes() {
+    return Array.from(this.monitoringNodes);
+  }
+  /**
+   * Get metrics for monitoring.
+   */
+  getMetrics() {
+    let suspectedCount = 0;
+    let confirmedCount = 0;
+    for (const state of this.nodeStates.values()) {
+      if (state.isSuspected) suspectedCount++;
+      if (state.isConfirmedFailed) confirmedCount++;
+    }
+    return {
+      monitoredNodes: this.monitoringNodes.size,
+      suspectedNodes: suspectedCount,
+      confirmedFailedNodes: confirmedCount
+    };
+  }
+};
+
+// src/cluster/ClusterManager.ts
+var ClusterManager = class extends import_events2.EventEmitter {
   constructor(config) {
     super();
     this.members = /* @__PURE__ */ new Map();
@@ -645,6 +911,30 @@ var ClusterManager = class extends import_events.EventEmitter {
     this.reconnectIntervals = /* @__PURE__ */ new Map();
     this._actualPort = 0;
     this.config = config;
+    this.failureDetector = new FailureDetector({
+      ...DEFAULT_FAILURE_DETECTOR_CONFIG,
+      heartbeatIntervalMs: config.heartbeatIntervalMs ?? 1e3,
+      ...config.failureDetection
+    });
+    this.failureDetector.on("nodeSuspected", (event) => {
+      logger.warn({ nodeId: event.nodeId, phi: event.phi }, "Node suspected (failure detector)");
+      this.emit("nodeSuspected", event.nodeId, event.phi);
+    });
+    this.failureDetector.on("nodeRecovered", (event) => {
+      logger.info({ nodeId: event.nodeId }, "Node recovered (failure detector)");
+      this.emit("nodeRecovered", event.nodeId);
+    });
+    this.failureDetector.on("nodeConfirmedFailed", (event) => {
+      logger.error({ nodeId: event.nodeId }, "Node failure confirmed");
+      this.emit("nodeConfirmedFailed", event.nodeId);
+      this.handleNodeFailure(event.nodeId);
+    });
+  }
+  /**
+   * Get the failure detector instance.
+   */
+  getFailureDetector() {
+    return this.failureDetector;
   }
   /** Get the actual port the cluster is listening on */
   get port() {
@@ -696,6 +986,8 @@ var ClusterManager = class extends import_events.EventEmitter {
   }
   stop() {
     logger.info({ port: this.config.port }, "Stopping Cluster Manager");
+    this.stopHeartbeat();
+    this.failureDetector.stop();
     for (const timeout of this.reconnectIntervals.values()) {
       clearTimeout(timeout);
     }
@@ -715,6 +1007,61 @@ var ClusterManager = class extends import_events.EventEmitter {
       this.server.close();
     }
   }
+  /**
+   * Start sending heartbeats to all peers.
+   */
+  startHeartbeat() {
+    if (this.heartbeatTimer) return;
+    const intervalMs = this.config.heartbeatIntervalMs ?? 1e3;
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeatToAll();
+    }, intervalMs);
+    this.failureDetector.start();
+    logger.debug({ intervalMs }, "Heartbeat started");
+  }
+  /**
+   * Stop sending heartbeats.
+   */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+  }
+  /**
+   * Send heartbeat to all connected peers.
+   */
+  sendHeartbeatToAll() {
+    for (const [nodeId, member] of this.members) {
+      if (member.isSelf) continue;
+      if (member.socket && member.socket.readyState === import_ws.WebSocket.OPEN) {
+        this.send(nodeId, "HEARTBEAT", { timestamp: Date.now() });
+      }
+    }
+  }
+  /**
+   * Handle incoming heartbeat from a peer.
+   */
+  handleHeartbeat(senderId, _payload) {
+    this.failureDetector.recordHeartbeat(senderId);
+  }
+  /**
+   * Handle confirmed node failure.
+   */
+  handleNodeFailure(nodeId) {
+    const member = this.members.get(nodeId);
+    if (!member) return;
+    logger.warn({ nodeId }, "Removing failed node from cluster");
+    if (member.socket && member.socket.readyState !== import_ws.WebSocket.CLOSED) {
+      try {
+        member.socket.terminate();
+      } catch (e) {
+      }
+    }
+    this.members.delete(nodeId);
+    this.failureDetector.stopMonitoring(nodeId);
+    this.emit("memberLeft", nodeId);
+  }
   connectToPeers() {
     for (const peer of this.config.peers) {
       this.connectToPeer(peer);
@@ -833,7 +1180,13 @@ var ClusterManager = class extends import_events.EventEmitter {
             socket: ws,
             isSelf: false
           });
+          this.failureDetector.startMonitoring(remoteNodeId);
+          this.startHeartbeat();
           this.emit("memberJoined", remoteNodeId);
+        } else if (msg.type === "HEARTBEAT") {
+          if (remoteNodeId) {
+            this.handleHeartbeat(remoteNodeId, msg.payload);
+          }
         } else {
           this.emit("message", msg);
         }
@@ -847,6 +1200,7 @@ var ClusterManager = class extends import_events.EventEmitter {
         if (current && current.socket === ws) {
           logger.info({ nodeId: remoteNodeId }, "Peer disconnected");
           this.members.delete(remoteNodeId);
+          this.failureDetector.stopMonitoring(remoteNodeId);
           this.emit("memberLeft", remoteNodeId);
           if (initiated && peerAddress) {
             this.scheduleReconnect(peerAddress, 0);
@@ -900,21 +1254,639 @@ var ClusterManager = class extends import_events.EventEmitter {
 };
 
 // src/cluster/PartitionService.ts
+var import_events4 = require("events");
+
+// src/cluster/MigrationManager.ts
+var import_events3 = require("events");
 var import_core3 = require("@topgunbuild/core");
-var PartitionService = class {
-  // Standard Hazelcast default
-  constructor(cluster) {
+var import_native = require("@topgunbuild/native");
+var MigrationManager = class extends import_events3.EventEmitter {
+  constructor(clusterManager, partitionService, config = {}) {
+    super();
+    // Active outgoing migrations (this node is source)
+    this.activeMigrations = /* @__PURE__ */ new Map();
+    // Queue of migrations to process
+    this.migrationQueue = [];
+    // Incoming migrations (this node is target)
+    this.incomingMigrations = /* @__PURE__ */ new Map();
+    // Pending chunk acknowledgments
+    this.pendingChunkAcks = /* @__PURE__ */ new Map();
+    // Pending verification results
+    this.pendingVerifications = /* @__PURE__ */ new Map();
+    // Metrics tracking
+    this.metrics = {
+      migrationsStarted: 0,
+      migrationsCompleted: 0,
+      migrationsFailed: 0,
+      chunksTransferred: 0,
+      bytesTransferred: 0,
+      activeMigrations: 0,
+      queuedMigrations: 0
+    };
+    // Batch processing timer
+    this.batchTimer = null;
+    // Data collection callback (injected from ServerCoordinator)
+    this.dataCollector = null;
+    // Data storage callback (injected from ServerCoordinator)
+    this.dataStorer = null;
+    this.clusterManager = clusterManager;
+    this.partitionService = partitionService;
+    this.config = {
+      ...import_core3.DEFAULT_MIGRATION_CONFIG,
+      ...config
+    };
+    this.setupMessageHandlers();
+  }
+  // ============================================
+  // Configuration
+  // ============================================
+  /**
+   * Set the data collector callback
+   * Called to collect all records for a partition before migration
+   */
+  setDataCollector(collector) {
+    this.dataCollector = collector;
+  }
+  /**
+   * Set the data storer callback
+   * Called to store received records after successful migration
+   */
+  setDataStorer(storer) {
+    this.dataStorer = storer;
+  }
+  // ============================================
+  // Migration Planning
+  // ============================================
+  /**
+   * Plan migration for topology change
+   */
+  planMigration(oldDistribution, newDistribution) {
+    const migrations = [];
+    for (const [partitionId, newDist] of newDistribution) {
+      const oldDist = oldDistribution.get(partitionId);
+      const oldOwner = oldDist?.owner ?? this.clusterManager.config.nodeId;
+      const newOwner = newDist.owner;
+      if (oldOwner !== newOwner && oldOwner === this.clusterManager.config.nodeId) {
+        migrations.push({
+          partitionId,
+          state: import_core3.PartitionState.STABLE,
+          sourceNode: oldOwner,
+          targetNode: newOwner,
+          startTime: 0,
+          bytesTransferred: 0,
+          totalBytes: 0,
+          retryCount: 0
+        });
+      }
+    }
+    migrations.sort((a, b) => a.partitionId - b.partitionId);
+    this.migrationQueue = migrations;
+    this.metrics.queuedMigrations = migrations.length;
+    logger.info({ total: migrations.length }, "Migration planned");
+    this.emit("migrationPlanned", { total: migrations.length });
+    if (migrations.length > 0) {
+      this.startBatchProcessing();
+    }
+  }
+  /**
+   * Start batch processing timer
+   */
+  startBatchProcessing() {
+    if (this.batchTimer) return;
+    this.startNextBatch().catch((err) => {
+      logger.error({ error: err }, "Failed to start first migration batch");
+      this.emit("error", err);
+    });
+    this.batchTimer = setInterval(() => {
+      this.startNextBatch().catch((err) => {
+        logger.error({ error: err }, "Failed to start migration batch");
+        this.emit("error", err);
+      });
+    }, this.config.batchIntervalMs);
+  }
+  /**
+   * Stop batch processing
+   */
+  stopBatchProcessing() {
+    if (this.batchTimer) {
+      clearInterval(this.batchTimer);
+      this.batchTimer = null;
+    }
+  }
+  /**
+   * Start next batch of migrations
+   */
+  async startNextBatch() {
+    if (this.activeMigrations.size >= this.config.parallelTransfers) {
+      return;
+    }
+    const slotsAvailable = this.config.parallelTransfers - this.activeMigrations.size;
+    const batch = this.migrationQueue.splice(0, Math.min(slotsAvailable, this.config.batchSize));
+    if (batch.length === 0) {
+      if (this.migrationQueue.length === 0 && this.activeMigrations.size === 0) {
+        this.stopBatchProcessing();
+      }
+      return;
+    }
+    for (const migration of batch) {
+      migration.state = import_core3.PartitionState.MIGRATING;
+      migration.startTime = Date.now();
+      this.activeMigrations.set(migration.partitionId, migration);
+      this.metrics.migrationsStarted++;
+      this.metrics.activeMigrations = this.activeMigrations.size;
+      this.metrics.queuedMigrations = this.migrationQueue.length;
+      this.startPartitionMigration(migration).catch((error) => {
+        this.onMigrationFailed(migration.partitionId, error);
+      });
+    }
+    logger.info({ count: batch.length, remaining: this.migrationQueue.length }, "Batch started");
+    this.emit("batchStarted", { count: batch.length, remaining: this.migrationQueue.length });
+  }
+  // ============================================
+  // Migration Execution
+  // ============================================
+  /**
+   * Start migration for a single partition
+   */
+  async startPartitionMigration(migration) {
+    const { partitionId, targetNode } = migration;
+    logger.info({ partitionId, targetNode }, "Starting partition migration");
+    let records;
+    if (this.dataCollector) {
+      records = await this.dataCollector(partitionId);
+    } else {
+      records = [];
+    }
+    migration.totalBytes = records.reduce((sum, r) => sum + r.length, 0);
+    this.clusterManager.send(targetNode, "OP_FORWARD", {
+      _migration: {
+        type: "MIGRATION_START",
+        payload: {
+          partitionId,
+          sourceNode: this.clusterManager.config.nodeId,
+          estimatedSize: migration.totalBytes
+        }
+      }
+    });
+    const chunks = this.chunkify(records);
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
+      const checksum = this.calculateChecksum(chunk);
+      this.clusterManager.send(targetNode, "OP_FORWARD", {
+        _migration: {
+          type: "MIGRATION_CHUNK",
+          payload: {
+            partitionId,
+            chunkIndex: i,
+            totalChunks: chunks.length,
+            data: Array.from(chunk),
+            // Convert Uint8Array to array for JSON serialization
+            checksum
+          }
+        }
+      });
+      await this.waitForChunkAck(partitionId, i);
+      migration.bytesTransferred += chunk.length;
+      this.metrics.chunksTransferred++;
+      this.metrics.bytesTransferred += chunk.length;
+      this.emit("migrationProgress", migration);
+    }
+    const fullChecksum = this.calculatePartitionChecksum(records);
+    migration.state = import_core3.PartitionState.SYNC;
+    this.clusterManager.send(targetNode, "OP_FORWARD", {
+      _migration: {
+        type: "MIGRATION_COMPLETE",
+        payload: {
+          partitionId,
+          totalRecords: records.length,
+          checksum: fullChecksum
+        }
+      }
+    });
+    const verified = await this.waitForVerification(partitionId);
+    if (verified) {
+      await this.onMigrationComplete(partitionId);
+    } else {
+      throw new Error(`Migration verification failed for partition ${partitionId}`);
+    }
+  }
+  /**
+   * Split records into chunks
+   */
+  chunkify(records) {
+    const chunks = [];
+    let currentChunk = [];
+    let currentSize = 0;
+    for (const record of records) {
+      const lengthPrefix = new Uint8Array(4);
+      new DataView(lengthPrefix.buffer).setUint32(0, record.length, true);
+      currentChunk.push(...lengthPrefix, ...record);
+      currentSize += 4 + record.length;
+      if (currentSize >= this.config.transferChunkSize) {
+        chunks.push(new Uint8Array(currentChunk));
+        currentChunk = [];
+        currentSize = 0;
+      }
+    }
+    if (currentChunk.length > 0) {
+      chunks.push(new Uint8Array(currentChunk));
+    }
+    if (chunks.length === 0) {
+      chunks.push(new Uint8Array(0));
+    }
+    return chunks;
+  }
+  /**
+   * Calculate checksum for a chunk using native xxhash
+   */
+  calculateChecksum(data) {
+    return String((0, import_native.xxhash64AsNumber)(data));
+  }
+  /**
+   * Calculate checksum for all partition records using streaming xxhash
+   */
+  calculatePartitionChecksum(records) {
+    const state = (0, import_native.createXxHash64State)();
+    for (const record of records) {
+      state.update(record);
+    }
+    return String(state.digestAsNumber());
+  }
+  /**
+   * Wait for chunk acknowledgment
+   */
+  waitForChunkAck(partitionId, chunkIndex) {
+    return new Promise((resolve, reject) => {
+      const key = `${partitionId}:${chunkIndex}`;
+      const timeout = setTimeout(() => {
+        this.pendingChunkAcks.delete(key);
+        reject(new Error(`Chunk ack timeout for partition ${partitionId}, chunk ${chunkIndex}`));
+      }, this.config.syncTimeoutMs);
+      this.pendingChunkAcks.set(key, { resolve, reject, timeout });
+    });
+  }
+  /**
+   * Wait for migration verification
+   */
+  waitForVerification(partitionId) {
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        this.pendingVerifications.delete(partitionId);
+        resolve(false);
+      }, this.config.syncTimeoutMs);
+      this.pendingVerifications.set(partitionId, { resolve, timeout });
+    });
+  }
+  // ============================================
+  // Migration Completion
+  // ============================================
+  /**
+   * Handle successful migration completion
+   */
+  async onMigrationComplete(partitionId) {
+    const migration = this.activeMigrations.get(partitionId);
+    if (!migration) return;
+    migration.state = import_core3.PartitionState.STABLE;
+    this.activeMigrations.delete(partitionId);
+    this.metrics.migrationsCompleted++;
+    this.metrics.activeMigrations = this.activeMigrations.size;
+    logger.info({
+      partitionId,
+      duration: Date.now() - migration.startTime,
+      bytesTransferred: migration.bytesTransferred
+    }, "Migration completed");
+    this.emit("migrationComplete", partitionId);
+  }
+  /**
+   * Handle migration failure
+   */
+  async onMigrationFailed(partitionId, error) {
+    const migration = this.activeMigrations.get(partitionId);
+    if (!migration) return;
+    migration.retryCount++;
+    if (migration.retryCount <= this.config.maxRetries) {
+      migration.state = import_core3.PartitionState.STABLE;
+      migration.bytesTransferred = 0;
+      this.activeMigrations.delete(partitionId);
+      this.migrationQueue.unshift(migration);
+      this.metrics.queuedMigrations = this.migrationQueue.length;
+      this.metrics.activeMigrations = this.activeMigrations.size;
+      logger.warn({
+        partitionId,
+        retryCount: migration.retryCount,
+        error: error.message
+      }, "Migration failed, will retry");
+    } else {
+      migration.state = import_core3.PartitionState.FAILED;
+      this.activeMigrations.delete(partitionId);
+      this.metrics.migrationsFailed++;
+      this.metrics.activeMigrations = this.activeMigrations.size;
+      logger.error({
+        partitionId,
+        retryCount: migration.retryCount,
+        error: error.message
+      }, "Migration failed permanently");
+      this.emit("migrationFailed", partitionId, error);
+    }
+  }
+  // ============================================
+  // Incoming Migration Handlers (Target Node)
+  // ============================================
+  /**
+   * Handle MIGRATION_START message
+   */
+  handleMigrationStart(payload) {
+    const { partitionId, sourceNode, estimatedSize } = payload;
+    logger.info({ partitionId, sourceNode, estimatedSize }, "Receiving migration");
+    this.incomingMigrations.set(partitionId, {
+      sourceNode,
+      chunks: [],
+      expectedSize: estimatedSize,
+      receivedSize: 0,
+      startTime: Date.now()
+    });
+  }
+  /**
+   * Handle MIGRATION_CHUNK message
+   */
+  handleMigrationChunk(payload) {
+    const { partitionId, chunkIndex, data, checksum } = payload;
+    const incoming = this.incomingMigrations.get(partitionId);
+    if (!incoming) {
+      logger.warn({ partitionId, chunkIndex }, "Received chunk for unknown migration");
+      return;
+    }
+    const chunkData = new Uint8Array(data);
+    const actualChecksum = this.calculateChecksum(chunkData);
+    const success = actualChecksum === checksum;
+    if (success) {
+      incoming.chunks[chunkIndex] = chunkData;
+      incoming.receivedSize += chunkData.length;
+    } else {
+      logger.warn({ partitionId, chunkIndex, expected: checksum, actual: actualChecksum }, "Chunk checksum mismatch");
+    }
+    this.clusterManager.send(incoming.sourceNode, "OP_FORWARD", {
+      _migration: {
+        type: "MIGRATION_CHUNK_ACK",
+        payload: {
+          partitionId,
+          chunkIndex,
+          success
+        }
+      }
+    });
+  }
+  /**
+   * Handle MIGRATION_COMPLETE message
+   */
+  async handleMigrationComplete(payload) {
+    const { partitionId, totalRecords, checksum } = payload;
+    const incoming = this.incomingMigrations.get(partitionId);
+    if (!incoming) {
+      logger.warn({ partitionId }, "Received complete for unknown migration");
+      return;
+    }
+    const allData = this.reassemble(incoming.chunks);
+    const records = this.deserializeRecords(allData);
+    const actualChecksum = this.calculatePartitionChecksum(records);
+    const checksumMatch = actualChecksum === checksum;
+    const success = checksumMatch && records.length === totalRecords;
+    if (success && this.dataStorer) {
+      await this.dataStorer(partitionId, records);
+    }
+    logger.info({
+      partitionId,
+      duration: Date.now() - incoming.startTime,
+      records: records.length,
+      checksumMatch
+    }, "Migration received");
+    this.clusterManager.send(incoming.sourceNode, "OP_FORWARD", {
+      _migration: {
+        type: "MIGRATION_VERIFY",
+        payload: {
+          partitionId,
+          success,
+          checksumMatch
+        }
+      }
+    });
+    this.incomingMigrations.delete(partitionId);
+  }
+  /**
+   * Handle MIGRATION_CHUNK_ACK message
+   */
+  handleMigrationChunkAck(payload) {
+    const { partitionId, chunkIndex, success } = payload;
+    const key = `${partitionId}:${chunkIndex}`;
+    const pending = this.pendingChunkAcks.get(key);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pendingChunkAcks.delete(key);
+      if (success) {
+        pending.resolve();
+      } else {
+        pending.reject(new Error(`Chunk ${chunkIndex} rejected by target`));
+      }
+    }
+  }
+  /**
+   * Handle MIGRATION_VERIFY message
+   */
+  handleMigrationVerify(payload) {
+    const { partitionId, success } = payload;
+    const pending = this.pendingVerifications.get(partitionId);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pendingVerifications.delete(partitionId);
+      pending.resolve(success);
+    }
+  }
+  /**
+   * Reassemble chunks into continuous data
+   */
+  reassemble(chunks) {
+    const totalLength = chunks.reduce((sum, c) => sum + (c?.length ?? 0), 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      if (chunk) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+      }
+    }
+    return result;
+  }
+  /**
+   * Deserialize records from chunk data
+   */
+  deserializeRecords(data) {
+    const records = [];
+    let offset = 0;
+    while (offset < data.length) {
+      if (offset + 4 > data.length) break;
+      const length = new DataView(data.buffer, data.byteOffset + offset, 4).getUint32(0, true);
+      offset += 4;
+      if (offset + length > data.length) break;
+      records.push(data.slice(offset, offset + length));
+      offset += length;
+    }
+    return records;
+  }
+  // ============================================
+  // Message Handling
+  // ============================================
+  /**
+   * Setup cluster message handlers
+   */
+  setupMessageHandlers() {
+    this.clusterManager.on("message", (msg) => {
+      if (msg.payload?._migration) {
+        const migration = msg.payload._migration;
+        switch (migration.type) {
+          case "MIGRATION_START":
+            this.handleMigrationStart(migration.payload);
+            break;
+          case "MIGRATION_CHUNK":
+            this.handleMigrationChunk(migration.payload);
+            break;
+          case "MIGRATION_COMPLETE":
+            this.handleMigrationComplete(migration.payload).catch((err) => {
+              logger.error({ error: err }, "Error handling migration complete");
+            });
+            break;
+          case "MIGRATION_CHUNK_ACK":
+            this.handleMigrationChunkAck(migration.payload);
+            break;
+          case "MIGRATION_VERIFY":
+            this.handleMigrationVerify(migration.payload);
+            break;
+        }
+      }
+    });
+  }
+  // ============================================
+  // Status and Metrics
+  // ============================================
+  /**
+   * Check if a partition is currently migrating
+   */
+  isActive(partitionId) {
+    return this.activeMigrations.has(partitionId) || this.incomingMigrations.has(partitionId);
+  }
+  /**
+   * Get migration status
+   */
+  getStatus() {
+    const avgMigrationTime = this.metrics.migrationsCompleted > 0 ? Date.now() - (this.activeMigrations.values().next().value?.startTime ?? Date.now()) : 0;
+    const estimatedTimeRemainingMs = (this.migrationQueue.length + this.activeMigrations.size) * (avgMigrationTime || 1e3);
+    return {
+      inProgress: this.activeMigrations.size > 0 || this.migrationQueue.length > 0,
+      active: Array.from(this.activeMigrations.values()),
+      queued: this.migrationQueue.length,
+      completed: this.metrics.migrationsCompleted,
+      failed: this.metrics.migrationsFailed,
+      estimatedTimeRemainingMs
+    };
+  }
+  /**
+   * Get migration metrics
+   */
+  getMetrics() {
+    return { ...this.metrics };
+  }
+  /**
+   * Cancel all active and queued migrations
+   */
+  async cancelAll() {
+    this.stopBatchProcessing();
+    this.migrationQueue = [];
+    this.metrics.queuedMigrations = 0;
+    for (const [partitionId, migration] of this.activeMigrations) {
+      migration.state = import_core3.PartitionState.FAILED;
+      this.metrics.migrationsFailed++;
+      this.emit("migrationFailed", partitionId, new Error("Migration cancelled"));
+    }
+    this.activeMigrations.clear();
+    this.metrics.activeMigrations = 0;
+    for (const pending of this.pendingChunkAcks.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Migration cancelled"));
+    }
+    this.pendingChunkAcks.clear();
+    for (const pending of this.pendingVerifications.values()) {
+      clearTimeout(pending.timeout);
+      pending.resolve(false);
+    }
+    this.pendingVerifications.clear();
+    this.incomingMigrations.clear();
+    logger.info("All migrations cancelled");
+  }
+  /**
+   * Cleanup resources (sync version for backwards compatibility)
+   */
+  close() {
+    this.cancelAll();
+  }
+  /**
+   * Async cleanup - waits for cancellation to complete
+   */
+  async closeAsync() {
+    await this.cancelAll();
+    this.removeAllListeners();
+  }
+};
+
+// src/cluster/PartitionService.ts
+var import_core4 = require("@topgunbuild/core");
+var DEFAULT_PARTITION_SERVICE_CONFIG = {
+  gradualRebalancing: false,
+  migration: import_core4.DEFAULT_MIGRATION_CONFIG
+};
+var PartitionService = class extends import_events4.EventEmitter {
+  constructor(cluster, config = {}) {
+    super();
     // partitionId -> { owner, backups }
     this.partitions = /* @__PURE__ */ new Map();
-    this.PARTITION_COUNT = 271;
-    this.BACKUP_COUNT = 1;
+    this.PARTITION_COUNT = import_core4.PARTITION_COUNT;
+    this.BACKUP_COUNT = import_core4.DEFAULT_BACKUP_COUNT;
+    // Phase 4: Version tracking for partition map
+    this.mapVersion = 0;
+    this.lastRebalanceTime = 0;
+    this.migrationManager = null;
     this.cluster = cluster;
-    this.cluster.on("memberJoined", () => this.rebalance());
-    this.cluster.on("memberLeft", () => this.rebalance());
-    this.rebalance();
+    this.config = {
+      ...DEFAULT_PARTITION_SERVICE_CONFIG,
+      ...config
+    };
+    if (this.config.gradualRebalancing) {
+      this.migrationManager = new MigrationManager(
+        cluster,
+        this,
+        this.config.migration
+      );
+      this.migrationManager.on("migrationComplete", (partitionId) => {
+        logger.info({ partitionId }, "Migration completed, updating ownership");
+      });
+      this.migrationManager.on("migrationFailed", (partitionId, error) => {
+        logger.error({ partitionId, error: error.message }, "Migration failed");
+      });
+    }
+    this.cluster.on("memberJoined", (nodeId) => this.onMembershipChange("JOIN", nodeId));
+    this.cluster.on("memberLeft", (nodeId) => this.onMembershipChange("LEAVE", nodeId));
+    this.rebalance("REBALANCE");
+  }
+  /**
+   * Handle membership change
+   */
+  onMembershipChange(reason, nodeId) {
+    if (this.config.gradualRebalancing && this.migrationManager) {
+      this.rebalanceGradual(reason, nodeId);
+    } else {
+      this.rebalance(reason, nodeId);
+    }
   }
   getPartitionId(key) {
-    return Math.abs((0, import_core3.hashString)(key)) % this.PARTITION_COUNT;
+    return Math.abs((0, import_core4.hashString)(key)) % this.PARTITION_COUNT;
   }
   getDistribution(key) {
     const pId = this.getPartitionId(key);
@@ -936,12 +1908,78 @@ var PartitionService = class {
   isRelated(key) {
     return this.isLocalOwner(key) || this.isLocalBackup(key);
   }
-  rebalance() {
+  // ============================================
+  // Phase 4: Partition Map Methods
+  // ============================================
+  /**
+   * Get current partition map version
+   */
+  getMapVersion() {
+    return this.mapVersion;
+  }
+  /**
+   * Generate full PartitionMap for client consumption
+   */
+  getPartitionMap() {
+    const nodes = [];
+    const partitions = [];
+    for (const nodeId of this.cluster.getMembers()) {
+      const isSelf = nodeId === this.cluster.config.nodeId;
+      const host = isSelf ? this.cluster.config.host : "unknown";
+      const port = isSelf ? this.cluster.port : 0;
+      nodes.push({
+        nodeId,
+        endpoints: {
+          websocket: `ws://${host}:${port}`
+        },
+        status: "ACTIVE"
+      });
+    }
+    for (let i = 0; i < this.PARTITION_COUNT; i++) {
+      const dist = this.partitions.get(i);
+      if (dist) {
+        partitions.push({
+          partitionId: i,
+          ownerNodeId: dist.owner,
+          backupNodeIds: dist.backups
+        });
+      }
+    }
+    return {
+      version: this.mapVersion,
+      partitionCount: this.PARTITION_COUNT,
+      nodes,
+      partitions,
+      generatedAt: Date.now()
+    };
+  }
+  /**
+   * Get partition info by ID
+   */
+  getPartitionInfo(partitionId) {
+    const dist = this.partitions.get(partitionId);
+    if (!dist) return null;
+    return {
+      partitionId,
+      ownerNodeId: dist.owner,
+      backupNodeIds: dist.backups
+    };
+  }
+  /**
+   * Get owner node for a partition ID
+   */
+  getPartitionOwner(partitionId) {
+    const dist = this.partitions.get(partitionId);
+    return dist?.owner ?? null;
+  }
+  rebalance(reason = "REBALANCE", triggerNodeId) {
+    const oldPartitions = new Map(this.partitions);
     let allMembers = this.cluster.getMembers().sort();
     if (allMembers.length === 0) {
       allMembers = [this.cluster.config.nodeId];
     }
-    logger.info({ memberCount: allMembers.length, members: allMembers }, "Rebalancing partitions");
+    logger.info({ memberCount: allMembers.length, members: allMembers, reason }, "Rebalancing partitions");
+    const changes = [];
     for (let i = 0; i < this.PARTITION_COUNT; i++) {
       const ownerIndex = i % allMembers.length;
       const owner = allMembers[ownerIndex];
@@ -952,14 +1990,141 @@ var PartitionService = class {
           backups.push(allMembers[backupIndex]);
         }
       }
+      const oldDist = oldPartitions.get(i);
+      if (oldDist && oldDist.owner !== owner) {
+        changes.push({
+          partitionId: i,
+          previousOwner: oldDist.owner,
+          newOwner: owner,
+          reason
+        });
+      }
       this.partitions.set(i, { owner, backups });
     }
+    if (changes.length > 0 || this.mapVersion === 0) {
+      this.mapVersion++;
+      this.lastRebalanceTime = Date.now();
+      logger.info({
+        version: this.mapVersion,
+        changesCount: changes.length,
+        reason
+      }, "Partition map updated");
+      this.emit("rebalanced", this.getPartitionMap(), changes);
+    }
+  }
+  // ============================================
+  // Phase 4 Task 03: Gradual Rebalancing
+  // ============================================
+  /**
+   * Perform gradual rebalancing using MigrationManager
+   */
+  rebalanceGradual(reason, triggerNodeId) {
+    if (!this.migrationManager) {
+      this.rebalance(reason, triggerNodeId);
+      return;
+    }
+    const oldDistribution = new Map(this.partitions);
+    let allMembers = this.cluster.getMembers().sort();
+    if (allMembers.length === 0) {
+      allMembers = [this.cluster.config.nodeId];
+    }
+    const newDistribution = /* @__PURE__ */ new Map();
+    for (let i = 0; i < this.PARTITION_COUNT; i++) {
+      const ownerIndex = i % allMembers.length;
+      const owner = allMembers[ownerIndex];
+      const backups = [];
+      if (allMembers.length > 1) {
+        for (let b = 1; b <= this.BACKUP_COUNT; b++) {
+          const backupIndex = (ownerIndex + b) % allMembers.length;
+          backups.push(allMembers[backupIndex]);
+        }
+      }
+      newDistribution.set(i, { owner, backups });
+    }
+    logger.info({ memberCount: allMembers.length, reason, triggerNodeId }, "Planning gradual rebalance");
+    this.migrationManager.planMigration(oldDistribution, newDistribution);
+    for (const [partitionId, dist] of newDistribution) {
+      this.partitions.set(partitionId, dist);
+    }
+    this.mapVersion++;
+    this.lastRebalanceTime = Date.now();
+    const changes = [];
+    for (const [partitionId, newDist] of newDistribution) {
+      const oldDist = oldDistribution.get(partitionId);
+      if (oldDist && oldDist.owner !== newDist.owner) {
+        changes.push({
+          partitionId,
+          previousOwner: oldDist.owner,
+          newOwner: newDist.owner,
+          reason
+        });
+      }
+    }
+    this.emit("rebalanced", this.getPartitionMap(), changes);
+  }
+  /**
+   * Set partition owner (called after migration completes)
+   */
+  setOwner(partitionId, nodeId) {
+    const partition = this.partitions.get(partitionId);
+    if (!partition) return;
+    const previousOwner = partition.owner;
+    if (previousOwner === nodeId) return;
+    partition.owner = nodeId;
+    this.mapVersion++;
+    logger.info({ partitionId, previousOwner, newOwner: nodeId, version: this.mapVersion }, "Partition owner updated");
+    this.emit("partitionMoved", {
+      partitionId,
+      previousOwner,
+      newOwner: nodeId,
+      version: this.mapVersion
+    });
+  }
+  /**
+   * Get backups for a partition
+   */
+  getBackups(partitionId) {
+    const dist = this.partitions.get(partitionId);
+    return dist?.backups ?? [];
+  }
+  /**
+   * Get migration status
+   */
+  getMigrationStatus() {
+    return this.migrationManager?.getStatus() ?? null;
+  }
+  /**
+   * Check if partition is currently migrating
+   */
+  isMigrating(partitionId) {
+    return this.migrationManager?.isActive(partitionId) ?? false;
+  }
+  /**
+   * Check if any partition is currently migrating
+   */
+  isRebalancing() {
+    const status = this.getMigrationStatus();
+    return status?.inProgress ?? false;
+  }
+  /**
+   * Get MigrationManager for configuration
+   */
+  getMigrationManager() {
+    return this.migrationManager;
+  }
+  /**
+   * Cancel all migrations
+   */
+  async cancelMigrations() {
+    if (this.migrationManager) {
+      await this.migrationManager.cancelAll();
+    }
   }
 };
 
 // src/cluster/LockManager.ts
-var import_events2 = require("events");
-var _LockManager = class _LockManager extends import_events2.EventEmitter {
+var import_events5 = require("events");
+var _LockManager = class _LockManager extends import_events5.EventEmitter {
   // 5 minutes
   constructor() {
     super();
@@ -1474,8 +2639,8 @@ var SystemManager = class {
 };
 
 // src/utils/BoundedEventQueue.ts
-var import_events3 = require("events");
-var BoundedEventQueue = class extends import_events3.EventEmitter {
+var import_events6 = require("events");
+var BoundedEventQueue = class extends import_events6.EventEmitter {
   constructor(options) {
     super();
     this.queue = [];
@@ -1907,7 +3072,7 @@ var BackpressureRegulator = class {
 
 // src/utils/CoalescingWriter.ts
 var import_ws2 = require("ws");
-var import_core4 = require("@topgunbuild/core");
+var import_core5 = require("@topgunbuild/core");
 
 // src/memory/BufferPool.ts
 var DEFAULT_CONFIG2 = {
@@ -2438,7 +3603,7 @@ var CoalescingWriter = class {
     if (this.closed) {
       return;
     }
-    const data = (0, import_core4.serialize)(message);
+    const data = (0, import_core5.serialize)(message);
     this.writeRaw(data, urgent);
   }
   /**
@@ -2622,7 +3787,7 @@ var CoalescingWriter = class {
       offset += msg.data.length;
     }
     const usedBatch = batch.subarray(0, totalSize);
-    const batchEnvelope = (0, import_core4.serialize)({
+    const batchEnvelope = (0, import_core5.serialize)({
       type: "BATCH",
       count: messages.length,
       data: usedBatch
@@ -2637,13 +3802,23 @@ var CoalescingWriter = class {
 // src/utils/coalescingPresets.ts
 var coalescingPresets = {
   /**
-   * Conservative defaults - good for low-latency workloads.
-   * Minimizes batching delay at the cost of more network calls.
-   * Use for: gaming, real-time chat, interactive applications.
+   * Low latency - optimized for minimal response time.
+   * Best for: gaming, real-time chat, interactive applications.
+   * Benchmark: p50=2ms, ~18K ops/sec
+   */
+  lowLatency: {
+    maxBatchSize: 100,
+    maxDelayMs: 1,
+    maxBatchBytes: 65536
+    // 64KB
+  },
+  /**
+   * Conservative - good balance of latency and batching.
+   * Use for: general purpose with latency sensitivity.
    */
   conservative: {
     maxBatchSize: 100,
-    maxDelayMs: 5,
+    maxDelayMs: 2,
     maxBatchBytes: 65536
     // 64KB
   },
@@ -2654,7 +3829,7 @@ var coalescingPresets = {
    */
   balanced: {
     maxBatchSize: 300,
-    maxDelayMs: 8,
+    maxDelayMs: 2,
     maxBatchBytes: 131072
     // 128KB
   },
@@ -2662,10 +3837,11 @@ var coalescingPresets = {
    * High throughput - optimized for write-heavy workloads.
    * Higher batching for better network utilization.
    * Use for: data ingestion, logging, IoT data streams.
+   * Benchmark: p50=7ms, ~18K ops/sec
    */
   highThroughput: {
     maxBatchSize: 500,
-    maxDelayMs: 10,
+    maxDelayMs: 2,
     maxBatchBytes: 262144
     // 256KB
   },
@@ -2676,7 +3852,7 @@ var coalescingPresets = {
    */
   aggressive: {
     maxBatchSize: 1e3,
-    maxDelayMs: 15,
+    maxDelayMs: 5,
     maxBatchBytes: 524288
     // 512KB
   }
@@ -3207,6 +4383,7 @@ var WorkerPool = class {
 
 // src/workers/MerkleWorker.ts
 var import_path2 = require("path");
+var import_core6 = require("@topgunbuild/core");
 var WORKER_THRESHOLD = 10;
 var taskIdCounter = 0;
 function generateTaskId() {
@@ -3416,12 +4593,7 @@ var MerkleWorker = class {
   }
   // ============ Hash utilities ============
   hashString(str) {
-    let hash = 2166136261;
-    for (let i = 0; i < str.length; i++) {
-      hash ^= str.charCodeAt(i);
-      hash = Math.imul(hash, 16777619);
-    }
-    return hash >>> 0;
+    return (0, import_core6.hashString)(str);
   }
   buildTree(entries, depth) {
     const root = { hash: 0, children: {} };
@@ -3648,7 +4820,7 @@ CRDTMergeWorker.BATCH_THRESHOLD = WORKER_THRESHOLD2;
 
 // src/workers/SerializationWorker.ts
 var import_path3 = require("path");
-var import_core5 = require("@topgunbuild/core");
+var import_core7 = require("@topgunbuild/core");
 var WORKER_BATCH_THRESHOLD = 10;
 var WORKER_SIZE_THRESHOLD = 50 * 1024;
 var taskIdCounter3 = 0;
@@ -3775,26 +4947,26 @@ var SerializationWorker = class {
    * Serialize a single object (always inline, too small for worker)
    */
   serialize(data) {
-    return (0, import_core5.serialize)(data);
+    return (0, import_core7.serialize)(data);
   }
   /**
    * Deserialize a single payload (always inline, too small for worker)
    */
   deserialize(data) {
-    return (0, import_core5.deserialize)(data);
+    return (0, import_core7.deserialize)(data);
   }
   // ============ Inline implementations for small batches ============
   serializeBatchInline(items) {
     const results = [];
     for (const item of items) {
-      results.push((0, import_core5.serialize)(item));
+      results.push((0, import_core7.serialize)(item));
     }
     return results;
   }
   deserializeBatchInline(items) {
     const results = [];
     for (const item of items) {
-      results.push((0, import_core5.deserialize)(item));
+      results.push((0, import_core7.deserialize)(item));
     }
     return results;
   }
@@ -4382,13 +5554,13 @@ var ReduceTasklet = class extends IteratorTasklet {
 };
 
 // src/ack/WriteAckManager.ts
-var import_events4 = require("events");
-var import_core6 = require("@topgunbuild/core");
-var WriteAckManager = class extends import_events4.EventEmitter {
+var import_events7 = require("events");
+var import_core8 = require("@topgunbuild/core");
+var WriteAckManager = class extends import_events7.EventEmitter {
   constructor(config) {
     super();
     this.pending = /* @__PURE__ */ new Map();
-    this.defaultTimeout = config?.defaultTimeout ?? import_core6.DEFAULT_WRITE_CONCERN_TIMEOUT;
+    this.defaultTimeout = config?.defaultTimeout ?? import_core8.DEFAULT_WRITE_CONCERN_TIMEOUT;
   }
   /**
    * Register a pending write operation.
@@ -4400,11 +5572,11 @@ var WriteAckManager = class extends import_events4.EventEmitter {
    * @returns Promise that resolves with WriteResult
    */
   registerPending(opId, writeConcern, timeout) {
-    if (writeConcern === import_core6.WriteConcern.FIRE_AND_FORGET) {
+    if (writeConcern === import_core8.WriteConcern.FIRE_AND_FORGET) {
       return Promise.resolve({
         success: true,
         opId,
-        achievedLevel: import_core6.WriteConcern.FIRE_AND_FORGET,
+        achievedLevel: import_core8.WriteConcern.FIRE_AND_FORGET,
         latencyMs: 0
       });
     }
@@ -4418,7 +5590,7 @@ var WriteAckManager = class extends import_events4.EventEmitter {
         timeout: effectiveTimeout,
         resolve,
         reject,
-        achievedLevels: /* @__PURE__ */ new Set([import_core6.WriteConcern.FIRE_AND_FORGET])
+        achievedLevels: /* @__PURE__ */ new Set([import_core8.WriteConcern.FIRE_AND_FORGET])
       };
       pendingWrite.timeoutHandle = setTimeout(() => {
         this.handleTimeout(opId);
@@ -4428,8 +5600,8 @@ var WriteAckManager = class extends import_events4.EventEmitter {
         { opId, writeConcern, timeout: effectiveTimeout },
         "Registered pending write"
       );
-      if (writeConcern === import_core6.WriteConcern.MEMORY) {
-        this.notifyLevel(opId, import_core6.WriteConcern.MEMORY);
+      if (writeConcern === import_core8.WriteConcern.MEMORY) {
+        this.notifyLevel(opId, import_core8.WriteConcern.MEMORY);
       }
     });
   }
@@ -4449,7 +5621,7 @@ var WriteAckManager = class extends import_events4.EventEmitter {
       { opId, level, target: pending.writeConcern },
       "Write Concern level achieved"
     );
-    if ((0, import_core6.isWriteConcernAchieved)(pending.achievedLevels, pending.writeConcern)) {
+    if ((0, import_core8.isWriteConcernAchieved)(pending.achievedLevels, pending.writeConcern)) {
       this.resolvePending(opId, level);
     }
   }
@@ -4492,7 +5664,7 @@ var WriteAckManager = class extends import_events4.EventEmitter {
   getAchievedLevel(opId) {
     const pending = this.pending.get(opId);
     if (!pending) return void 0;
-    return (0, import_core6.getHighestWriteConcernLevel)(pending.achievedLevels);
+    return (0, import_core8.getHighestWriteConcernLevel)(pending.achievedLevels);
   }
   /**
    * Resolve a pending write with success.
@@ -4524,7 +5696,7 @@ var WriteAckManager = class extends import_events4.EventEmitter {
   handleTimeout(opId) {
     const pending = this.pending.get(opId);
     if (!pending) return;
-    const highestAchieved = (0, import_core6.getHighestWriteConcernLevel)(pending.achievedLevels);
+    const highestAchieved = (0, import_core8.getHighestWriteConcernLevel)(pending.achievedLevels);
     const latencyMs = Date.now() - pending.timestamp;
     const result = {
       success: false,
@@ -4552,89 +5724,747 @@ var WriteAckManager = class extends import_events4.EventEmitter {
    * @param opId - Operation ID
    * @param error - Error message
    */
-  failPending(opId, error) {
-    const pending = this.pending.get(opId);
+  failPending(opId, error) {
+    const pending = this.pending.get(opId);
+    if (!pending) return;
+    if (pending.timeoutHandle) {
+      clearTimeout(pending.timeoutHandle);
+    }
+    const latencyMs = Date.now() - pending.timestamp;
+    const highestAchieved = (0, import_core8.getHighestWriteConcernLevel)(pending.achievedLevels);
+    const result = {
+      success: false,
+      opId,
+      achievedLevel: highestAchieved,
+      latencyMs,
+      error
+    };
+    pending.resolve(result);
+    this.pending.delete(opId);
+    logger.error({ opId, error, latencyMs }, "Write failed");
+    this.emit("failed", result);
+  }
+  /**
+   * Get pending writes statistics.
+   */
+  getStats() {
+    const byLevel = {
+      [import_core8.WriteConcern.FIRE_AND_FORGET]: 0,
+      [import_core8.WriteConcern.MEMORY]: 0,
+      [import_core8.WriteConcern.APPLIED]: 0,
+      [import_core8.WriteConcern.REPLICATED]: 0,
+      [import_core8.WriteConcern.PERSISTED]: 0
+    };
+    for (const pending of this.pending.values()) {
+      byLevel[pending.writeConcern]++;
+    }
+    return { pending: this.pending.size, byLevel };
+  }
+  /**
+   * Get all pending operation IDs.
+   */
+  getPendingIds() {
+    return Array.from(this.pending.keys());
+  }
+  /**
+   * Clear all pending writes (for shutdown).
+   * Rejects all pending promises with an error.
+   */
+  clear() {
+    const count = this.pending.size;
+    for (const pending of this.pending.values()) {
+      if (pending.timeoutHandle) {
+        clearTimeout(pending.timeoutHandle);
+      }
+      pending.reject(new Error("WriteAckManager cleared"));
+    }
+    this.pending.clear();
+    if (count > 0) {
+      logger.info({ count }, "WriteAckManager cleared");
+    }
+  }
+  /**
+   * Graceful shutdown - resolves all pending writes with their current achieved level.
+   */
+  shutdown() {
+    const count = this.pending.size;
+    for (const [opId, pending] of this.pending.entries()) {
+      if (pending.timeoutHandle) {
+        clearTimeout(pending.timeoutHandle);
+      }
+      const highestAchieved = (0, import_core8.getHighestWriteConcernLevel)(pending.achievedLevels);
+      const latencyMs = Date.now() - pending.timestamp;
+      const result = {
+        success: highestAchieved === pending.writeConcern,
+        opId,
+        achievedLevel: highestAchieved,
+        latencyMs,
+        error: highestAchieved !== pending.writeConcern ? `Shutdown: achieved ${highestAchieved}, requested ${pending.writeConcern}` : void 0
+      };
+      pending.resolve(result);
+    }
+    this.pending.clear();
+    if (count > 0) {
+      logger.info({ count }, "WriteAckManager shutdown");
+    }
+  }
+};
+
+// src/cluster/ReplicationPipeline.ts
+var import_events8 = require("events");
+var import_core9 = require("@topgunbuild/core");
+
+// src/cluster/LagTracker.ts
+var DEFAULT_LAG_TRACKER_CONFIG = {
+  historySize: 100,
+  laggyThresholdMs: 5e3,
+  unhealthyThresholdMs: 3e4
+};
+var LagTracker = class {
+  constructor(config = {}) {
+    this.lagByNode = /* @__PURE__ */ new Map();
+    this.config = {
+      ...DEFAULT_LAG_TRACKER_CONFIG,
+      ...config
+    };
+  }
+  /**
+   * Update lag measurement for a node
+   */
+  update(nodeId, lagMs) {
+    let info = this.lagByNode.get(nodeId);
+    if (!info) {
+      info = {
+        current: 0,
+        history: [],
+        lastUpdate: Date.now(),
+        pendingOps: 0
+      };
+      this.lagByNode.set(nodeId, info);
+    }
+    info.current = lagMs;
+    info.history.push(lagMs);
+    if (info.history.length > this.config.historySize) {
+      info.history.shift();
+    }
+    info.lastUpdate = Date.now();
+  }
+  /**
+   * Record acknowledgment from a node (lag effectively becomes 0)
+   */
+  recordAck(nodeId) {
+    const info = this.lagByNode.get(nodeId);
+    if (info) {
+      info.current = 0;
+      info.lastUpdate = Date.now();
+      if (info.pendingOps > 0) {
+        info.pendingOps--;
+      }
+    }
+  }
+  /**
+   * Increment pending operations counter for a node
+   */
+  incrementPending(nodeId) {
+    let info = this.lagByNode.get(nodeId);
+    if (!info) {
+      info = {
+        current: 0,
+        history: [],
+        lastUpdate: Date.now(),
+        pendingOps: 0
+      };
+      this.lagByNode.set(nodeId, info);
+    }
+    info.pendingOps++;
+  }
+  /**
+   * Get lag statistics for a specific node
+   */
+  getLag(nodeId) {
+    const info = this.lagByNode.get(nodeId);
+    if (!info || info.history.length === 0) {
+      return { current: 0, avg: 0, max: 0, percentile99: 0 };
+    }
+    const sorted = [...info.history].sort((a, b) => a - b);
+    const avg = sorted.reduce((a, b) => a + b, 0) / sorted.length;
+    const max = sorted[sorted.length - 1] || 0;
+    const p99Index = Math.floor(sorted.length * 0.99);
+    const percentile99 = sorted[p99Index] || max;
+    return {
+      current: info.current,
+      avg: Math.round(avg * 100) / 100,
+      // Round to 2 decimal places
+      max,
+      percentile99
+    };
+  }
+  /**
+   * Get pending operations count for a node
+   */
+  getPendingOps(nodeId) {
+    const info = this.lagByNode.get(nodeId);
+    return info?.pendingOps ?? 0;
+  }
+  /**
+   * Get overall replication health status
+   */
+  getHealth() {
+    const unhealthyNodes = [];
+    const laggyNodes = [];
+    let totalLag = 0;
+    let nodeCount = 0;
+    const now = Date.now();
+    for (const [nodeId, info] of this.lagByNode) {
+      const timeSinceUpdate = now - info.lastUpdate;
+      if (timeSinceUpdate > this.config.unhealthyThresholdMs) {
+        unhealthyNodes.push(nodeId);
+      } else if (info.current > this.config.laggyThresholdMs) {
+        laggyNodes.push(nodeId);
+      }
+      totalLag += info.current;
+      nodeCount++;
+    }
+    const avgLagMs = nodeCount > 0 ? totalLag / nodeCount : 0;
+    return {
+      healthy: unhealthyNodes.length === 0,
+      unhealthyNodes,
+      laggyNodes,
+      avgLagMs: Math.round(avgLagMs * 100) / 100
+    };
+  }
+  /**
+   * Get average lag across all tracked nodes
+   */
+  getAverageLag() {
+    let total = 0;
+    let count = 0;
+    for (const info of this.lagByNode.values()) {
+      total += info.current;
+      count++;
+    }
+    return count > 0 ? total / count : 0;
+  }
+  /**
+   * Check if a specific node is considered healthy
+   */
+  isNodeHealthy(nodeId) {
+    const info = this.lagByNode.get(nodeId);
+    if (!info) return true;
+    const timeSinceUpdate = Date.now() - info.lastUpdate;
+    return timeSinceUpdate < this.config.unhealthyThresholdMs;
+  }
+  /**
+   * Check if a specific node is considered laggy
+   */
+  isNodeLaggy(nodeId) {
+    const info = this.lagByNode.get(nodeId);
+    if (!info) return false;
+    return info.current > this.config.laggyThresholdMs;
+  }
+  /**
+   * Remove a node from tracking
+   */
+  removeNode(nodeId) {
+    this.lagByNode.delete(nodeId);
+  }
+  /**
+   * Get all tracked node IDs
+   */
+  getTrackedNodes() {
+    return Array.from(this.lagByNode.keys());
+  }
+  /**
+   * Get raw lag info for a node (for advanced monitoring)
+   */
+  getRawLagInfo(nodeId) {
+    return this.lagByNode.get(nodeId);
+  }
+  /**
+   * Clear all tracking data
+   */
+  clear() {
+    this.lagByNode.clear();
+  }
+  /**
+   * Export metrics in Prometheus format
+   */
+  toPrometheusMetrics() {
+    const lines = [
+      "# HELP topgun_replication_lag_ms Current replication lag in milliseconds",
+      "# TYPE topgun_replication_lag_ms gauge"
+    ];
+    for (const [nodeId, info] of this.lagByNode) {
+      lines.push(`topgun_replication_lag_ms{node="${nodeId}"} ${info.current}`);
+    }
+    lines.push("");
+    lines.push("# HELP topgun_replication_pending_ops Pending replication operations");
+    lines.push("# TYPE topgun_replication_pending_ops gauge");
+    for (const [nodeId, info] of this.lagByNode) {
+      lines.push(`topgun_replication_pending_ops{node="${nodeId}"} ${info.pendingOps}`);
+    }
+    const health = this.getHealth();
+    lines.push("");
+    lines.push("# HELP topgun_replication_healthy Cluster replication health (1=healthy, 0=unhealthy)");
+    lines.push("# TYPE topgun_replication_healthy gauge");
+    lines.push(`topgun_replication_healthy ${health.healthy ? 1 : 0}`);
+    lines.push("");
+    lines.push("# HELP topgun_replication_avg_lag_ms Average replication lag across all nodes");
+    lines.push("# TYPE topgun_replication_avg_lag_ms gauge");
+    lines.push(`topgun_replication_avg_lag_ms ${health.avgLagMs}`);
+    return lines.join("\n");
+  }
+};
+
+// src/cluster/ReplicationPipeline.ts
+var ReplicationTimeoutError = class extends Error {
+  constructor(opId, targetNodes, ackedNodes) {
+    super(
+      `Replication timeout for operation ${opId}. Expected: ${targetNodes.join(", ")}, Acked: ${ackedNodes.join(", ")}`
+    );
+    this.opId = opId;
+    this.targetNodes = targetNodes;
+    this.ackedNodes = ackedNodes;
+    this.name = "ReplicationTimeoutError";
+  }
+};
+var ReplicationPipeline = class extends import_events8.EventEmitter {
+  constructor(clusterManager, partitionService, config = {}) {
+    super();
+    // Replication queues per node (for EVENTUAL mode)
+    this.replicationQueue = /* @__PURE__ */ new Map();
+    // Pending acknowledgments (for STRONG/QUORUM mode)
+    this.pendingAcks = /* @__PURE__ */ new Map();
+    // Queue processor timer
+    this.queueProcessorTimer = null;
+    // Operation applier callback (injected by ServerCoordinator)
+    this.operationApplier = null;
+    this.clusterManager = clusterManager;
+    this.partitionService = partitionService;
+    this.nodeId = clusterManager.config.nodeId;
+    this.config = {
+      ...import_core9.DEFAULT_REPLICATION_CONFIG,
+      ...config
+    };
+    this.lagTracker = new LagTracker();
+    this.setupMessageHandlers();
+    this.startQueueProcessor();
+  }
+  // ============================================
+  // Configuration
+  // ============================================
+  /**
+   * Set the operation applier callback
+   * This is called when replicated operations are received from other nodes
+   */
+  setOperationApplier(applier) {
+    this.operationApplier = applier;
+  }
+  // ============================================
+  // Replication API
+  // ============================================
+  /**
+   * Replicate operation to backup nodes
+   */
+  async replicate(operation, opId, key, options = {}) {
+    const consistency = options.consistency ?? this.config.defaultConsistency;
+    const partitionId = this.partitionService.getPartitionId(key);
+    const backups = this.partitionService.getBackups(partitionId);
+    if (backups.length === 0) {
+      return { success: true, ackedBy: [this.nodeId] };
+    }
+    switch (consistency) {
+      case import_core9.ConsistencyLevel.STRONG:
+        return this.replicateStrong(operation, opId, backups, options.timeout);
+      case import_core9.ConsistencyLevel.QUORUM:
+        return this.replicateQuorum(operation, opId, backups, options.timeout);
+      case import_core9.ConsistencyLevel.EVENTUAL:
+        return this.replicateEventual(operation, opId, backups);
+    }
+  }
+  /**
+   * STRONG: Wait for all replicas to acknowledge
+   */
+  async replicateStrong(operation, opId, backups, timeout) {
+    const targetNodes = backups;
+    return new Promise((resolve, reject) => {
+      const pending = {
+        opId,
+        consistency: import_core9.ConsistencyLevel.STRONG,
+        targetNodes,
+        ackedNodes: /* @__PURE__ */ new Set(),
+        resolve: () => resolve({
+          success: true,
+          ackedBy: [this.nodeId, ...targetNodes]
+        }),
+        reject: (error) => reject(error),
+        timeout: setTimeout(() => {
+          this.pendingAcks.delete(opId);
+          const ackedList = Array.from(pending.ackedNodes);
+          reject(new ReplicationTimeoutError(opId, targetNodes, ackedList));
+        }, timeout ?? this.config.ackTimeoutMs),
+        startTime: Date.now()
+      };
+      this.pendingAcks.set(opId, pending);
+      for (const nodeId of targetNodes) {
+        this.lagTracker.incrementPending(nodeId);
+      }
+      for (const nodeId of targetNodes) {
+        this.sendReplication(nodeId, operation, opId, import_core9.ConsistencyLevel.STRONG);
+      }
+    });
+  }
+  /**
+   * QUORUM: Wait for majority of replicas
+   */
+  async replicateQuorum(operation, opId, backups, timeout) {
+    const targetNodes = backups;
+    const quorumSize = Math.floor(targetNodes.length / 2) + 1;
+    return new Promise((resolve, reject) => {
+      const ackedNodes = /* @__PURE__ */ new Set();
+      const pending = {
+        opId,
+        consistency: import_core9.ConsistencyLevel.QUORUM,
+        targetNodes,
+        ackedNodes,
+        resolve: () => {
+          const ackedSnapshot = Array.from(ackedNodes);
+          const ackedBy = [this.nodeId, ...ackedSnapshot];
+          resolve({ success: true, ackedBy });
+        },
+        reject: (error) => reject(error),
+        timeout: setTimeout(() => {
+          this.pendingAcks.delete(opId);
+          const ackedList = Array.from(ackedNodes);
+          reject(new ReplicationTimeoutError(opId, targetNodes, ackedList));
+        }, timeout ?? this.config.ackTimeoutMs),
+        startTime: Date.now()
+      };
+      this.pendingAcks.set(opId, pending);
+      for (const nodeId of targetNodes) {
+        this.lagTracker.incrementPending(nodeId);
+      }
+      for (const nodeId of targetNodes) {
+        this.sendReplication(nodeId, operation, opId, import_core9.ConsistencyLevel.QUORUM);
+      }
+    });
+  }
+  /**
+   * EVENTUAL: Fire-and-forget with queue
+   */
+  async replicateEventual(operation, opId, backups) {
+    for (const nodeId of backups) {
+      this.enqueue(nodeId, {
+        opId,
+        operation,
+        consistency: import_core9.ConsistencyLevel.EVENTUAL,
+        timestamp: Date.now(),
+        retryCount: 0
+      });
+    }
+    return { success: true, ackedBy: [this.nodeId] };
+  }
+  // ============================================
+  // Queue Management
+  // ============================================
+  /**
+   * Add task to replication queue
+   */
+  enqueue(nodeId, task) {
+    let queue = this.replicationQueue.get(nodeId);
+    if (!queue) {
+      queue = [];
+      this.replicationQueue.set(nodeId, queue);
+    }
+    if (queue.length >= this.config.queueSizeLimit) {
+      this.emit("queueOverflow", nodeId);
+      logger.warn({ nodeId, queueSize: queue.length }, "Replication queue overflow, dropping oldest");
+      queue.shift();
+    }
+    queue.push(task);
+    this.lagTracker.incrementPending(nodeId);
+  }
+  /**
+   * Start queue processor
+   */
+  startQueueProcessor() {
+    if (this.queueProcessorTimer) return;
+    this.queueProcessorTimer = setInterval(() => {
+      for (const nodeId of this.replicationQueue.keys()) {
+        this.processQueue(nodeId).catch((err) => {
+          logger.error({ nodeId, error: err }, "Error processing replication queue");
+          this.emit("error", err);
+        });
+      }
+    }, this.config.batchIntervalMs);
+  }
+  /**
+   * Stop queue processor
+   */
+  stopQueueProcessor() {
+    if (this.queueProcessorTimer) {
+      clearInterval(this.queueProcessorTimer);
+      this.queueProcessorTimer = null;
+    }
+  }
+  /**
+   * Process replication queue for a node
+   */
+  async processQueue(nodeId) {
+    const queue = this.replicationQueue.get(nodeId);
+    if (!queue || queue.length === 0) return;
+    const batch = queue.splice(0, this.config.batchSize);
+    try {
+      this.clusterManager.send(nodeId, "OP_FORWARD", {
+        _replication: {
+          type: "REPLICATION_BATCH",
+          payload: {
+            operations: batch.map((t) => t.operation),
+            opIds: batch.map((t) => t.opId)
+          }
+        }
+      });
+      const oldestTimestamp = Math.min(...batch.map((t) => t.timestamp));
+      this.lagTracker.update(nodeId, Date.now() - oldestTimestamp);
+      logger.debug({ nodeId, batchSize: batch.length }, "Sent replication batch");
+    } catch (error) {
+      for (const task of batch) {
+        task.retryCount++;
+        if (task.retryCount <= this.config.maxRetries) {
+          queue.unshift(task);
+        } else {
+          logger.warn({ nodeId, opId: task.opId, retries: task.retryCount }, "Replication task exceeded max retries");
+          this.emit("replicationFailed", task.opId, new Error("Max retries exceeded"));
+        }
+      }
+    }
+  }
+  // ============================================
+  // Message Handling
+  // ============================================
+  /**
+   * Send replication message to a node
+   */
+  sendReplication(nodeId, operation, opId, consistency) {
+    this.clusterManager.send(nodeId, "OP_FORWARD", {
+      _replication: {
+        type: "REPLICATION",
+        payload: {
+          opId,
+          operation,
+          consistency
+        }
+      }
+    });
+  }
+  /**
+   * Setup cluster message handlers
+   */
+  setupMessageHandlers() {
+    this.clusterManager.on("message", (msg) => {
+      if (msg.payload?._replication) {
+        const replication = msg.payload._replication;
+        switch (replication.type) {
+          case "REPLICATION":
+            this.handleReplication(msg.senderId, replication.payload);
+            break;
+          case "REPLICATION_BATCH":
+            this.handleReplicationBatch(msg.senderId, replication.payload);
+            break;
+          case "REPLICATION_ACK":
+            this.handleReplicationAck(msg.senderId, replication.payload);
+            break;
+          case "REPLICATION_BATCH_ACK":
+            this.handleReplicationBatchAck(msg.senderId, replication.payload);
+            break;
+        }
+      }
+    });
+  }
+  /**
+   * Handle incoming replication request (on backup node)
+   */
+  async handleReplication(sourceNode, payload) {
+    const { opId, operation, consistency } = payload;
+    logger.debug({ sourceNode, opId, consistency }, "Received replication");
+    let success = true;
+    if (this.operationApplier) {
+      try {
+        success = await this.operationApplier(operation, opId, sourceNode);
+      } catch (error) {
+        logger.error({ sourceNode, opId, error }, "Failed to apply replicated operation");
+        success = false;
+      }
+    } else {
+      logger.warn({ sourceNode, opId }, "No operation applier set, operation not applied");
+    }
+    if (consistency === import_core9.ConsistencyLevel.STRONG || consistency === import_core9.ConsistencyLevel.QUORUM) {
+      this.clusterManager.send(sourceNode, "OP_FORWARD", {
+        _replication: {
+          type: "REPLICATION_ACK",
+          payload: {
+            opId,
+            success,
+            timestamp: Date.now()
+          }
+        }
+      });
+    }
+  }
+  /**
+   * Handle incoming batch replication (on backup node)
+   */
+  async handleReplicationBatch(sourceNode, payload) {
+    const { operations, opIds } = payload;
+    logger.debug({ sourceNode, count: operations.length }, "Received replication batch");
+    let allSuccess = true;
+    if (this.operationApplier) {
+      for (let i = 0; i < operations.length; i++) {
+        try {
+          const success = await this.operationApplier(operations[i], opIds[i], sourceNode);
+          if (!success) {
+            allSuccess = false;
+          }
+        } catch (error) {
+          logger.error({ sourceNode, opId: opIds[i], error }, "Failed to apply replicated operation in batch");
+          allSuccess = false;
+        }
+      }
+    } else {
+      logger.warn({ sourceNode, count: operations.length }, "No operation applier set, batch not applied");
+    }
+    this.clusterManager.send(sourceNode, "OP_FORWARD", {
+      _replication: {
+        type: "REPLICATION_BATCH_ACK",
+        payload: {
+          opIds,
+          success: allSuccess,
+          timestamp: Date.now()
+        }
+      }
+    });
+  }
+  /**
+   * Handle replication acknowledgment (on owner node)
+   */
+  handleReplicationAck(sourceNode, payload) {
+    const { opId, success } = payload;
+    this.lagTracker.recordAck(sourceNode);
+    const pending = this.pendingAcks.get(opId);
     if (!pending) return;
-    if (pending.timeoutHandle) {
-      clearTimeout(pending.timeoutHandle);
+    if (!success) {
+      logger.warn({ sourceNode, opId }, "Replication rejected by backup");
+      return;
+    }
+    pending.ackedNodes.add(sourceNode);
+    const lag = Date.now() - pending.startTime;
+    this.lagTracker.update(sourceNode, lag);
+    const ackedCount = pending.ackedNodes.size;
+    const targetCount = pending.targetNodes.length;
+    switch (pending.consistency) {
+      case import_core9.ConsistencyLevel.STRONG:
+        if (ackedCount === targetCount) {
+          clearTimeout(pending.timeout);
+          this.pendingAcks.delete(opId);
+          pending.resolve();
+          this.emit("replicationComplete", opId, [this.nodeId, ...pending.ackedNodes]);
+        }
+        break;
+      case import_core9.ConsistencyLevel.QUORUM:
+        const quorumSize = Math.floor(targetCount / 2) + 1;
+        if (ackedCount >= quorumSize) {
+          clearTimeout(pending.timeout);
+          this.pendingAcks.delete(opId);
+          pending.resolve();
+          this.emit("replicationComplete", opId, [this.nodeId, ...pending.ackedNodes]);
+        }
+        break;
     }
-    const latencyMs = Date.now() - pending.timestamp;
-    const highestAchieved = (0, import_core6.getHighestWriteConcernLevel)(pending.achievedLevels);
-    const result = {
-      success: false,
-      opId,
-      achievedLevel: highestAchieved,
-      latencyMs,
-      error
-    };
-    pending.resolve(result);
-    this.pending.delete(opId);
-    logger.error({ opId, error, latencyMs }, "Write failed");
-    this.emit("failed", result);
   }
   /**
-   * Get pending writes statistics.
+   * Handle batch acknowledgment (on owner node)
    */
-  getStats() {
-    const byLevel = {
-      [import_core6.WriteConcern.FIRE_AND_FORGET]: 0,
-      [import_core6.WriteConcern.MEMORY]: 0,
-      [import_core6.WriteConcern.APPLIED]: 0,
-      [import_core6.WriteConcern.REPLICATED]: 0,
-      [import_core6.WriteConcern.PERSISTED]: 0
-    };
-    for (const pending of this.pending.values()) {
-      byLevel[pending.writeConcern]++;
+  handleReplicationBatchAck(sourceNode, payload) {
+    const { success } = payload;
+    this.lagTracker.recordAck(sourceNode);
+    if (!success) {
+      logger.warn({ sourceNode, count: payload.opIds.length }, "Batch replication rejected");
     }
-    return { pending: this.pending.size, byLevel };
   }
+  // ============================================
+  // Status and Metrics
+  // ============================================
   /**
-   * Get all pending operation IDs.
+   * Get replication lag for a specific node
    */
-  getPendingIds() {
-    return Array.from(this.pending.keys());
+  getLag(nodeId) {
+    return this.lagTracker.getLag(nodeId);
   }
   /**
-   * Clear all pending writes (for shutdown).
-   * Rejects all pending promises with an error.
+   * Get overall replication health
    */
-  clear() {
-    const count = this.pending.size;
-    for (const pending of this.pending.values()) {
-      if (pending.timeoutHandle) {
-        clearTimeout(pending.timeoutHandle);
-      }
-      pending.reject(new Error("WriteAckManager cleared"));
-    }
-    this.pending.clear();
-    if (count > 0) {
-      logger.info({ count }, "WriteAckManager cleared");
+  getHealth() {
+    return this.lagTracker.getHealth();
+  }
+  /**
+   * Get queue size for a specific node
+   */
+  getQueueSize(nodeId) {
+    return this.replicationQueue.get(nodeId)?.length ?? 0;
+  }
+  /**
+   * Get total pending operations across all nodes
+   */
+  getTotalPending() {
+    let total = 0;
+    for (const queue of this.replicationQueue.values()) {
+      total += queue.length;
     }
+    return total + this.pendingAcks.size;
   }
   /**
-   * Graceful shutdown - resolves all pending writes with their current achieved level.
+   * Check if a node is considered synced (low lag)
    */
-  shutdown() {
-    const count = this.pending.size;
-    for (const [opId, pending] of this.pending.entries()) {
-      if (pending.timeoutHandle) {
-        clearTimeout(pending.timeoutHandle);
-      }
-      const highestAchieved = (0, import_core6.getHighestWriteConcernLevel)(pending.achievedLevels);
-      const latencyMs = Date.now() - pending.timestamp;
-      const result = {
-        success: highestAchieved === pending.writeConcern,
-        opId,
-        achievedLevel: highestAchieved,
-        latencyMs,
-        error: highestAchieved !== pending.writeConcern ? `Shutdown: achieved ${highestAchieved}, requested ${pending.writeConcern}` : void 0
-      };
-      pending.resolve(result);
+  isSynced(nodeId, maxLagMs = 1e3) {
+    const lag = this.lagTracker.getLag(nodeId);
+    return lag.current < maxLagMs;
+  }
+  /**
+   * Get LagTracker for advanced monitoring
+   */
+  getLagTracker() {
+    return this.lagTracker;
+  }
+  /**
+   * Export metrics in Prometheus format
+   */
+  toPrometheusMetrics() {
+    const lines = [];
+    lines.push("# HELP topgun_replication_queue_size Pending operations in replication queue");
+    lines.push("# TYPE topgun_replication_queue_size gauge");
+    for (const [nodeId, queue] of this.replicationQueue) {
+      lines.push(`topgun_replication_queue_size{node="${nodeId}"} ${queue.length}`);
     }
-    this.pending.clear();
-    if (count > 0) {
-      logger.info({ count }, "WriteAckManager shutdown");
+    lines.push("");
+    lines.push("# HELP topgun_replication_pending_acks Pending synchronous acknowledgments");
+    lines.push("# TYPE topgun_replication_pending_acks gauge");
+    lines.push(`topgun_replication_pending_acks ${this.pendingAcks.size}`);
+    lines.push("");
+    lines.push(this.lagTracker.toPrometheusMetrics());
+    return lines.join("\n");
+  }
+  /**
+   * Cleanup resources
+   */
+  close() {
+    this.stopQueueProcessor();
+    for (const [opId, pending] of this.pendingAcks) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("ReplicationPipeline closed"));
     }
+    this.pendingAcks.clear();
+    this.replicationQueue.clear();
+    this.lagTracker.clear();
   }
 };
 
@@ -4662,7 +6492,7 @@ var ServerCoordinator = class {
     this._readyPromise = new Promise((resolve) => {
       this._readyResolve = resolve;
     });
-    this.hlc = new import_core7.HLC(config.nodeId);
+    this.hlc = new import_core10.HLC(config.nodeId);
     this.storage = config.storage;
     const rawSecret = config.jwtSecret || process.env.JWT_SECRET || "topgun-secret-dev";
     this.jwtSecret = rawSecret.replace(/\\n/g, "\n");
@@ -4799,6 +6629,22 @@ var ServerCoordinator = class {
         tls: config.clusterTls
       });
       this.partitionService = new PartitionService(this.cluster);
+      if (config.replicationEnabled !== false) {
+        this.replicationPipeline = new ReplicationPipeline(
+          this.cluster,
+          this.partitionService,
+          {
+            ...import_core10.DEFAULT_REPLICATION_CONFIG,
+            defaultConsistency: config.defaultConsistency ?? import_core10.ConsistencyLevel.EVENTUAL,
+            ...config.replicationConfig
+          }
+        );
+        this.replicationPipeline.setOperationApplier(this.applyReplicatedOperation.bind(this));
+        logger.info({ nodeId: config.nodeId }, "ReplicationPipeline initialized");
+      }
+      this.partitionService.on("rebalanced", (partitionMap, changes) => {
+        this.broadcastPartitionMap(partitionMap);
+      });
       this.lockManager = new LockManager();
       this.lockManager.on("lockGranted", (evt) => this.handleLockGranted(evt));
       this.topicManager = new TopicManager({
@@ -4915,7 +6761,7 @@ var ServerCoordinator = class {
     this.metricsService.destroy();
     this.wss.close();
     logger.info(`Closing ${this.clients.size} client connections...`);
-    const shutdownMsg = (0, import_core7.serialize)({ type: "SHUTDOWN_PENDING", retryAfter: 5e3 });
+    const shutdownMsg = (0, import_core10.serialize)({ type: "SHUTDOWN_PENDING", retryAfter: 5e3 });
     for (const client of this.clients.values()) {
       try {
         if (client.socket.readyState === import_ws3.WebSocket.OPEN) {
@@ -4937,6 +6783,9 @@ var ServerCoordinator = class {
       await this.workerPool.shutdown(5e3);
       logger.info("Worker pool shutdown complete.");
     }
+    if (this.replicationPipeline) {
+      this.replicationPipeline.close();
+    }
     if (this.cluster) {
       this.cluster.stop();
     }
@@ -5033,7 +6882,7 @@ var ServerCoordinator = class {
           buf = Buffer.from(message);
         }
         try {
-          data = (0, import_core7.deserialize)(buf);
+          data = (0, import_core10.deserialize)(buf);
         } catch (e) {
           try {
             const text = Buffer.isBuffer(buf) ? buf.toString() : new TextDecoder().decode(buf);
@@ -5084,10 +6933,10 @@ var ServerCoordinator = class {
       this.clients.delete(clientId);
       this.metricsService.setConnectedClients(this.clients.size);
     });
-    ws.send((0, import_core7.serialize)({ type: "AUTH_REQUIRED" }));
+    ws.send((0, import_core10.serialize)({ type: "AUTH_REQUIRED" }));
   }
   async handleMessage(client, rawMessage) {
-    const parseResult = import_core7.MessageSchema.safeParse(rawMessage);
+    const parseResult = import_core10.MessageSchema.safeParse(rawMessage);
     if (!parseResult.success) {
       logger.error({ clientId: client.id, error: parseResult.error }, "Invalid message format from client");
       client.writer.write({
@@ -5327,7 +7176,7 @@ var ServerCoordinator = class {
         this.metricsService.incOp("GET", message.mapName);
         try {
           const mapForSync = await this.getMapAsync(message.mapName);
-          if (mapForSync instanceof import_core7.LWWMap) {
+          if (mapForSync instanceof import_core10.LWWMap) {
             const tree = mapForSync.getMerkleTree();
             const rootHash = tree.getRootHash();
             client.writer.write({
@@ -5365,7 +7214,7 @@ var ServerCoordinator = class {
         const { mapName, path } = message.payload;
         try {
           const mapForBucket = await this.getMapAsync(mapName);
-          if (mapForBucket instanceof import_core7.LWWMap) {
+          if (mapForBucket instanceof import_core10.LWWMap) {
             const treeForBucket = mapForBucket.getMerkleTree();
             const buckets = treeForBucket.getBuckets(path);
             const node = treeForBucket.getNode(path);
@@ -5494,6 +7343,23 @@ var ServerCoordinator = class {
         }
         break;
       }
+      // ============ Phase 4: Partition Map Request Handler ============
+      case "PARTITION_MAP_REQUEST": {
+        const clientVersion = message.payload?.currentVersion ?? 0;
+        const currentMap = this.partitionService.getPartitionMap();
+        if (clientVersion < currentMap.version) {
+          client.writer.write({
+            type: "PARTITION_MAP",
+            payload: currentMap
+          });
+          logger.debug({
+            clientId: client.id,
+            clientVersion,
+            serverVersion: currentMap.version
+          }, "Sent partition map to client");
+        }
+        break;
+      }
       // ============ ORMap Sync Message Handlers ============
       case "ORMAP_SYNC_INIT": {
         if (!this.securityManager.checkPermission(client.principal, message.mapName, "READ")) {
@@ -5517,7 +7383,7 @@ var ServerCoordinator = class {
         this.metricsService.incOp("GET", message.mapName);
         try {
           const mapForSync = await this.getMapAsync(message.mapName, "OR");
-          if (mapForSync instanceof import_core7.ORMap) {
+          if (mapForSync instanceof import_core10.ORMap) {
             const tree = mapForSync.getMerkleTree();
             const rootHash = tree.getRootHash();
             client.writer.write({
@@ -5554,7 +7420,7 @@ var ServerCoordinator = class {
         const { mapName, path } = message.payload;
         try {
           const mapForBucket = await this.getMapAsync(mapName, "OR");
-          if (mapForBucket instanceof import_core7.ORMap) {
+          if (mapForBucket instanceof import_core10.ORMap) {
             const tree = mapForBucket.getMerkleTree();
             const buckets = tree.getBuckets(path);
             const isLeaf = tree.isLeaf(path);
@@ -5598,7 +7464,7 @@ var ServerCoordinator = class {
         const { mapName: diffMapName, keys } = message.payload;
         try {
           const mapForDiff = await this.getMapAsync(diffMapName, "OR");
-          if (mapForDiff instanceof import_core7.ORMap) {
+          if (mapForDiff instanceof import_core10.ORMap) {
             const entries = [];
             const allTombstones = mapForDiff.getTombstones();
             for (const key of keys) {
@@ -5630,7 +7496,7 @@ var ServerCoordinator = class {
         const { mapName: pushMapName, entries: pushEntries } = message.payload;
         try {
           const mapForPush = await this.getMapAsync(pushMapName, "OR");
-          if (mapForPush instanceof import_core7.ORMap) {
+          if (mapForPush instanceof import_core10.ORMap) {
             let totalAdded = 0;
             let totalUpdated = 0;
             for (const entry of pushEntries) {
@@ -5685,7 +7551,7 @@ var ServerCoordinator = class {
       } else if (op.orRecord && op.orRecord.timestamp) {
       } else if (op.orTag) {
         try {
-          ts = import_core7.HLC.parse(op.orTag);
+          ts = import_core10.HLC.parse(op.orTag);
         } catch (e) {
         }
       }
@@ -5697,6 +7563,28 @@ var ServerCoordinator = class {
       client.lastActiveHlc = this.hlc.now();
     }
   }
+  // ============ Phase 4: Partition Map Broadcast ============
+  /**
+   * Broadcast partition map to all connected and authenticated clients.
+   * Called when partition topology changes (node join/leave/failover).
+   */
+  broadcastPartitionMap(partitionMap) {
+    const message = {
+      type: "PARTITION_MAP",
+      payload: partitionMap
+    };
+    let broadcastCount = 0;
+    for (const client of this.clients.values()) {
+      if (client.isAuthenticated && client.socket.readyState === import_ws3.WebSocket.OPEN) {
+        client.writer.write(message);
+        broadcastCount++;
+      }
+    }
+    logger.info({
+      version: partitionMap.version,
+      clientCount: broadcastCount
+    }, "Broadcast partition map to clients");
+  }
   broadcast(message, excludeClientId) {
     const isServerEvent = message.type === "SERVER_EVENT";
     if (isServerEvent) {
@@ -5727,7 +7615,7 @@ var ServerCoordinator = class {
         client.writer.write({ ...message, payload: newPayload });
       }
     } else {
-      const msgData = (0, import_core7.serialize)(message);
+      const msgData = (0, import_core10.serialize)(message);
       for (const [id, client] of this.clients) {
         if (id !== excludeClientId && client.socket.readyState === 1) {
           client.writer.writeRaw(msgData);
@@ -5805,7 +7693,7 @@ var ServerCoordinator = class {
         payload: { events: filteredEvents },
         timestamp: this.hlc.now()
       };
-      const serializedBatch = (0, import_core7.serialize)(batchMessage);
+      const serializedBatch = (0, import_core10.serialize)(batchMessage);
       for (const client of clients) {
         try {
           client.writer.writeRaw(serializedBatch);
@@ -5890,7 +7778,7 @@ var ServerCoordinator = class {
         payload: { events: filteredEvents },
         timestamp: this.hlc.now()
       };
-      const serializedBatch = (0, import_core7.serialize)(batchMessage);
+      const serializedBatch = (0, import_core10.serialize)(batchMessage);
       for (const client of clients) {
         sendPromises.push(new Promise((resolve, reject) => {
           try {
@@ -6034,14 +7922,14 @@ var ServerCoordinator = class {
   async executeLocalQuery(mapName, query) {
     const map = await this.getMapAsync(mapName);
     const records = /* @__PURE__ */ new Map();
-    if (map instanceof import_core7.LWWMap) {
+    if (map instanceof import_core10.LWWMap) {
       for (const key of map.allKeys()) {
         const rec = map.getRecord(key);
         if (rec && rec.value !== null) {
           records.set(key, rec);
         }
       }
-    } else if (map instanceof import_core7.ORMap) {
+    } else if (map instanceof import_core10.ORMap) {
       const items = map.items;
       for (const key of items.keys()) {
         const values = map.get(key);
@@ -6111,11 +7999,11 @@ var ServerCoordinator = class {
   applyOpToMap(op) {
     const typeHint = op.opType === "OR_ADD" || op.opType === "OR_REMOVE" ? "OR" : "LWW";
     const map = this.getMap(op.mapName, typeHint);
-    if (typeHint === "OR" && map instanceof import_core7.LWWMap) {
+    if (typeHint === "OR" && map instanceof import_core10.LWWMap) {
       logger.error({ mapName: op.mapName }, "Map type mismatch: LWWMap but received OR op");
       throw new Error("Map type mismatch: LWWMap but received OR op");
     }
-    if (typeHint === "LWW" && map instanceof import_core7.ORMap) {
+    if (typeHint === "LWW" && map instanceof import_core10.ORMap) {
       logger.error({ mapName: op.mapName }, "Map type mismatch: ORMap but received LWW op");
       throw new Error("Map type mismatch: ORMap but received LWW op");
     }
@@ -6126,13 +8014,13 @@ var ServerCoordinator = class {
       mapName: op.mapName,
       key: op.key
     };
-    if (map instanceof import_core7.LWWMap) {
+    if (map instanceof import_core10.LWWMap) {
       oldRecord = map.getRecord(op.key);
       map.merge(op.key, op.record);
       recordToStore = op.record;
       eventPayload.eventType = "UPDATED";
       eventPayload.record = op.record;
-    } else if (map instanceof import_core7.ORMap) {
+    } else if (map instanceof import_core10.ORMap) {
       oldRecord = map.getRecords(op.key);
       if (op.opType === "OR_ADD") {
         map.apply(op.key, op.orRecord);
@@ -6148,7 +8036,7 @@ var ServerCoordinator = class {
       }
     }
     this.queryRegistry.processChange(op.mapName, map, op.key, op.record || op.orRecord, oldRecord);
-    const mapSize = map instanceof import_core7.ORMap ? map.totalRecords : map.size;
+    const mapSize = map instanceof import_core10.ORMap ? map.totalRecords : map.size;
     this.metricsService.setMapSize(op.mapName, mapSize);
     if (this.storage) {
       if (recordToStore) {
@@ -6175,6 +8063,26 @@ var ServerCoordinator = class {
       }
     }
   }
+  /**
+   * Apply replicated operation from another node (callback for ReplicationPipeline)
+   * This is called when we receive a replicated operation as a backup node
+   */
+  async applyReplicatedOperation(operation, opId, sourceNode) {
+    try {
+      const op = operation;
+      logger.debug({ sourceNode, opId, mapName: op.mapName, key: op.key }, "Applying replicated operation");
+      const { eventPayload } = this.applyOpToMap(op);
+      this.broadcast({
+        type: "SERVER_EVENT",
+        payload: eventPayload,
+        timestamp: this.hlc.now()
+      });
+      return true;
+    } catch (error) {
+      logger.error({ sourceNode, opId, error }, "Failed to apply replicated operation");
+      return false;
+    }
+  }
   /**
    * Build OpContext for interceptors.
    */
@@ -6263,6 +8171,12 @@ var ServerCoordinator = class {
       throw err;
     }
     const { eventPayload } = this.applyOpToMap(op);
+    if (this.replicationPipeline && !fromCluster) {
+      const opId = op.id || `${op.mapName}:${op.key}:${Date.now()}`;
+      this.replicationPipeline.replicate(op, opId, op.key).catch((err) => {
+        logger.warn({ opId, key: op.key, err }, "Replication failed (non-fatal)");
+      });
+    }
     this.broadcast({
       type: "SERVER_EVENT",
       payload: eventPayload,
@@ -6385,6 +8299,12 @@ var ServerCoordinator = class {
       throw err;
     }
     const { eventPayload } = this.applyOpToMap(op);
+    if (this.replicationPipeline) {
+      const opId = op.id || `${op.mapName}:${op.key}:${Date.now()}`;
+      this.replicationPipeline.replicate(op, opId, op.key).catch((err) => {
+        logger.warn({ opId, key: op.key, err }, "Batch replication failed (non-fatal)");
+      });
+    }
     batchedEvents.push(eventPayload);
     this.broadcastToCluster(eventPayload);
     this.runAfterInterceptors(op, context);
@@ -6392,11 +8312,11 @@ var ServerCoordinator = class {
   handleClusterEvent(payload) {
     const { mapName, key, eventType } = payload;
     const map = this.getMap(mapName, eventType === "OR_ADD" || eventType === "OR_REMOVE" ? "OR" : "LWW");
-    const oldRecord = map instanceof import_core7.LWWMap ? map.getRecord(key) : null;
+    const oldRecord = map instanceof import_core10.LWWMap ? map.getRecord(key) : null;
     if (this.partitionService.isRelated(key)) {
-      if (map instanceof import_core7.LWWMap && payload.record) {
+      if (map instanceof import_core10.LWWMap && payload.record) {
         map.merge(key, payload.record);
-      } else if (map instanceof import_core7.ORMap) {
+      } else if (map instanceof import_core10.ORMap) {
         if (eventType === "OR_ADD" && payload.orRecord) {
           map.apply(key, payload.orRecord);
         } else if (eventType === "OR_REMOVE" && payload.orTag) {
@@ -6415,9 +8335,9 @@ var ServerCoordinator = class {
     if (!this.maps.has(name)) {
       let map;
       if (typeHint === "OR") {
-        map = new import_core7.ORMap(this.hlc);
+        map = new import_core10.ORMap(this.hlc);
       } else {
-        map = new import_core7.LWWMap(this.hlc);
+        map = new import_core10.LWWMap(this.hlc);
       }
       this.maps.set(name, map);
       if (this.storage) {
@@ -6440,7 +8360,7 @@ var ServerCoordinator = class {
     this.getMap(name, typeHint);
     const loadingPromise = this.mapLoadingPromises.get(name);
     const map = this.maps.get(name);
-    const mapSize = map instanceof import_core7.LWWMap ? Array.from(map.entries()).length : map instanceof import_core7.ORMap ? map.size : 0;
+    const mapSize = map instanceof import_core10.LWWMap ? Array.from(map.entries()).length : map instanceof import_core10.ORMap ? map.size : 0;
     logger.info({
       mapName: name,
       mapExisted,
@@ -6450,7 +8370,7 @@ var ServerCoordinator = class {
     if (loadingPromise) {
       logger.info({ mapName: name }, "[getMapAsync] Waiting for loadMapFromStorage...");
       await loadingPromise;
-      const newMapSize = map instanceof import_core7.LWWMap ? Array.from(map.entries()).length : map instanceof import_core7.ORMap ? map.size : 0;
+      const newMapSize = map instanceof import_core10.LWWMap ? Array.from(map.entries()).length : map instanceof import_core10.ORMap ? map.size : 0;
       logger.info({ mapName: name, mapSizeAfterLoad: newMapSize }, "[getMapAsync] Load completed");
     }
     return this.maps.get(name);
@@ -6476,16 +8396,16 @@ var ServerCoordinator = class {
       const currentMap = this.maps.get(name);
       if (!currentMap) return;
       let targetMap = currentMap;
-      if (isOR && currentMap instanceof import_core7.LWWMap) {
+      if (isOR && currentMap instanceof import_core10.LWWMap) {
         logger.info({ mapName: name }, "Map auto-detected as ORMap. Switching type.");
-        targetMap = new import_core7.ORMap(this.hlc);
+        targetMap = new import_core10.ORMap(this.hlc);
         this.maps.set(name, targetMap);
-      } else if (!isOR && currentMap instanceof import_core7.ORMap && typeHint !== "OR") {
+      } else if (!isOR && currentMap instanceof import_core10.ORMap && typeHint !== "OR") {
         logger.info({ mapName: name }, "Map auto-detected as LWWMap. Switching type.");
-        targetMap = new import_core7.LWWMap(this.hlc);
+        targetMap = new import_core10.LWWMap(this.hlc);
         this.maps.set(name, targetMap);
       }
-      if (targetMap instanceof import_core7.ORMap) {
+      if (targetMap instanceof import_core10.ORMap) {
         for (const [key, record] of records) {
           if (key === "__tombstones__") {
             const t = record;
@@ -6498,7 +8418,7 @@ var ServerCoordinator = class {
             }
           }
         }
-      } else if (targetMap instanceof import_core7.LWWMap) {
+      } else if (targetMap instanceof import_core10.LWWMap) {
         for (const [key, record] of records) {
           if (!record.type) {
             targetMap.merge(key, record);
@@ -6509,7 +8429,7 @@ var ServerCoordinator = class {
       if (count > 0) {
         logger.info({ mapName: name, count }, "Loaded records for map");
         this.queryRegistry.refreshSubscriptions(name, targetMap);
-        const mapSize = targetMap instanceof import_core7.ORMap ? targetMap.totalRecords : targetMap.size;
+        const mapSize = targetMap instanceof import_core10.ORMap ? targetMap.totalRecords : targetMap.size;
         this.metricsService.setMapSize(name, mapSize);
       }
     } catch (err) {
@@ -6591,7 +8511,7 @@ var ServerCoordinator = class {
   reportLocalHlc() {
     let minHlc = this.hlc.now();
     for (const client of this.clients.values()) {
-      if (import_core7.HLC.compare(client.lastActiveHlc, minHlc) < 0) {
+      if (import_core10.HLC.compare(client.lastActiveHlc, minHlc) < 0) {
         minHlc = client.lastActiveHlc;
       }
     }
@@ -6612,7 +8532,7 @@ var ServerCoordinator = class {
       let globalSafe = this.hlc.now();
       let initialized = false;
       for (const ts of this.gcReports.values()) {
-        if (!initialized || import_core7.HLC.compare(ts, globalSafe) < 0) {
+        if (!initialized || import_core10.HLC.compare(ts, globalSafe) < 0) {
           globalSafe = ts;
           initialized = true;
         }
@@ -6647,7 +8567,7 @@ var ServerCoordinator = class {
     logger.info({ olderThanMillis: olderThan.millis }, "Performing Garbage Collection");
     const now = Date.now();
     for (const [name, map] of this.maps) {
-      if (map instanceof import_core7.LWWMap) {
+      if (map instanceof import_core10.LWWMap) {
         for (const key of map.allKeys()) {
           const record = map.getRecord(key);
           if (record && record.value !== null && record.ttlMs) {
@@ -6699,7 +8619,7 @@ var ServerCoordinator = class {
             });
           }
         }
-      } else if (map instanceof import_core7.ORMap) {
+      } else if (map instanceof import_core10.ORMap) {
         const items = map.items;
         const tombstonesSet = map.tombstones;
         const tagsToExpire = [];
@@ -6802,17 +8722,17 @@ var ServerCoordinator = class {
   stringToWriteConcern(value) {
     switch (value) {
       case "FIRE_AND_FORGET":
-        return import_core7.WriteConcern.FIRE_AND_FORGET;
+        return import_core10.WriteConcern.FIRE_AND_FORGET;
       case "MEMORY":
-        return import_core7.WriteConcern.MEMORY;
+        return import_core10.WriteConcern.MEMORY;
       case "APPLIED":
-        return import_core7.WriteConcern.APPLIED;
+        return import_core10.WriteConcern.APPLIED;
       case "REPLICATED":
-        return import_core7.WriteConcern.REPLICATED;
+        return import_core10.WriteConcern.REPLICATED;
       case "PERSISTED":
-        return import_core7.WriteConcern.PERSISTED;
+        return import_core10.WriteConcern.PERSISTED;
       default:
-        return import_core7.WriteConcern.MEMORY;
+        return import_core10.WriteConcern.MEMORY;
     }
   }
   /**
@@ -6869,7 +8789,7 @@ var ServerCoordinator = class {
             }
           });
           if (op.id) {
-            this.writeAckManager.notifyLevel(op.id, import_core7.WriteConcern.REPLICATED);
+            this.writeAckManager.notifyLevel(op.id, import_core10.WriteConcern.REPLICATED);
           }
         }
       }
@@ -6877,7 +8797,7 @@ var ServerCoordinator = class {
         this.broadcastBatch(batchedEvents, clientId);
         for (const op of ops) {
           if (op.id && this.partitionService.isLocalOwner(op.key)) {
-            this.writeAckManager.notifyLevel(op.id, import_core7.WriteConcern.REPLICATED);
+            this.writeAckManager.notifyLevel(op.id, import_core10.WriteConcern.REPLICATED);
           }
         }
       }
@@ -6905,7 +8825,7 @@ var ServerCoordinator = class {
         const owner = this.partitionService.getOwner(op.key);
         await this.forwardOpAndWait(op, owner);
         if (op.id) {
-          this.writeAckManager.notifyLevel(op.id, import_core7.WriteConcern.REPLICATED);
+          this.writeAckManager.notifyLevel(op.id, import_core10.WriteConcern.REPLICATED);
         }
       }
     }
@@ -6913,7 +8833,7 @@ var ServerCoordinator = class {
       await this.broadcastBatchSync(batchedEvents, clientId);
       for (const op of ops) {
         if (op.id && this.partitionService.isLocalOwner(op.key)) {
-          this.writeAckManager.notifyLevel(op.id, import_core7.WriteConcern.REPLICATED);
+          this.writeAckManager.notifyLevel(op.id, import_core10.WriteConcern.REPLICATED);
         }
       }
     }
@@ -6941,7 +8861,7 @@ var ServerCoordinator = class {
     }
     const { eventPayload } = this.applyOpToMap(op);
     if (op.id) {
-      this.writeAckManager.notifyLevel(op.id, import_core7.WriteConcern.APPLIED);
+      this.writeAckManager.notifyLevel(op.id, import_core10.WriteConcern.APPLIED);
     }
     if (eventPayload) {
       batchedEvents.push({
@@ -6955,7 +8875,7 @@ var ServerCoordinator = class {
       try {
         await this.persistOpSync(op);
         if (op.id) {
-          this.writeAckManager.notifyLevel(op.id, import_core7.WriteConcern.PERSISTED);
+          this.writeAckManager.notifyLevel(op.id, import_core10.WriteConcern.PERSISTED);
         }
       } catch (err) {
         logger.error({ opId: op.id, err }, "Persistence failed");
@@ -7298,10 +9218,10 @@ var RateLimitInterceptor = class {
 };
 
 // src/utils/nativeStats.ts
-var import_core8 = require("@topgunbuild/core");
+var import_core11 = require("@topgunbuild/core");
 function getNativeModuleStatus() {
   return {
-    nativeHash: (0, import_core8.isUsingNativeHash)(),
+    nativeHash: (0, import_core11.isUsingNativeHash)(),
     sharedArrayBuffer: SharedMemoryManager.isAvailable()
   };
 }
@@ -7332,19 +9252,401 @@ function logNativeStatus() {
     `  - SharedArrayBuffer: ${status.sharedArrayBuffer ? "available" : "unavailable"}`
   );
 }
+
+// src/cluster/ClusterCoordinator.ts
+var import_events9 = require("events");
+var import_core12 = require("@topgunbuild/core");
+var DEFAULT_CLUSTER_COORDINATOR_CONFIG = {
+  gradualRebalancing: true,
+  migration: import_core12.DEFAULT_MIGRATION_CONFIG,
+  replication: import_core12.DEFAULT_REPLICATION_CONFIG,
+  replicationEnabled: true
+};
+var ClusterCoordinator = class extends import_events9.EventEmitter {
+  constructor(config) {
+    super();
+    this.replicationPipeline = null;
+    // State
+    this.started = false;
+    this.actualPort = 0;
+    this.config = {
+      ...DEFAULT_CLUSTER_COORDINATOR_CONFIG,
+      ...config
+    };
+    this.clusterManager = new ClusterManager(this.config.cluster);
+    this.lagTracker = new LagTracker();
+    const partitionServiceConfig = {
+      gradualRebalancing: this.config.gradualRebalancing,
+      migration: this.config.migration
+    };
+    this.partitionService = new PartitionService(this.clusterManager, partitionServiceConfig);
+    if (this.config.replicationEnabled) {
+      this.replicationPipeline = new ReplicationPipeline(
+        this.clusterManager,
+        this.partitionService,
+        this.config.replication
+      );
+    }
+    this.setupEventHandlers();
+  }
+  // ============================================
+  // Lifecycle Methods
+  // ============================================
+  /**
+   * Start the cluster coordinator
+   */
+  async start() {
+    if (this.started) {
+      return this.actualPort;
+    }
+    logger.info({ nodeId: this.config.cluster.nodeId }, "Starting ClusterCoordinator");
+    this.actualPort = await this.clusterManager.start();
+    const migrationManager = this.partitionService.getMigrationManager();
+    if (migrationManager && this.config.dataCollector) {
+      migrationManager.setDataCollector(this.config.dataCollector);
+    }
+    if (migrationManager && this.config.dataStorer) {
+      migrationManager.setDataStorer(this.config.dataStorer);
+    }
+    this.started = true;
+    this.emit("started");
+    logger.info({ nodeId: this.config.cluster.nodeId, port: this.actualPort }, "ClusterCoordinator started");
+    return this.actualPort;
+  }
+  /**
+   * Stop the cluster coordinator
+   */
+  async stop() {
+    if (!this.started) return;
+    logger.info({ nodeId: this.config.cluster.nodeId }, "Stopping ClusterCoordinator");
+    await this.partitionService.cancelMigrations();
+    this.replicationPipeline?.close();
+    this.clusterManager.stop();
+    this.started = false;
+    this.emit("stopped");
+    logger.info({ nodeId: this.config.cluster.nodeId }, "ClusterCoordinator stopped");
+  }
+  // ============================================
+  // Cluster Information
+  // ============================================
+  /**
+   * Get local node ID
+   */
+  getNodeId() {
+    return this.config.cluster.nodeId;
+  }
+  /**
+   * Get cluster port
+   */
+  getPort() {
+    return this.actualPort;
+  }
+  /**
+   * Get all cluster members
+   */
+  getMembers() {
+    return this.clusterManager.getMembers();
+  }
+  /**
+   * Check if this is the local node
+   */
+  isLocal(nodeId) {
+    return this.clusterManager.isLocal(nodeId);
+  }
+  /**
+   * Check if coordinator is started
+   */
+  isStarted() {
+    return this.started;
+  }
+  // ============================================
+  // Partition Operations
+  // ============================================
+  /**
+   * Get current partition map
+   */
+  getPartitionMap() {
+    return this.partitionService.getPartitionMap();
+  }
+  /**
+   * Get partition map version
+   */
+  getPartitionMapVersion() {
+    return this.partitionService.getMapVersion();
+  }
+  /**
+   * Get partition ID for a key
+   */
+  getPartitionId(key) {
+    return this.partitionService.getPartitionId(key);
+  }
+  /**
+   * Get owner node for a key
+   */
+  getOwner(key) {
+    return this.partitionService.getOwner(key);
+  }
+  /**
+   * Check if this node owns the key
+   */
+  isLocalOwner(key) {
+    return this.partitionService.isLocalOwner(key);
+  }
+  /**
+   * Check if this node is a backup for the key
+   */
+  isLocalBackup(key) {
+    return this.partitionService.isLocalBackup(key);
+  }
+  /**
+   * Get backup nodes for a partition
+   */
+  getBackups(partitionId) {
+    return this.partitionService.getBackups(partitionId);
+  }
+  /**
+   * Check if partition is currently migrating
+   */
+  isMigrating(partitionId) {
+    return this.partitionService.isMigrating(partitionId);
+  }
+  /**
+   * Check if any rebalancing is in progress
+   */
+  isRebalancing() {
+    return this.partitionService.isRebalancing();
+  }
+  // ============================================
+  // Migration Operations
+  // ============================================
+  /**
+   * Get migration status
+   */
+  getMigrationStatus() {
+    return this.partitionService.getMigrationStatus();
+  }
+  /**
+   * Get migration metrics
+   */
+  getMigrationMetrics() {
+    return this.partitionService.getMigrationManager()?.getMetrics() ?? null;
+  }
+  /**
+   * Cancel all active migrations
+   */
+  async cancelMigrations() {
+    await this.partitionService.cancelMigrations();
+  }
+  /**
+   * Set data collector for migrations
+   */
+  setDataCollector(collector) {
+    const migrationManager = this.partitionService.getMigrationManager();
+    if (migrationManager) {
+      migrationManager.setDataCollector(collector);
+    }
+  }
+  /**
+   * Set data storer for incoming migrations
+   */
+  setDataStorer(storer) {
+    const migrationManager = this.partitionService.getMigrationManager();
+    if (migrationManager) {
+      migrationManager.setDataStorer(storer);
+    }
+  }
+  // ============================================
+  // Replication Operations
+  // ============================================
+  /**
+   * Replicate an operation to backup nodes
+   */
+  async replicate(operation, opId, key, options = {}) {
+    if (!this.replicationPipeline) {
+      return { success: true, ackedBy: [] };
+    }
+    return this.replicationPipeline.replicate(operation, opId, key, options);
+  }
+  /**
+   * Get replication health status
+   */
+  getReplicationHealth() {
+    return this.lagTracker.getHealth();
+  }
+  /**
+   * Get replication lag for a specific node
+   */
+  getReplicationLag(nodeId) {
+    return this.lagTracker.getLag(nodeId);
+  }
+  /**
+   * Check if a node is healthy for replication
+   */
+  isNodeHealthy(nodeId) {
+    return this.lagTracker.isNodeHealthy(nodeId);
+  }
+  /**
+   * Check if a node is laggy
+   */
+  isNodeLaggy(nodeId) {
+    return this.lagTracker.isNodeLaggy(nodeId);
+  }
+  // ============================================
+  // Cluster Communication
+  // ============================================
+  /**
+   * Send message to a specific node
+   */
+  send(nodeId, message) {
+    this.clusterManager.sendToNode(nodeId, message);
+  }
+  /**
+   * Broadcast message to all nodes
+   */
+  broadcast(message) {
+    for (const nodeId of this.clusterManager.getMembers()) {
+      if (!this.clusterManager.isLocal(nodeId)) {
+        this.clusterManager.sendToNode(nodeId, message);
+      }
+    }
+  }
+  // ============================================
+  // Component Access
+  // ============================================
+  /**
+   * Get underlying ClusterManager
+   */
+  getClusterManager() {
+    return this.clusterManager;
+  }
+  /**
+   * Get underlying PartitionService
+   */
+  getPartitionService() {
+    return this.partitionService;
+  }
+  /**
+   * Get underlying ReplicationPipeline
+   */
+  getReplicationPipeline() {
+    return this.replicationPipeline;
+  }
+  /**
+   * Get underlying LagTracker
+   */
+  getLagTracker() {
+    return this.lagTracker;
+  }
+  // ============================================
+  // Metrics Export
+  // ============================================
+  /**
+   * Get all metrics in Prometheus format
+   */
+  getPrometheusMetrics() {
+    const lines = [];
+    lines.push("# HELP topgun_cluster_members Number of cluster members");
+    lines.push("# TYPE topgun_cluster_members gauge");
+    lines.push(`topgun_cluster_members ${this.clusterManager.getMembers().length}`);
+    lines.push("");
+    lines.push("# HELP topgun_cluster_started Cluster started status (1=started, 0=stopped)");
+    lines.push("# TYPE topgun_cluster_started gauge");
+    lines.push(`topgun_cluster_started ${this.started ? 1 : 0}`);
+    lines.push("");
+    lines.push("# HELP topgun_partition_map_version Current partition map version");
+    lines.push("# TYPE topgun_partition_map_version gauge");
+    lines.push(`topgun_partition_map_version ${this.partitionService.getMapVersion()}`);
+    const migrationMetrics = this.getMigrationMetrics();
+    if (migrationMetrics) {
+      lines.push("");
+      lines.push("# HELP topgun_migrations_started Total migrations started");
+      lines.push("# TYPE topgun_migrations_started counter");
+      lines.push(`topgun_migrations_started ${migrationMetrics.migrationsStarted}`);
+      lines.push("");
+      lines.push("# HELP topgun_migrations_completed Total migrations completed");
+      lines.push("# TYPE topgun_migrations_completed counter");
+      lines.push(`topgun_migrations_completed ${migrationMetrics.migrationsCompleted}`);
+      lines.push("");
+      lines.push("# HELP topgun_migrations_failed Total migrations failed");
+      lines.push("# TYPE topgun_migrations_failed counter");
+      lines.push(`topgun_migrations_failed ${migrationMetrics.migrationsFailed}`);
+      lines.push("");
+      lines.push("# HELP topgun_migrations_active Currently active migrations");
+      lines.push("# TYPE topgun_migrations_active gauge");
+      lines.push(`topgun_migrations_active ${migrationMetrics.activeMigrations}`);
+      lines.push("");
+      lines.push("# HELP topgun_migrations_queued Queued migrations");
+      lines.push("# TYPE topgun_migrations_queued gauge");
+      lines.push(`topgun_migrations_queued ${migrationMetrics.queuedMigrations}`);
+    }
+    lines.push("");
+    lines.push(this.lagTracker.toPrometheusMetrics());
+    return lines.join("\n");
+  }
+  // ============================================
+  // Private Methods
+  // ============================================
+  setupEventHandlers() {
+    this.clusterManager.on("memberJoined", (nodeId) => {
+      logger.info({ nodeId }, "Cluster member joined");
+      this.emit("member:joined", nodeId);
+    });
+    this.clusterManager.on("memberLeft", (nodeId) => {
+      logger.info({ nodeId }, "Cluster member left");
+      this.lagTracker.removeNode(nodeId);
+      this.emit("member:left", nodeId);
+    });
+    this.partitionService.on("rebalanced", (map, changes) => {
+      logger.info({ version: map.version, changesCount: changes.length }, "Partition map rebalanced");
+      this.emit("partition:rebalanced", map, changes);
+    });
+    this.partitionService.on("partitionMoved", (info) => {
+      this.emit("partition:moved", info);
+    });
+    const migrationManager = this.partitionService.getMigrationManager();
+    if (migrationManager) {
+      migrationManager.on("migrationStarted", (partitionId, targetNode) => {
+        this.emit("migration:started", partitionId, targetNode);
+      });
+      migrationManager.on("migrationComplete", (partitionId) => {
+        this.emit("migration:completed", partitionId);
+      });
+      migrationManager.on("migrationFailed", (partitionId, error) => {
+        this.emit("migration:failed", partitionId, error);
+      });
+    }
+    if (this.replicationPipeline) {
+      this.replicationPipeline.on("ackReceived", (nodeId) => {
+        this.lagTracker.recordAck(nodeId);
+      });
+      this.replicationPipeline.on("replicationSent", (nodeId) => {
+        this.lagTracker.incrementPending(nodeId);
+      });
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BufferPool,
+  ClusterCoordinator,
+  ClusterManager,
   ConnectionRateLimiter,
+  DEFAULT_CLUSTER_COORDINATOR_CONFIG,
+  DEFAULT_LAG_TRACKER_CONFIG,
   FilterTasklet,
   ForEachTasklet,
   IteratorTasklet,
+  LagTracker,
+  LockManager,
   MapTasklet,
   MemoryServerAdapter,
+  MigrationManager,
   ObjectPool,
+  PartitionService,
   PostgresAdapter,
   RateLimitInterceptor,
   ReduceTasklet,
+  ReplicationPipeline,
   SecurityManager,
   ServerCoordinator,
   TaskletScheduler,