@topgunbuild/server 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { Timestamp, LWWRecord, ORMapRecord, Principal, PermissionPolicy, LWWMap, ORMap, PermissionType } from '@topgunbuild/core';
+import * as _topgunbuild_core from '@topgunbuild/core';
+import { Timestamp, LWWRecord, ORMapRecord, Principal, EventJournalImpl, EventJournalConfig, JournalEvent, PermissionPolicy, ConsistencyLevel, ReplicationConfig, LWWMap, ORMap, PermissionType, MigrationConfig, MigrationStatus, MigrationMetrics, PartitionMap, PartitionInfo, PartitionChange, ReplicationLag, ReplicationHealth, ReplicationResult, EntryProcessorDef, EntryProcessorResult, HLC, MergeRejection, ConflictResolverDef, MergeContext, MergeResult } from '@topgunbuild/core';
 import { WebSocket } from 'ws';
-import { PoolConfig, Pool } from 'pg';
+import { Pool, PoolConfig } from 'pg';
 import pino from 'pino';
+import { EventEmitter } from 'events';
 
 /**
  * TaskletScheduler — Cooperative multitasking for long-running operations.
@@ -1601,16 +1603,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 +1636,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 +1657,7 @@ declare const coalescingPresets: {
      */
     readonly aggressive: {
         readonly maxBatchSize: 1000;
-        readonly maxDelayMs: 15;
+        readonly maxDelayMs: 5;
         readonly maxBatchBytes: 524288;
     };
 };
@@ -1655,6 +1672,116 @@ type CoalescingPreset = keyof typeof coalescingPresets;
  */
 declare function getCoalescingPreset(preset: CoalescingPreset): CoalescingWriterOptions;
 
