@topgunbuild/server 0.2.1 → 0.3.0

package/dist/index.d.mts

@@ -1,7 +1,8 @@
-import { Timestamp, LWWRecord, ORMapRecord, Principal, PermissionPolicy, LWWMap, ORMap, PermissionType } from '@topgunbuild/core';
+import { Timestamp, LWWRecord, ORMapRecord, Principal, PermissionPolicy, ConsistencyLevel, ReplicationConfig, LWWMap, ORMap, PermissionType, MigrationConfig, MigrationStatus, MigrationMetrics, PartitionMap, PartitionInfo, PartitionChange, ReplicationLag, ReplicationHealth, ReplicationResult } from '@topgunbuild/core';
 import { WebSocket } from 'ws';
 import { PoolConfig, Pool } from 'pg';
 import pino from 'pino';
+import { EventEmitter } from 'events';
 
 /**
  * TaskletScheduler — Cooperative multitasking for long-running operations.
@@ -1601,16 +1602,30 @@ interface CoalescingWriterMetrics {
  * - Larger batch size = higher throughput, higher latency
  * - Longer delay = more messages per batch, higher latency
  * - Larger maxBatchBytes = handles larger payloads, more memory
+ *
+ * NOTE: A/B testing (Dec 2024) showed maxDelayMs is the primary bottleneck:
+ * - 10ms delay: ~10K ops/sec, p50=11ms
+ * - 1ms delay:  ~18K ops/sec, p50=8ms  (+80% throughput)
+ * - 0ms (disabled): ~18K ops/sec, p50=2ms (best latency)
  */
 declare const 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
+     */
+    readonly lowLatency: {
+        readonly maxBatchSize: 100;
+        readonly maxDelayMs: 1;
+        readonly maxBatchBytes: 65536;
+    };
+    /**
+     * Conservative - good balance of latency and batching.
+     * Use for: general purpose with latency sensitivity.
      */
     readonly conservative: {
         readonly maxBatchSize: 100;
-        readonly maxDelayMs: 5;
+        readonly maxDelayMs: 2;
         readonly maxBatchBytes: 65536;
     };
     /**
@@ -1620,17 +1635,18 @@ declare const coalescingPresets: {
      */
     readonly balanced: {
         readonly maxBatchSize: 300;
-        readonly maxDelayMs: 8;
+        readonly maxDelayMs: 2;
         readonly maxBatchBytes: 131072;
     };
     /**
      * 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
      */
     readonly highThroughput: {
         readonly maxBatchSize: 500;
-        readonly maxDelayMs: 10;
+        readonly maxDelayMs: 2;
         readonly maxBatchBytes: 262144;
     };
     /**
@@ -1640,7 +1656,7 @@ declare const coalescingPresets: {
      */
     readonly aggressive: {
         readonly maxBatchSize: 1000;
-        readonly maxDelayMs: 15;
+        readonly maxDelayMs: 5;
         readonly maxBatchBytes: 524288;
     };
 };
