@topgunbuild/server 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { Timestamp, LWWRecord, ORMapRecord, Principal, PermissionPolicy, ConsistencyLevel, ReplicationConfig, LWWMap, ORMap, PermissionType, MigrationConfig, MigrationStatus, MigrationMetrics, PartitionMap, PartitionInfo, PartitionChange, ReplicationLag, ReplicationHealth, ReplicationResult } 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, IndexedLWWMap, IndexedORMap } 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';
 
@@ -1671,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;
@@ -1743,6 +1854,10 @@ interface ServerCoordinatorConfig {
     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;
@@ -1782,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;
@@ -1831,6 +1952,11 @@ declare class ServerCoordinator {
      * 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 ===
@@ -1852,6 +1978,19 @@ declare class ServerCoordinator {
     private broadcastBatchSync;
     private setupClusterListeners;
     private executeLocalQuery;
+    /**
+     * Convert server Query format to core Query format for indexed execution.
+     * Returns null if conversion is not possible (complex queries).
+     */
+    private convertToCoreQuery;
+    /**
+     * Convert predicate node to core Query format.
+     */
+    private predicateToCoreQuery;
+    /**
+     * Convert server operator to core query type.
+     */
+    private convertOperator;
     private finalizeClusterQuery;
     /**
      * Core operation application logic shared between processLocalOp and processLocalOpForBatch.
@@ -3048,4 +3187,689 @@ declare class ClusterCoordinator extends EventEmitter {
     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 };
+/**
+ * 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;
+}
+
+/**
+ * IndexConfig Types
+ *
+ * Configuration types for server-side index management.
+ * Used to define indexes per map at server startup.
+ *
+ * @module config/IndexConfig
+ */
+/**
+ * Definition of a single index on a map.
+ */
+interface IndexDefinition {
+    /** Attribute name (supports dot notation for nested attributes, e.g., "user.email") */
+    attribute: string;
+    /** Index type */
+    type: 'hash' | 'navigable';
+    /**
+     * Comparator type for navigable indexes.
+     * Defaults to natural ordering (string/number).
+     */
+    comparator?: 'number' | 'string' | 'date';
+}
+/**
+ * Index configuration for a specific map.
+ */
+interface MapIndexConfig {
+    /** Map name */
+    mapName: string;
+    /** Indexes to create on this map */
+    indexes: IndexDefinition[];
+}
+/**
+ * Server-wide index configuration.
+ */
+interface ServerIndexConfig {
+    /**
+     * Auto-create indexes based on query patterns.
+     * When enabled, the server will analyze query patterns and suggest/create indexes.
+     * Default: false
+     */
+    autoIndex?: boolean;
+    /**
+     * Maximum number of auto-created indexes per map.
+     * Prevents unbounded memory growth from auto-indexing.
+     * Default: 10
+     */
+    maxAutoIndexesPerMap?: number;
+    /**
+     * Pre-configured indexes per map.
+     * These indexes are created at map initialization.
+     */
+    maps?: MapIndexConfig[];
+    /**
+     * Whether to log index usage statistics.
+     * Default: false
+     */
+    logStats?: boolean;
+    /**
+     * Interval in milliseconds for logging index statistics.
+     * Only used if logStats is true.
+     * Default: 60000 (1 minute)
+     */
+    statsLogInterval?: number;
+}
+/**
+ * Default index configuration.
+ */
+declare const DEFAULT_INDEX_CONFIG: ServerIndexConfig;
+/**
+ * Validate a ServerIndexConfig object.
+ *
+ * @param config - Config to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+declare function validateIndexConfig(config: ServerIndexConfig): string[];
+/**
+ * Merge user config with defaults.
+ *
+ * @param userConfig - User-provided config
+ * @returns Merged config with defaults
+ */
+declare function mergeWithDefaults(userConfig: Partial<ServerIndexConfig>): ServerIndexConfig;
+
+/**
+ * MapFactory Implementation
+ *
+ * Factory for creating LWWMap or IndexedLWWMap based on configuration.
+ * Used by ServerCoordinator to create maps with proper indexes.
+ *
+ * @module config/MapFactory
+ */
+
+/**
+ * Factory for creating indexed or regular CRDT maps.
+ */
+declare class MapFactory {
+    private readonly config;
+    private readonly mapConfigs;
+    /**
+     * Create a MapFactory.
+     *
+     * @param config - Server index configuration
+     */
+    constructor(config?: Partial<ServerIndexConfig>);
+    /**
+     * Create an LWWMap or IndexedLWWMap based on configuration.
+     *
+     * @param mapName - Name of the map
+     * @param hlc - Hybrid Logical Clock instance
+     * @returns LWWMap or IndexedLWWMap depending on configuration
+     */
+    createLWWMap<V>(mapName: string, hlc: HLC): LWWMap<string, V> | IndexedLWWMap<string, V>;
+    /**
+     * Create an ORMap or IndexedORMap based on configuration.
+     *
+     * @param mapName - Name of the map
+     * @param hlc - Hybrid Logical Clock instance
+     * @returns ORMap or IndexedORMap depending on configuration
+     */
+    createORMap<V>(mapName: string, hlc: HLC): ORMap<string, V> | IndexedORMap<string, V>;
+    /**
+     * Add an index to an IndexedLWWMap based on definition.
+     */
+    private addIndexToLWWMap;
+    /**
+     * Add an index to an IndexedORMap based on definition.
+     */
+    private addIndexToORMap;
+    /**
+     * Create an Attribute for extracting values from records.
+     * Supports dot notation for nested paths.
+     */
+    private createAttribute;
+    /**
+     * Get a nested value from an object using dot notation.
+     *
+     * @param obj - Object to extract value from
+     * @param path - Dot-notation path (e.g., "user.email")
+     * @returns Value at the path or undefined
+     */
+    private getNestedValue;
+    /**
+     * Create a comparator function for navigable indexes.
+     */
+    private createComparator;
+    /**
+     * Check if a map should be indexed based on configuration.
+     *
+     * @param mapName - Name of the map
+     * @returns true if map has index configuration
+     */
+    hasIndexConfig(mapName: string): boolean;
+    /**
+     * Get index configuration for a map.
+     *
+     * @param mapName - Name of the map
+     * @returns Map index config or undefined
+     */
+    getMapConfig(mapName: string): MapIndexConfig | undefined;
+    /**
+     * Get all configured map names.
+     *
+     * @returns Array of map names with index configuration
+     */
+    getConfiguredMaps(): string[];
+    /**
+     * Get the full server index configuration.
+     */
+    getConfig(): ServerIndexConfig;
+}
+
+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_INDEX_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, type IndexDefinition, IteratorTasklet, type IteratorTaskletConfig, type LagInfo, LagTracker, type LagTrackerConfig, LockManager, type Logger, MapFactory, type MapIndexConfig, 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 ServerIndexConfig, 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, mergeWithDefaults, setGlobalBufferPool, setGlobalEventPayloadPool, setGlobalMessagePool, setGlobalRecordPool, setGlobalTimestampPool, validateIndexConfig };