+/**
+ * Export options for streaming journal events.
+ */
+interface ExportOptions {
+    /** Start from this sequence (inclusive) */
+    fromSequence?: bigint;
+    /** End at this sequence (inclusive) */
+    toSequence?: bigint;
+    /** Filter by map name */
+    mapName?: string;
+    /** Filter by event types */
+    types?: ('PUT' | 'UPDATE' | 'DELETE')[];
+}
+/**
+ * Configuration for EventJournalService.
+ */
+interface EventJournalServiceConfig extends EventJournalConfig {
+    /** PostgreSQL connection pool */
+    pool: Pool;
+    /** Table name for journal storage */
+    tableName?: string;
+    /** Batch size for persistence */
+    persistBatchSize?: number;
+    /** Interval for periodic persistence (ms) */
+    persistIntervalMs?: number;
+}
+/**
+ * Default configuration for EventJournalService.
+ */
+declare const DEFAULT_JOURNAL_SERVICE_CONFIG: Omit<EventJournalServiceConfig, 'pool'>;
+/**
+ * Server-side Event Journal Service with PostgreSQL persistence.
+ * Extends EventJournalImpl to add durable storage.
+ */
+declare class EventJournalService extends EventJournalImpl {
+    private readonly pool;
+    private readonly tableName;
+    private readonly persistBatchSize;
+    private readonly persistIntervalMs;
+    private pendingPersist;
+    private persistTimer?;
+    private isPersisting;
+    private isInitialized;
+    private isLoadingFromStorage;
+    constructor(config: EventJournalServiceConfig);
+    /**
+     * Initialize the journal service, creating table if needed.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Persist pending events to PostgreSQL.
+     */
+    persistToStorage(): Promise<void>;
+    /**
+     * Load journal events from PostgreSQL on startup.
+     */
+    loadFromStorage(): Promise<void>;
+    /**
+     * Export events as NDJSON stream.
+     */
+    exportStream(options?: ExportOptions): ReadableStream<string>;
+    /**
+     * Get events for a specific map.
+     */
+    getMapEvents(mapName: string, fromSeq?: bigint): JournalEvent[];
+    /**
+     * Query events from PostgreSQL with filters.
+     */
+    queryFromStorage(options?: {
+        mapName?: string;
+        key?: string;
+        types?: ('PUT' | 'UPDATE' | 'DELETE')[];
+        fromSequence?: bigint;
+        toSequence?: bigint;
+        fromDate?: Date;
+        toDate?: Date;
+        limit?: number;
+        offset?: number;
+    }): Promise<JournalEvent[]>;
+    /**
+     * Count events matching filters.
+     */
+    countFromStorage(options?: {
+        mapName?: string;
+        types?: ('PUT' | 'UPDATE' | 'DELETE')[];
+        fromDate?: Date;
+        toDate?: Date;
+    }): Promise<number>;
+    /**
+     * Cleanup old events based on retention policy.
+     */
+    cleanupOldEvents(retentionDays: number): Promise<number>;
+    /**
+     * Start the periodic persistence timer.
+     */
+    private startPersistTimer;
+    /**
+     * Stop the periodic persistence timer.
+     */
+    private stopPersistTimer;
+    /**
+     * Dispose resources and persist remaining events.
+     */
+    dispose(): void;
+    /**
+     * Get pending persist count (for monitoring).
+     */
+    getPendingPersistCount(): number;
+}
+
 interface ServerCoordinatorConfig {
     port: number;
     nodeId: string;
@@ -1721,6 +1848,16 @@ 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>;
+    /** Enable event journal for audit/CDC (default: false) */
+    eventJournalEnabled?: boolean;
+    /** Event journal configuration */
+    eventJournalConfig?: Partial<Omit<EventJournalServiceConfig, 'pool'>>;
 }
 declare class ServerCoordinator {
     private httpServer;
@@ -1736,6 +1873,7 @@ declare class ServerCoordinator {
     private queryRegistry;
     private cluster;
     private partitionService;
+    private replicationPipeline?;
     private lockManager;
     private topicManager;
     private securityManager;
@@ -1759,6 +1897,12 @@ declare class ServerCoordinator {
     private eventPayloadPool;
     private taskletScheduler;
     private writeAckManager;
+    private counterHandler;
+    private entryProcessorHandler;
+    private conflictResolverHandler;
+    private eventJournalService?;
+    private journalSubscriptions;
+    private readonly _nodeId;
     private _actualPort;
     private _actualClusterPort;
     private _readyPromise;
@@ -1803,6 +1947,16 @@ 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;
+    /**
+     * Notify a client about a merge rejection (Phase 5.05).
+     * Finds the client by node ID and sends MERGE_REJECTED message.
+     */
+    private notifyMergeRejection;
     private broadcast;
     /**
      * === OPTIMIZATION 2 & 3: Batched Broadcast with Serialization Caching ===
@@ -1836,6 +1990,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 +2306,1386 @@ 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;
+}
+
+/**
+ * Configuration for the processor sandbox.
+ */
+interface ProcessorSandboxConfig {
+    /** Memory limit in MB per isolate */
+    memoryLimitMb: number;
+    /** Execution timeout in milliseconds */
+    timeoutMs: number;
+    /** Maximum number of cached isolates */
+    maxCachedIsolates: number;
+    /** Enable strict code validation */
+    strictValidation: boolean;
+}
+/**
+ * Default sandbox configuration.
+ */
+declare const DEFAULT_SANDBOX_CONFIG: ProcessorSandboxConfig;
+/**
+ * Sandbox for executing entry processor code securely.
+ *
+ * Uses isolated-vm for production environments with:
+ * - Memory limits to prevent memory bombs
+ * - CPU limits via timeout to prevent infinite loops
+ * - No I/O access (no require, fs, net, etc.)
+ * - Minimal exposed globals (only value, key, args)
+ *
+ * Falls back to Node.js vm module for development/testing
+ * when isolated-vm is not available.
+ */
+declare class ProcessorSandbox {
+    private config;
+    private isolateCache;
+    private scriptCache;
+    private fallbackScriptCache;
+    private disposed;
+    constructor(config?: Partial<ProcessorSandboxConfig>);
+    /**
+     * Execute an entry processor in the sandbox.
+     *
+     * @param processor The processor definition (name, code, args)
+     * @param value The current value for the key (or undefined)
+     * @param key The key being processed
+     * @returns Result containing success status, result, and new value
+     */
+    execute<V, R>(processor: EntryProcessorDef<V, R>, value: V | undefined, key: string): Promise<EntryProcessorResult<R>>;
+    /**
+     * Execute processor in isolated-vm (secure production mode).
+     */
+    private executeInIsolate;
+    /**
+     * Execute processor in fallback VM (less secure, for development).
+     */
+    private executeInFallback;
+    /**
+     * Get or create an isolate for a processor.
+     */
+    private getOrCreateIsolate;
+    /**
+     * Get or compile a script for a processor.
+     */
+    private getOrCompileScript;
+    /**
+     * Clear script cache for a specific processor (e.g., when code changes).
+     */
+    clearCache(processorName?: string): void;
+    /**
+     * Check if using secure isolated-vm mode.
+     */
+    isSecureMode(): boolean;
+    /**
+     * Get current cache sizes.
+     */
+    getCacheStats(): {
+        isolates: number;
+        scripts: number;
+        fallbackScripts: number;
+    };
+    /**
+     * Dispose of all isolates and clear caches.
+     */
+    dispose(): void;
+}
+
+/**
+ * Configuration for the EntryProcessorHandler.
+ */
+interface EntryProcessorHandlerConfig {
+    /** HLC instance for timestamp generation */
+    hlc: HLC;
+    /** Optional sandbox configuration override */
+    sandboxConfig?: Partial<ProcessorSandboxConfig>;
+}
+/**
+ * Server-side handler for Entry Processor execution.
+ *
+ * Responsibilities:
+ * - Validate incoming processor definitions
+ * - Execute processors in sandboxed environment
+ * - Update map state atomically
+ * - Return results with new values for client cache sync
+ */
+declare class EntryProcessorHandler {
+    private sandbox;
+    private hlc;
+    constructor(config: EntryProcessorHandlerConfig);
+    /**
+     * Execute a processor on a single key atomically.
+     *
+     * @param map The LWWMap to operate on
+     * @param key The key to process
+     * @param processorDef The processor definition (will be validated)
+     * @returns Result with success status, processor result, and new value
+     */
+    executeOnKey<V, R>(map: LWWMap<string, V>, key: string, processorDef: unknown): Promise<{
+        result: EntryProcessorResult<R>;
+        timestamp?: Timestamp;
+    }>;
+    /**
+     * Execute a processor on multiple keys.
+     *
+     * Each key is processed sequentially to ensure atomicity per-key.
+     * For parallel execution across keys, use multiple calls.
+     *
+     * @param map The LWWMap to operate on
+     * @param keys The keys to process
+     * @param processorDef The processor definition
+     * @returns Map of key -> result
+     */
+    executeOnKeys<V, R>(map: LWWMap<string, V>, keys: string[], processorDef: unknown): Promise<{
+        results: Map<string, EntryProcessorResult<R>>;
+        timestamps: Map<string, Timestamp>;
+    }>;
+    /**
+     * Execute a processor on all entries matching a predicate.
+     *
+     * WARNING: This can be expensive for large maps.
+     *
+     * @param map The LWWMap to operate on
+     * @param processorDef The processor definition
+     * @param predicateCode Optional predicate code to filter entries
+     * @returns Map of key -> result for processed entries
+     */
+    executeOnEntries<V, R>(map: LWWMap<string, V>, processorDef: unknown, predicateCode?: string): Promise<{
+        results: Map<string, EntryProcessorResult<R>>;
+        timestamps: Map<string, Timestamp>;
+    }>;
+    /**
+     * Check if sandbox is in secure mode (using isolated-vm).
+     */
+    isSecureMode(): boolean;
+    /**
+     * Get sandbox cache statistics.
+     */
+    getCacheStats(): {
+        isolates: number;
+        scripts: number;
+        fallbackScripts: number;
+    };
+    /**
+     * Clear sandbox cache.
+     */
+    clearCache(processorName?: string): void;
+    /**
+     * Dispose of the handler and its sandbox.
+     */
+    dispose(): void;
+}
+
+/**
+ * Configuration for ConflictResolverService.
+ */
+interface ConflictResolverServiceConfig {
+    /** Maximum resolvers per map */
+    maxResolversPerMap: number;
+    /** Enable sandboxed code execution (requires isolated-vm) */
+    enableSandboxedResolvers: boolean;
+    /** Default timeout for resolver execution in milliseconds */
+    resolverTimeoutMs: number;
+}
+/**
+ * Default service configuration.
+ */
+declare const DEFAULT_CONFLICT_RESOLVER_CONFIG: ConflictResolverServiceConfig;
+/**
+ * Service for managing and executing conflict resolvers.
+ *
+ * Resolvers are executed in priority order (highest first).
+ * The first resolver that returns a non-'local' action wins.
+ * If all resolvers return 'local', LWW is used as fallback.
+ *
+ * ## Design Decisions
+ *
+ * ### In-Memory Storage
+ * Resolvers are stored in memory only (not persisted to database).
+ * This is intentional - resolvers represent application logic that should
+ * be registered by clients on connection. Benefits:
+ * - Simpler architecture without resolver schema migrations
+ * - Clients control their own conflict resolution logic
+ * - Natural cleanup when client disconnects
+ *
+ * ### Permission Model
+ * Resolver registration requires PUT permission on the target map.
+ * This aligns with the principle that if you can write to a map,
+ * you can define how your writes are resolved. For stricter control,
+ * implement custom permission checks in ServerCoordinator.
+ *
+ * ### Deletion Handling
+ * Deletions (tombstones with null value) are passed through resolvers
+ * with `remoteValue: null`. This allows resolvers like IMMUTABLE or
+ * OWNER_ONLY to protect against unauthorized deletions.
+ */
+declare class ConflictResolverService {
+    private resolvers;
+    private sandbox;
+    private config;
+    private onRejectionCallback?;
+    private disposed;
+    constructor(sandbox: ProcessorSandbox, config?: Partial<ConflictResolverServiceConfig>);
+    /**
+     * Set callback for merge rejections.
+     */
+    onRejection(callback: (rejection: MergeRejection) => void): void;
+    /**
+     * Register a resolver for a map.
+     *
+     * @param mapName The map this resolver applies to
+     * @param resolver The resolver definition
+     * @param registeredBy Optional client ID that registered this resolver
+     */
+    register<V>(mapName: string, resolver: ConflictResolverDef<V>, registeredBy?: string): void;
+    /**
+     * Unregister a resolver.
+     *
+     * @param mapName The map name
+     * @param resolverName The resolver name to unregister
+     * @param clientId Optional - only unregister if registered by this client
+     */
+    unregister(mapName: string, resolverName: string, clientId?: string): boolean;
+    /**
+     * Resolve a merge conflict using registered resolvers.
+     *
+     * @param context The merge context
+     * @returns The merge result
+     */
+    resolve<V>(context: MergeContext<V>): Promise<MergeResult<V>>;
+    /**
+     * List registered resolvers.
+     *
+     * @param mapName Optional - filter by map name
+     */
+    list(mapName?: string): Array<{
+        mapName: string;
+        name: string;
+        priority?: number;
+        keyPattern?: string;
+        registeredBy?: string;
+    }>;
+    /**
+     * Check if a map has any registered resolvers.
+     */
+    hasResolvers(mapName: string): boolean;
+    /**
+     * Get the number of registered resolvers.
+     */
+    get size(): number;
+    /**
+     * Clear all registered resolvers.
+     *
+     * @param mapName Optional - only clear resolvers for specific map
+     */
+    clear(mapName?: string): void;
+    /**
+     * Clear resolvers registered by a specific client.
+     */
+    clearByClient(clientId: string): number;
+    /**
+     * Dispose the service.
+     */
+    dispose(): void;
+    /**
+     * Match a key against a glob-like pattern.
+     * Supports * (any chars) and ? (single char).
+     */
+    private matchKeyPattern;
+    /**
+     * Compile sandboxed resolver code.
+     */
+    private compileSandboxed;
+}
+
+/**
+ * Configuration for MapWithResolver.
+ */
+interface MapWithResolverConfig {
+    /** Map name */
+    name: string;
+    /** Node ID for HLC */
+    nodeId: string;
+    /** Conflict resolver service */
+    resolverService: ConflictResolverService;
+    /** Callback for merge rejections */
+    onRejection?: (rejection: MergeRejection) => void;
+}
+/**
+ * Result of setWithResolver operation.
+ */
+interface SetWithResolverResult<V> {
+    /** Whether the value was applied */
+    applied: boolean;
+    /** The merge result */
+    result: MergeResult<V>;
+    /** The final record if applied */
+    record?: LWWRecord<V>;
+}
+/**
+ * Extended LWWMap that supports custom conflict resolvers.
+ *
+ * This wrapper delegates merge operations to ConflictResolverService,
+ * allowing custom business logic to intercept and modify merge behavior.
+ */
+declare class MapWithResolver<K extends string, V> {
+    private map;
+    private resolverService;
+    private mapName;
+    private hlc;
+    private onRejection?;
+    constructor(config: MapWithResolverConfig);
+    /**
+     * Get the map name.
+     */
+    get name(): string;
+    /**
+     * Get the underlying LWWMap.
+     */
+    get rawMap(): LWWMap<K, V>;
+    /**
+     * Get a value by key.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Get the full record for a key.
+     */
+    getRecord(key: K): LWWRecord<V> | undefined;
+    /**
+     * Get the timestamp for a key.
+     */
+    getTimestamp(key: K): Timestamp | undefined;
+    /**
+     * Set a value locally (no resolver).
+     * Use for server-initiated writes.
+     */
+    set(key: K, value: V, ttlMs?: number): LWWRecord<V>;
+    /**
+     * Set a value with conflict resolution.
+     * Use for client-initiated writes.
+     *
+     * @param key The key to set
+     * @param value The new value
+     * @param timestamp The client's timestamp
+     * @param remoteNodeId The client's node ID
+     * @param auth Optional authentication context
+     * @returns Result containing applied status and merge result
+     */
+    setWithResolver(key: K, value: V, timestamp: Timestamp, remoteNodeId: string, auth?: MergeContext['auth']): Promise<SetWithResolverResult<V>>;
+    /**
+     * Remove a key.
+     */
+    remove(key: K): LWWRecord<V>;
+    /**
+     * Standard merge without resolver (for sync operations).
+     */
+    merge(key: K, record: LWWRecord<V>): boolean;
+    /**
+     * Merge with resolver support.
+     * Equivalent to setWithResolver but takes a full record.
+     */
+    mergeWithResolver(key: K, record: LWWRecord<V>, remoteNodeId: string, auth?: MergeContext['auth']): Promise<SetWithResolverResult<V>>;
+    /**
+     * Clear all data.
+     */
+    clear(): void;
+    /**
+     * Get map size.
+     */
+    get size(): number;
+    /**
+     * Iterate over entries.
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Get all keys.
+     */
+    allKeys(): IterableIterator<K>;
+    /**
+     * Subscribe to changes.
+     */
+    onChange(callback: () => void): () => void;
+    /**
+     * Get MerkleTree for sync.
+     */
+    getMerkleTree(): _topgunbuild_core.MerkleTree;
+    /**
+     * Prune old tombstones.
+     */
+    prune(olderThan: Timestamp): K[];
+}
+
+/**
+ * Configuration for ConflictResolverHandler.
+ */
+interface ConflictResolverHandlerConfig {
+    /** Node ID for identifying server-side resolvers */
+    nodeId: string;
+    /** Optional sandbox configuration override */
+    sandboxConfig?: Partial<ProcessorSandboxConfig>;
+    /** Optional resolver service configuration */
+    resolverConfig?: Partial<ConflictResolverServiceConfig>;
+}
+/**
+ * Result of merge operation with resolver.
+ */
+interface MergeWithResolverResult<V> {
+    /** Whether the merge was applied */
+    applied: boolean;
+    /** The merge result details */
+    result: MergeResult<V>;
+    /** The final record if applied */
+    record?: LWWRecord<V>;
+    /** Rejection details if rejected */
+    rejection?: MergeRejection;
+}
+/**
+ * Server-side handler for Conflict Resolver operations.
+ *
+ * Responsibilities:
+ * - Manage conflict resolver registrations
+ * - Execute resolvers during merge operations
+ * - Provide merge rejection notifications
+ */
+declare class ConflictResolverHandler {
+    private sandbox;
+    private resolverService;
+    /** Reserved for future use (server-side resolver identification) */
+    private readonly nodeId;
+    private rejectionListeners;
+    constructor(config: ConflictResolverHandlerConfig);
+    /**
+     * Register a conflict resolver for a map.
+     *
+     * @param mapName The map name
+     * @param resolver The resolver definition
+     * @param clientId Optional client ID that registered this resolver
+     */
+    registerResolver<V>(mapName: string, resolver: ConflictResolverDef<V>, clientId?: string): void;
+    /**
+     * Unregister a conflict resolver.
+     *
+     * @param mapName The map name
+     * @param resolverName The resolver name
+     * @param clientId Optional - only unregister if registered by this client
+     */
+    unregisterResolver(mapName: string, resolverName: string, clientId?: string): boolean;
+    /**
+     * List registered resolvers.
+     *
+     * @param mapName Optional - filter by map name
+     */
+    listResolvers(mapName?: string): Array<{
+        mapName: string;
+        name: string;
+        priority?: number;
+        keyPattern?: string;
+    }>;
+    /**
+     * Apply a merge with conflict resolution.
+     *
+     * Deletions (tombstones) are also passed through resolvers to allow
+     * protection via IMMUTABLE, OWNER_ONLY, or similar resolvers.
+     * If no custom resolvers are registered, deletions use standard LWW.
+     *
+     * @param map The LWWMap to merge into
+     * @param mapName The map name (for resolver lookup)
+     * @param key The key being merged
+     * @param record The incoming record
+     * @param remoteNodeId The source node ID
+     * @param auth Optional authentication context
+     */
+    mergeWithResolver<V>(map: LWWMap<string, V>, mapName: string, key: string, record: LWWRecord<V>, remoteNodeId: string, auth?: MergeContext['auth']): Promise<MergeWithResolverResult<V>>;
+    /**
+     * Check if a map has custom resolvers registered.
+     */
+    hasResolvers(mapName: string): boolean;
+    /**
+     * Add a listener for merge rejections.
+     */
+    onRejection(listener: (rejection: MergeRejection) => void): () => void;
+    /**
+     * Clear resolvers registered by a specific client.
+     */
+    clearByClient(clientId: string): number;
+    /**
+     * Get the number of registered resolvers.
+     */
+    get resolverCount(): number;
+    /**
+     * Check if sandbox is in secure mode.
+     */
+    isSecureMode(): boolean;
+    /**
+     * Dispose of the handler.
+     */
+    dispose(): void;
+}
+
+export { BufferPool, type BufferPoolConfig, type BufferPoolStats, type ClusterConfig, ClusterCoordinator, type ClusterCoordinatorConfig, type ClusterCoordinatorEvents, ClusterManager, type ClusterMember, type ClusterMessage, type CoalescingPreset, type CoalescingWriterMetrics, type CoalescingWriterOptions, ConflictResolverHandler, type ConflictResolverHandlerConfig, ConflictResolverService, type ConflictResolverServiceConfig, type ConnectionContext, ConnectionRateLimiter, DEFAULT_CLUSTER_COORDINATOR_CONFIG, DEFAULT_CONFLICT_RESOLVER_CONFIG, DEFAULT_JOURNAL_SERVICE_CONFIG, DEFAULT_LAG_TRACKER_CONFIG, DEFAULT_SANDBOX_CONFIG, EntryProcessorHandler, type EntryProcessorHandlerConfig, EventJournalService, type EventJournalServiceConfig, type ExportOptions, FilterTasklet, ForEachTasklet, type IInterceptor, type IServerStorage, IteratorTasklet, type IteratorTaskletConfig, type LagInfo, LagTracker, type LagTrackerConfig, LockManager, type Logger, MapTasklet, MapWithResolver, type MapWithResolverConfig, MemoryServerAdapter, type MergeWithResolverResult, 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, ProcessorSandbox, type ProcessorSandboxConfig, type ProgressState, RateLimitInterceptor, type RateLimiterConfig, type RateLimiterStats, ReduceTasklet, ReplicationPipeline, SecurityManager, ServerCoordinator, type ServerCoordinatorConfig, type ServerOp, type SetWithResolverResult, 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 };