@@ -1721,6 +1737,12 @@ interface ServerCoordinatorConfig {
     workerPoolConfig?: Partial<WorkerPoolConfig>;
     /** Default timeout for Write Concern acknowledgments in ms (default: 5000) */
     writeAckTimeout?: number;
+    /** Enable replication to backup nodes (default: true when cluster has peers) */
+    replicationEnabled?: boolean;
+    /** Default consistency level for replication (default: EVENTUAL) */
+    defaultConsistency?: ConsistencyLevel;
+    /** Replication configuration */
+    replicationConfig?: Partial<ReplicationConfig>;
 }
 declare class ServerCoordinator {
     private httpServer;
@@ -1736,6 +1758,7 @@ declare class ServerCoordinator {
     private queryRegistry;
     private cluster;
     private partitionService;
+    private replicationPipeline?;
     private lockManager;
     private topicManager;
     private securityManager;
@@ -1803,6 +1826,11 @@ declare class ServerCoordinator {
     private handleConnection;
     private handleMessage;
     private updateClientHlc;
+    /**
+     * Broadcast partition map to all connected and authenticated clients.
+     * Called when partition topology changes (node join/leave/failover).
+     */
+    private broadcastPartitionMap;
     private broadcast;
     /**
      * === OPTIMIZATION 2 & 3: Batched Broadcast with Serialization Caching ===
@@ -1836,6 +1864,11 @@ declare class ServerCoordinator {
      * Broadcast event to cluster members (excluding self).
      */
     private broadcastToCluster;
+    /**
+     * Apply replicated operation from another node (callback for ReplicationPipeline)
+     * This is called when we receive a replicated operation as a backup node
+     */
+    private applyReplicatedOperation;
     /**
      * Build OpContext for interceptors.
      */
@@ -2147,4 +2180,872 @@ declare function getNativeStats(sharedMemoryManager?: SharedMemoryManager): Nati
  */
 declare function logNativeStatus(): void;
 
-export { BufferPool, type BufferPoolConfig, type BufferPoolStats, type CoalescingPreset, type CoalescingWriterMetrics, type CoalescingWriterOptions, type ConnectionContext, ConnectionRateLimiter, FilterTasklet, ForEachTasklet, type IInterceptor, type IServerStorage, IteratorTasklet, type IteratorTaskletConfig, type Logger, MapTasklet, MemoryServerAdapter, type NativeModuleStatus, type NativeStats, type ORMapTombstones, type ORMapValue, ObjectPool, type ObjectPoolConfig, type ObjectPoolStats, type OpContext, type PooledEventPayload, type PooledMessage, type PooledRecord, type PooledTimestamp, PostgresAdapter, type PostgresAdapterOptions, type ProgressState, RateLimitInterceptor, type RateLimiterConfig, type RateLimiterStats, ReduceTasklet, SecurityManager, ServerCoordinator, type ServerCoordinatorConfig, type ServerOp, type StorageValue, type Tasklet, TaskletScheduler, type TaskletSchedulerConfig, type TaskletSchedulerStats, TimestampInterceptor, coalescingPresets, createEventPayloadPool, createMessagePool, createRecordPool, createTimestampPool, getCoalescingPreset, getGlobalBufferPool, getGlobalEventPayloadPool, getGlobalMessagePool, getGlobalRecordPool, getGlobalTimestampPool, getNativeModuleStatus, getNativeStats, logNativeStatus, logger, setGlobalBufferPool, setGlobalEventPayloadPool, setGlobalMessagePool, setGlobalRecordPool, setGlobalTimestampPool };
+/**
+ * FailureDetector - Phi Accrual Failure Detector
+ *
+ * Implements the Phi Accrual Failure Detection algorithm for distributed systems.
+ * Based on the paper: "The φ Accrual Failure Detector" by Hayashibara et al.
+ *
+ * The detector provides a suspicion level (phi) rather than binary alive/dead status,
+ * allowing the application to make decisions based on configurable thresholds.
+ *
+ * Hazelcast equivalent: com.hazelcast.internal.cluster.fd.PhiAccrualFailureDetector
+ */
+
+interface FailureDetectorConfig {
+    /** Interval between heartbeat checks (ms). Default: 1000 */
+    heartbeatIntervalMs: number;
+    /** Time after which a node is suspected if no heartbeat received (ms). Default: 5000 */
+    suspicionTimeoutMs: number;
+    /** Time after suspicion before confirming failure (ms). Default: 10000 */
+    confirmationTimeoutMs: number;
+    /** Phi threshold above which a node is considered suspected. Default: 8 */
+    phiThreshold: number;
+    /** Minimum samples required for accurate phi calculation. Default: 10 */
+    minSamples: number;
+    /** Maximum samples to keep in history. Default: 100 */
+    maxSamples: number;
+    /** Initial heartbeat interval estimate (ms). Default: 1000 */
+    initialHeartbeatIntervalMs: number;
+}
+declare class FailureDetector extends EventEmitter {
+    private config;
+    private nodeStates;
+    private monitoringNodes;
+    private checkTimer?;
+    private confirmationTimers;
+    private started;
+    constructor(config?: Partial<FailureDetectorConfig>);
+    /**
+     * Start the failure detector monitoring loop.
+     */
+    start(): void;
+    /**
+     * Stop the failure detector and clean up.
+     */
+    stop(): void;
+    /**
+     * Start monitoring a node.
+     */
+    startMonitoring(nodeId: string): void;
+    /**
+     * Stop monitoring a node.
+     */
+    stopMonitoring(nodeId: string): void;
+    /**
+     * Record a heartbeat from a node.
+     * This updates the node's state and clears any suspicion.
+     */
+    recordHeartbeat(nodeId: string): void;
+    /**
+     * Check all monitored nodes for failure.
+     */
+    private checkAllNodes;
+    /**
+     * Schedule failure confirmation after suspicion timeout.
+     */
+    private scheduleConfirmation;
+    /**
+     * Confirm node failure after confirmation timeout.
+     */
+    private confirmFailure;
+    /**
+     * 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: string): number;
+    /**
+     * Calculate mean of an array of numbers.
+     */
+    private calculateMean;
+    /**
+     * Calculate variance of an array of numbers.
+     */
+    private calculateVariance;
+    /**
+     * Get list of currently suspected nodes.
+     */
+    getSuspectedNodes(): string[];
+    /**
+     * Get list of confirmed failed nodes.
+     */
+    getConfirmedFailedNodes(): string[];
+    /**
+     * Check if a specific node is suspected.
+     */
+    isSuspected(nodeId: string): boolean;
+    /**
+     * Check if a specific node's failure is confirmed.
+     */
+    isConfirmedFailed(nodeId: string): boolean;
+    /**
+     * Get the current phi value for a node.
+     */
+    getPhi(nodeId: string): number;
+    /**
+     * Get all monitored nodes.
+     */
+    getMonitoredNodes(): string[];
+    /**
+     * Get metrics for monitoring.
+     */
+    getMetrics(): {
+        monitoredNodes: number;
+        suspectedNodes: number;
+        confirmedFailedNodes: number;
+    };
+}
+
+interface ClusterConfig {
+    nodeId: string;
+    host: string;
+    port: number;
+    peers: string[];
+    discovery?: 'manual' | 'kubernetes';
+    serviceName?: string;
+    discoveryInterval?: number;
+    tls?: ClusterTLSConfig;
+    /** Heartbeat interval in milliseconds. Default: 1000 */
+    heartbeatIntervalMs?: number;
+    /** Failure detection configuration */
+    failureDetection?: Partial<FailureDetectorConfig>;
+}
+interface ClusterMember {
+    nodeId: string;
+    host: string;
+    port: number;
+    socket: WebSocket;
+    isSelf: boolean;
+}
+interface ClusterMessage {
+    type: 'HELLO' | 'OP_FORWARD' | 'PARTITION_UPDATE' | 'HEARTBEAT' | 'CLUSTER_EVENT' | 'CLUSTER_QUERY_EXEC' | 'CLUSTER_QUERY_RESP' | 'CLUSTER_GC_REPORT' | 'CLUSTER_GC_COMMIT' | 'CLUSTER_LOCK_REQ' | 'CLUSTER_LOCK_RELEASE' | 'CLUSTER_LOCK_GRANTED' | 'CLUSTER_LOCK_RELEASED' | 'CLUSTER_CLIENT_DISCONNECTED' | 'CLUSTER_TOPIC_PUB';
+    senderId: string;
+    payload: any;
+}
+declare class ClusterManager extends EventEmitter {
+    readonly config: ClusterConfig;
+    private server?;
+    private members;
+    private pendingConnections;
+    private reconnectIntervals;
+    private discoveryTimer?;
+    private heartbeatTimer?;
+    private failureDetector;
+    constructor(config: ClusterConfig);
+    /**
+     * Get the failure detector instance.
+     */
+    getFailureDetector(): FailureDetector;
+    private _actualPort;
+    /** Get the actual port the cluster is listening on */
+    get port(): number;
+    start(): Promise<number>;
+    /** Called when server is ready - registers self and initiates peer connections */
+    private onServerReady;
+    stop(): void;
+    /**
+     * Start sending heartbeats to all peers.
+     */
+    private startHeartbeat;
+    /**
+     * Stop sending heartbeats.
+     */
+    private stopHeartbeat;
+    /**
+     * Send heartbeat to all connected peers.
+     */
+    private sendHeartbeatToAll;
+    /**
+     * Handle incoming heartbeat from a peer.
+     */
+    private handleHeartbeat;
+    /**
+     * Handle confirmed node failure.
+     */
+    private handleNodeFailure;
+    private connectToPeers;
+    private startDiscovery;
+    private scheduleReconnect;
+    private connectToPeerWithBackoff;
+    private connectToPeer;
+    private _connectToPeerInternal;
+    private handleSocket;
+    send(nodeId: string, type: ClusterMessage['type'], payload: any): void;
+    sendToNode(nodeId: string, message: any): void;
+    getMembers(): string[];
+    isLocal(nodeId: string): boolean;
+    private buildClusterTLSOptions;
+}
+
+/**
+ * MigrationManager - Manages gradual partition rebalancing
+ *
+ * Phase 4 Task 03: Parallel Partition Sync
+ *
+ * Features:
+ * - Gradual rebalancing with configurable batch size
+ * - State machine for migration lifecycle
+ * - Backpressure via chunk acknowledgments
+ * - Retry logic for failed migrations
+ * - Metrics and observability
+ */
+
+declare class MigrationManager extends EventEmitter {
+    private readonly config;
+    private readonly clusterManager;
+    private readonly partitionService;
+    private activeMigrations;
+    private migrationQueue;
+    private incomingMigrations;
+    private pendingChunkAcks;
+    private pendingVerifications;
+    private metrics;
+    private batchTimer;
+    private dataCollector;
+    private dataStorer;
+    constructor(clusterManager: ClusterManager, partitionService: PartitionService, config?: Partial<MigrationConfig>);
+    /**
+     * Set the data collector callback
+     * Called to collect all records for a partition before migration
+     */
+    setDataCollector(collector: (partitionId: number) => Promise<Uint8Array[]>): void;
+    /**
+     * Set the data storer callback
+     * Called to store received records after successful migration
+     */
+    setDataStorer(storer: (partitionId: number, data: Uint8Array[]) => Promise<void>): void;
+    /**
+     * Plan migration for topology change
+     */
+    planMigration(oldDistribution: Map<number, PartitionDistribution>, newDistribution: Map<number, PartitionDistribution>): void;
+    /**
+     * Start batch processing timer
+     */
+    private startBatchProcessing;
+    /**
+     * Stop batch processing
+     */
+    private stopBatchProcessing;
+    /**
+     * Start next batch of migrations
+     */
+    startNextBatch(): Promise<void>;
+    /**
+     * Start migration for a single partition
+     */
+    private startPartitionMigration;
+    /**
+     * Split records into chunks
+     */
+    private chunkify;
+    /**
+     * Calculate checksum for a chunk using native xxhash
+     */
+    private calculateChecksum;
+    /**
+     * Calculate checksum for all partition records using streaming xxhash
+     */
+    private calculatePartitionChecksum;
+    /**
+     * Wait for chunk acknowledgment
+     */
+    private waitForChunkAck;
+    /**
+     * Wait for migration verification
+     */
+    private waitForVerification;
+    /**
+     * Handle successful migration completion
+     */
+    private onMigrationComplete;
+    /**
+     * Handle migration failure
+     */
+    private onMigrationFailed;
+    /**
+     * Handle MIGRATION_START message
+     */
+    private handleMigrationStart;
+    /**
+     * Handle MIGRATION_CHUNK message
+     */
+    private handleMigrationChunk;
+    /**
+     * Handle MIGRATION_COMPLETE message
+     */
+    private handleMigrationComplete;
+    /**
+     * Handle MIGRATION_CHUNK_ACK message
+     */
+    private handleMigrationChunkAck;
+    /**
+     * Handle MIGRATION_VERIFY message
+     */
+    private handleMigrationVerify;
+    /**
+     * Reassemble chunks into continuous data
+     */
+    private reassemble;
+    /**
+     * Deserialize records from chunk data
+     */
+    private deserializeRecords;
+    /**
+     * Setup cluster message handlers
+     */
+    private setupMessageHandlers;
+    /**
+     * Check if a partition is currently migrating
+     */
+    isActive(partitionId: number): boolean;
+    /**
+     * Get migration status
+     */
+    getStatus(): MigrationStatus;
+    /**
+     * Get migration metrics
+     */
+    getMetrics(): MigrationMetrics;
+    /**
+     * Cancel all active and queued migrations
+     */
+    cancelAll(): Promise<void>;
+    /**
+     * Cleanup resources (sync version for backwards compatibility)
+     */
+    close(): void;
+    /**
+     * Async cleanup - waits for cancellation to complete
+     */
+    closeAsync(): Promise<void>;
+}
+
+interface PartitionDistribution {
+    owner: string;
+    backups: string[];
+}
+interface PartitionServiceEvents {
+    'rebalanced': (map: PartitionMap, changes: PartitionChange[]) => void;
+    'partitionMoved': (info: {
+        partitionId: number;
+        previousOwner: string;
+        newOwner: string;
+        version: number;
+    }) => void;
+}
+interface PartitionServiceConfig {
+    /** Enable gradual rebalancing (default: false for backward compatibility) */
+    gradualRebalancing: boolean;
+    /** Migration configuration */
+    migration: Partial<MigrationConfig>;
+}
+declare class PartitionService extends EventEmitter {
+    private cluster;
+    private partitions;
+    private readonly PARTITION_COUNT;
+    private readonly BACKUP_COUNT;
+    private mapVersion;
+    private lastRebalanceTime;
+    private config;
+    private migrationManager;
+    constructor(cluster: ClusterManager, config?: Partial<PartitionServiceConfig>);
+    /**
+     * Handle membership change
+     */
+    private onMembershipChange;
+    getPartitionId(key: string): number;
+    getDistribution(key: string): PartitionDistribution;
+    getOwner(key: string): string;
+    isLocalOwner(key: string): boolean;
+    isLocalBackup(key: string): boolean;
+    isRelated(key: string): boolean;
+    /**
+     * Get current partition map version
+     */
+    getMapVersion(): number;
+    /**
+     * Generate full PartitionMap for client consumption
+     */
+    getPartitionMap(): PartitionMap;
+    /**
+     * Get partition info by ID
+     */
+    getPartitionInfo(partitionId: number): PartitionInfo | null;
+    /**
+     * Get owner node for a partition ID
+     */
+    getPartitionOwner(partitionId: number): string | null;
+    private rebalance;
+    /**
+     * Perform gradual rebalancing using MigrationManager
+     */
+    private rebalanceGradual;
+    /**
+     * Set partition owner (called after migration completes)
+     */
+    setOwner(partitionId: number, nodeId: string): void;
+    /**
+     * Get backups for a partition
+     */
+    getBackups(partitionId: number): string[];
+    /**
+     * Get migration status
+     */
+    getMigrationStatus(): MigrationStatus | null;
+    /**
+     * Check if partition is currently migrating
+     */
+    isMigrating(partitionId: number): boolean;
+    /**
+     * Check if any partition is currently migrating
+     */
+    isRebalancing(): boolean;
+    /**
+     * Get MigrationManager for configuration
+     */
+    getMigrationManager(): MigrationManager | null;
+    /**
+     * Cancel all migrations
+     */
+    cancelMigrations(): Promise<void>;
+}
+
+/**
+ * LagTracker - Monitors replication lag across cluster nodes
+ *
+ * Phase 4 Task 04: Async Replication Pipeline
+ *
+ * Features:
+ * - Tracks replication lag per node
+ * - Maintains historical lag data for percentile calculations
+ * - Identifies unhealthy and laggy nodes
+ * - Provides health metrics for monitoring
+ */
+
+interface LagInfo {
+    current: number;
+    history: number[];
+    lastUpdate: number;
+    pendingOps: number;
+}
+interface LagTrackerConfig {
+    /** Number of lag samples to keep in history (default: 100) */
+    historySize: number;
+    /** Threshold in ms for considering a node laggy (default: 5000) */
+    laggyThresholdMs: number;
+    /** Threshold in ms for considering a node unhealthy (default: 30000) */
+    unhealthyThresholdMs: number;
+}
+declare const DEFAULT_LAG_TRACKER_CONFIG: LagTrackerConfig;
+declare class LagTracker {
+    private readonly config;
+    private lagByNode;
+    constructor(config?: Partial<LagTrackerConfig>);
+    /**
+     * Update lag measurement for a node
+     */
+    update(nodeId: string, lagMs: number): void;
+    /**
+     * Record acknowledgment from a node (lag effectively becomes 0)
+     */
+    recordAck(nodeId: string): void;
+    /**
+     * Increment pending operations counter for a node
+     */
+    incrementPending(nodeId: string): void;
+    /**
+     * Get lag statistics for a specific node
+     */
+    getLag(nodeId: string): ReplicationLag;
+    /**
+     * Get pending operations count for a node
+     */
+    getPendingOps(nodeId: string): number;
+    /**
+     * Get overall replication health status
+     */
+    getHealth(): ReplicationHealth;
+    /**
+     * Get average lag across all tracked nodes
+     */
+    getAverageLag(): number;
+    /**
+     * Check if a specific node is considered healthy
+     */
+    isNodeHealthy(nodeId: string): boolean;
+    /**
+     * Check if a specific node is considered laggy
+     */
+    isNodeLaggy(nodeId: string): boolean;
+    /**
+     * Remove a node from tracking
+     */
+    removeNode(nodeId: string): void;
+    /**
+     * Get all tracked node IDs
+     */
+    getTrackedNodes(): string[];
+    /**
+     * Get raw lag info for a node (for advanced monitoring)
+     */
+    getRawLagInfo(nodeId: string): LagInfo | undefined;
+    /**
+     * Clear all tracking data
+     */
+    clear(): void;
+    /**
+     * Export metrics in Prometheus format
+     */
+    toPrometheusMetrics(): string;
+}
+
+/**
+ * ReplicationPipeline - Manages async replication with configurable consistency levels
+ *
+ * Phase 4 Task 04: Async Replication Pipeline
+ *
+ * Features:
+ * - Three consistency levels: STRONG, QUORUM, EVENTUAL
+ * - Async replication queue for high throughput
+ * - Backpressure handling with queue limits
+ * - Retry logic for failed replications
+ * - Integration with LagTracker for monitoring
+ * - Pluggable operation applier for storage integration
+ */
+
+/**
+ * Callback to apply replicated operation to local storage
+ * @param operation - The operation to apply
+ * @param opId - Unique operation ID
+ * @param sourceNode - Node that originated the operation
+ * @returns Promise<boolean> - true if applied successfully
+ */
+type OperationApplier = (operation: unknown, opId: string, sourceNode: string) => Promise<boolean>;
+declare class ReplicationPipeline extends EventEmitter {
+    private readonly config;
+    private readonly clusterManager;
+    private readonly partitionService;
+    private readonly lagTracker;
+    private readonly nodeId;
+    private replicationQueue;
+    private pendingAcks;
+    private queueProcessorTimer;
+    private operationApplier;
+    constructor(clusterManager: ClusterManager, partitionService: PartitionService, config?: Partial<ReplicationConfig>);
+    /**
+     * Set the operation applier callback
+     * This is called when replicated operations are received from other nodes
+     */
+    setOperationApplier(applier: OperationApplier): void;
+    /**
+     * Replicate operation to backup nodes
+     */
+    replicate(operation: unknown, opId: string, key: string, options?: {
+        consistency?: ConsistencyLevel;
+        timeout?: number;
+    }): Promise<ReplicationResult>;
+    /**
+     * STRONG: Wait for all replicas to acknowledge
+     */
+    private replicateStrong;
+    /**
+     * QUORUM: Wait for majority of replicas
+     */
+    private replicateQuorum;
+    /**
+     * EVENTUAL: Fire-and-forget with queue
+     */
+    private replicateEventual;
+    /**
+     * Add task to replication queue
+     */
+    private enqueue;
+    /**
+     * Start queue processor
+     */
+    private startQueueProcessor;
+    /**
+     * Stop queue processor
+     */
+    private stopQueueProcessor;
+    /**
+     * Process replication queue for a node
+     */
+    private processQueue;
+    /**
+     * Send replication message to a node
+     */
+    private sendReplication;
+    /**
+     * Setup cluster message handlers
+     */
+    private setupMessageHandlers;
+    /**
+     * Handle incoming replication request (on backup node)
+     */
+    private handleReplication;
+    /**
+     * Handle incoming batch replication (on backup node)
+     */
+    private handleReplicationBatch;
+    /**
+     * Handle replication acknowledgment (on owner node)
+     */
+    private handleReplicationAck;
+    /**
+     * Handle batch acknowledgment (on owner node)
+     */
+    private handleReplicationBatchAck;
+    /**
+     * Get replication lag for a specific node
+     */
+    getLag(nodeId: string): ReplicationLag;
+    /**
+     * Get overall replication health
+     */
+    getHealth(): ReplicationHealth;
+    /**
+     * Get queue size for a specific node
+     */
+    getQueueSize(nodeId: string): number;
+    /**
+     * Get total pending operations across all nodes
+     */
+    getTotalPending(): number;
+    /**
+     * Check if a node is considered synced (low lag)
+     */
+    isSynced(nodeId: string, maxLagMs?: number): boolean;
+    /**
+     * Get LagTracker for advanced monitoring
+     */
+    getLagTracker(): LagTracker;
+    /**
+     * Export metrics in Prometheus format
+     */
+    toPrometheusMetrics(): string;
+    /**
+     * Cleanup resources
+     */
+    close(): void;
+}
+
+declare class LockManager extends EventEmitter {
+    private locks;
+    private checkInterval;
+    private static readonly MIN_TTL;
+    private static readonly MAX_TTL;
+    constructor();
+    stop(): void;
+    acquire(name: string, clientId: string, requestId: string, ttl: number): {
+        granted: boolean;
+        fencingToken?: number;
+        error?: string;
+    };
+    release(name: string, clientId: string, fencingToken: number): boolean;
+    handleClientDisconnect(clientId: string): void;
+    private grantLock;
+    private processNext;
+    private cleanupExpiredLocks;
+}
+
+/**
+ * ClusterCoordinator - Unified cluster integration layer
+ *
+ * Phase 4 Task 06: System Integration
+ *
+ * Coordinates all cluster components:
+ * - ClusterManager: P2P WebSocket mesh
+ * - PartitionService: Consistent hashing & routing
+ * - MigrationManager: Gradual rebalancing
+ * - ReplicationPipeline: Async replication with consistency levels
+ * - LagTracker: Replication health monitoring
+ */
+
+interface ClusterCoordinatorConfig {
+    /** Cluster node configuration */
+    cluster: ClusterConfig;
+    /** Enable gradual partition rebalancing (default: true) */
+    gradualRebalancing: boolean;
+    /** Migration configuration for gradual rebalancing */
+    migration: Partial<MigrationConfig>;
+    /** Replication configuration */
+    replication: Partial<ReplicationConfig>;
+    /** Enable async replication pipeline (default: true) */
+    replicationEnabled: boolean;
+    /** Data collector callback for migrations */
+    dataCollector?: (partitionId: number) => Promise<Uint8Array[]>;
+    /** Data storer callback for incoming migrations */
+    dataStorer?: (partitionId: number, data: Uint8Array[]) => Promise<void>;
+}
+declare const DEFAULT_CLUSTER_COORDINATOR_CONFIG: Omit<ClusterCoordinatorConfig, 'cluster'>;
+interface ClusterCoordinatorEvents {
+    'started': () => void;
+    'stopped': () => void;
+    'member:joined': (nodeId: string) => void;
+    'member:left': (nodeId: string) => void;
+    'partition:rebalanced': (map: PartitionMap, changes: PartitionChange[]) => void;
+    'partition:moved': (info: {
+        partitionId: number;
+        previousOwner: string;
+        newOwner: string;
+        version: number;
+    }) => void;
+    'migration:started': (partitionId: number, targetNode: string) => void;
+    'migration:completed': (partitionId: number) => void;
+    'migration:failed': (partitionId: number, error: Error) => void;
+    'replication:unhealthy': (nodeId: string) => void;
+    'replication:healthy': (nodeId: string) => void;
+    'error': (error: Error) => void;
+}
+declare class ClusterCoordinator extends EventEmitter {
+    private readonly config;
+    private clusterManager;
+    private partitionService;
+    private replicationPipeline;
+    private lagTracker;
+    private started;
+    private actualPort;
+    constructor(config: ClusterCoordinatorConfig);
+    /**
+     * Start the cluster coordinator
+     */
+    start(): Promise<number>;
+    /**
+     * Stop the cluster coordinator
+     */
+    stop(): Promise<void>;
+    /**
+     * Get local node ID
+     */
+    getNodeId(): string;
+    /**
+     * Get cluster port
+     */
+    getPort(): number;
+    /**
+     * Get all cluster members
+     */
+    getMembers(): string[];
+    /**
+     * Check if this is the local node
+     */
+    isLocal(nodeId: string): boolean;
+    /**
+     * Check if coordinator is started
+     */
+    isStarted(): boolean;
+    /**
+     * Get current partition map
+     */
+    getPartitionMap(): PartitionMap;
+    /**
+     * Get partition map version
+     */
+    getPartitionMapVersion(): number;
+    /**
+     * Get partition ID for a key
+     */
+    getPartitionId(key: string): number;
+    /**
+     * Get owner node for a key
+     */
+    getOwner(key: string): string;
+    /**
+     * Check if this node owns the key
+     */
+    isLocalOwner(key: string): boolean;
+    /**
+     * Check if this node is a backup for the key
+     */
+    isLocalBackup(key: string): boolean;
+    /**
+     * Get backup nodes for a partition
+     */
+    getBackups(partitionId: number): string[];
+    /**
+     * Check if partition is currently migrating
+     */
+    isMigrating(partitionId: number): boolean;
+    /**
+     * Check if any rebalancing is in progress
+     */
+    isRebalancing(): boolean;
+    /**
+     * Get migration status
+     */
+    getMigrationStatus(): MigrationStatus | null;
+    /**
+     * Get migration metrics
+     */
+    getMigrationMetrics(): MigrationMetrics | null;
+    /**
+     * Cancel all active migrations
+     */
+    cancelMigrations(): Promise<void>;
+    /**
+     * Set data collector for migrations
+     */
+    setDataCollector(collector: (partitionId: number) => Promise<Uint8Array[]>): void;
+    /**
+     * Set data storer for incoming migrations
+     */
+    setDataStorer(storer: (partitionId: number, data: Uint8Array[]) => Promise<void>): void;
+    /**
+     * Replicate an operation to backup nodes
+     */
+    replicate(operation: unknown, opId: string, key: string, options?: {
+        consistency?: ConsistencyLevel;
+        timeout?: number;
+    }): Promise<ReplicationResult>;
+    /**
+     * Get replication health status
+     */
+    getReplicationHealth(): ReplicationHealth;
+    /**
+     * Get replication lag for a specific node
+     */
+    getReplicationLag(nodeId: string): ReplicationLag;
+    /**
+     * Check if a node is healthy for replication
+     */
+    isNodeHealthy(nodeId: string): boolean;
+    /**
+     * Check if a node is laggy
+     */
+    isNodeLaggy(nodeId: string): boolean;
+    /**
+     * Send message to a specific node
+     */
+    send(nodeId: string, message: unknown): void;
+    /**
+     * Broadcast message to all nodes
+     */
+    broadcast(message: unknown): void;
+    /**
+     * Get underlying ClusterManager
+     */
+    getClusterManager(): ClusterManager;
+    /**
+     * Get underlying PartitionService
+     */
+    getPartitionService(): PartitionService;
+    /**
+     * Get underlying ReplicationPipeline
+     */
+    getReplicationPipeline(): ReplicationPipeline | null;
+    /**
+     * Get underlying LagTracker
+     */
+    getLagTracker(): LagTracker;
+    /**
+     * Get all metrics in Prometheus format
+     */
+    getPrometheusMetrics(): string;
+    private setupEventHandlers;
+}
+
+export { BufferPool, type BufferPoolConfig, type BufferPoolStats, type ClusterConfig, ClusterCoordinator, type ClusterCoordinatorConfig, type ClusterCoordinatorEvents, ClusterManager, type ClusterMember, type ClusterMessage, type CoalescingPreset, type CoalescingWriterMetrics, type CoalescingWriterOptions, type ConnectionContext, ConnectionRateLimiter, DEFAULT_CLUSTER_COORDINATOR_CONFIG, DEFAULT_LAG_TRACKER_CONFIG, FilterTasklet, ForEachTasklet, type IInterceptor, type IServerStorage, IteratorTasklet, type IteratorTaskletConfig, type LagInfo, LagTracker, type LagTrackerConfig, LockManager, type Logger, MapTasklet, MemoryServerAdapter, MigrationManager, type NativeModuleStatus, type NativeStats, type ORMapTombstones, type ORMapValue, ObjectPool, type ObjectPoolConfig, type ObjectPoolStats, type OpContext, type PartitionDistribution, PartitionService, type PartitionServiceConfig, type PartitionServiceEvents, type PooledEventPayload, type PooledMessage, type PooledRecord, type PooledTimestamp, PostgresAdapter, type PostgresAdapterOptions, type ProgressState, RateLimitInterceptor, type RateLimiterConfig, type RateLimiterStats, ReduceTasklet, ReplicationPipeline, SecurityManager, ServerCoordinator, type ServerCoordinatorConfig, type ServerOp, type StorageValue, type Tasklet, TaskletScheduler, type TaskletSchedulerConfig, type TaskletSchedulerStats, TimestampInterceptor, coalescingPresets, createEventPayloadPool, createMessagePool, createRecordPool, createTimestampPool, getCoalescingPreset, getGlobalBufferPool, getGlobalEventPayloadPool, getGlobalMessagePool, getGlobalRecordPool, getGlobalTimestampPool, getNativeModuleStatus, getNativeStats, logNativeStatus, logger, setGlobalBufferPool, setGlobalEventPayloadPool, setGlobalMessagePool, setGlobalRecordPool, setGlobalTimestampPool };