@topgunbuild/client 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -430,6 +430,237 @@ var SingleServerProvider = class {
   }
 };
 
+// src/ConflictResolverClient.ts
+var _ConflictResolverClient = class _ConflictResolverClient {
+  // 10 seconds
+  constructor(syncEngine) {
+    this.rejectionListeners = /* @__PURE__ */ new Set();
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.syncEngine = syncEngine;
+  }
+  /**
+   * Register a conflict resolver on the server.
+   *
+   * @param mapName The map to register the resolver for
+   * @param resolver The resolver definition
+   * @returns Promise resolving to registration result
+   *
+   * @example
+   * ```typescript
+   * // Register a first-write-wins resolver for bookings
+   * await client.resolvers.register('bookings', {
+   *   name: 'first-write-wins',
+   *   code: `
+   *     if (context.localValue !== undefined) {
+   *       return { action: 'reject', reason: 'Slot already booked' };
+   *     }
+   *     return { action: 'accept', value: context.remoteValue };
+   *   `,
+   *   priority: 100,
+   * });
+   * ```
+   */
+  async register(mapName, resolver) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Register resolver request timed out"));
+      }, _ConflictResolverClient.REQUEST_TIMEOUT);
+      this.pendingRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+        timeout
+      });
+      try {
+        this.syncEngine.send({
+          type: "REGISTER_RESOLVER",
+          requestId,
+          mapName,
+          resolver: {
+            name: resolver.name,
+            code: resolver.code || "",
+            priority: resolver.priority,
+            keyPattern: resolver.keyPattern
+          }
+        });
+      } catch {
+        this.pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve({ success: false, error: "Not connected to server" });
+      }
+    });
+  }
+  /**
+   * Unregister a conflict resolver from the server.
+   *
+   * @param mapName The map the resolver is registered for
+   * @param resolverName The name of the resolver to unregister
+   * @returns Promise resolving to unregistration result
+   */
+  async unregister(mapName, resolverName) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Unregister resolver request timed out"));
+      }, _ConflictResolverClient.REQUEST_TIMEOUT);
+      this.pendingRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+        timeout
+      });
+      try {
+        this.syncEngine.send({
+          type: "UNREGISTER_RESOLVER",
+          requestId,
+          mapName,
+          resolverName
+        });
+      } catch {
+        this.pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve({ success: false, error: "Not connected to server" });
+      }
+    });
+  }
+  /**
+   * List registered conflict resolvers on the server.
+   *
+   * @param mapName Optional - filter by map name
+   * @returns Promise resolving to list of resolver info
+   */
+  async list(mapName) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("List resolvers request timed out"));
+      }, _ConflictResolverClient.REQUEST_TIMEOUT);
+      this.pendingRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result.resolvers);
+        },
+        reject,
+        timeout
+      });
+      try {
+        this.syncEngine.send({
+          type: "LIST_RESOLVERS",
+          requestId,
+          mapName
+        });
+      } catch {
+        this.pendingRequests.delete(requestId);
+        clearTimeout(timeout);
+        resolve([]);
+      }
+    });
+  }
+  /**
+   * Subscribe to merge rejection events.
+   *
+   * @param listener Callback for rejection events
+   * @returns Unsubscribe function
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.resolvers.onRejection((rejection) => {
+   *   console.log(`Merge rejected for ${rejection.key}: ${rejection.reason}`);
+   *   // Optionally refresh the local value
+   * });
+   *
+   * // Later...
+   * unsubscribe();
+   * ```
+   */
+  onRejection(listener) {
+    this.rejectionListeners.add(listener);
+    return () => this.rejectionListeners.delete(listener);
+  }
+  /**
+   * Handle REGISTER_RESOLVER_RESPONSE from server.
+   * Called by SyncEngine.
+   */
+  handleRegisterResponse(message) {
+    const pending = this.pendingRequests.get(message.requestId);
+    if (pending) {
+      this.pendingRequests.delete(message.requestId);
+      pending.resolve({ success: message.success, error: message.error });
+    }
+  }
+  /**
+   * Handle UNREGISTER_RESOLVER_RESPONSE from server.
+   * Called by SyncEngine.
+   */
+  handleUnregisterResponse(message) {
+    const pending = this.pendingRequests.get(message.requestId);
+    if (pending) {
+      this.pendingRequests.delete(message.requestId);
+      pending.resolve({ success: message.success, error: message.error });
+    }
+  }
+  /**
+   * Handle LIST_RESOLVERS_RESPONSE from server.
+   * Called by SyncEngine.
+   */
+  handleListResponse(message) {
+    const pending = this.pendingRequests.get(message.requestId);
+    if (pending) {
+      this.pendingRequests.delete(message.requestId);
+      pending.resolve({ resolvers: message.resolvers });
+    }
+  }
+  /**
+   * Handle MERGE_REJECTED from server.
+   * Called by SyncEngine.
+   */
+  handleMergeRejected(message) {
+    const rejection = {
+      mapName: message.mapName,
+      key: message.key,
+      attemptedValue: message.attemptedValue,
+      reason: message.reason,
+      timestamp: message.timestamp,
+      nodeId: ""
+      // Not provided by server in this message
+    };
+    logger.debug({ rejection }, "Merge rejected by server");
+    for (const listener of this.rejectionListeners) {
+      try {
+        listener(rejection);
+      } catch (e) {
+        logger.error({ error: e }, "Error in rejection listener");
+      }
+    }
+  }
+  /**
+   * Clear all pending requests (e.g., on disconnect).
+   */
+  clearPending() {
+    for (const [requestId, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Connection lost"));
+    }
+    this.pendingRequests.clear();
+  }
+  /**
+   * Get the number of registered rejection listeners.
+   */
+  get rejectionListenerCount() {
+    return this.rejectionListeners.size;
+  }
+};
+_ConflictResolverClient.REQUEST_TIMEOUT = 1e4;
+var ConflictResolverClient = _ConflictResolverClient;
+
 // src/SyncEngine.ts
 var DEFAULT_BACKOFF_CONFIG = {
   initialDelayMs: 1e3,
@@ -438,7 +669,7 @@ var DEFAULT_BACKOFF_CONFIG = {
   jitter: true,
   maxRetries: 10
 };
-var SyncEngine = class {
+var _SyncEngine = class _SyncEngine {
   constructor(config) {
     this.websocket = null;
     this.opLog = [];
@@ -461,6 +692,23 @@ var SyncEngine = class {
     this.backpressureListeners = /* @__PURE__ */ new Map();
     // Write Concern state (Phase 5.01)
     this.pendingWriteConcernPromises = /* @__PURE__ */ new Map();
+    // ============================================
+    // PN Counter Methods (Phase 5.2)
+    // ============================================
+    /** Counter update listeners by name */
+    this.counterUpdateListeners = /* @__PURE__ */ new Map();
+    // ============================================
+    // Entry Processor Methods (Phase 5.03)
+    // ============================================
+    /** Pending entry processor requests by requestId */
+    this.pendingProcessorRequests = /* @__PURE__ */ new Map();
+    /** Pending batch entry processor requests by requestId */
+    this.pendingBatchProcessorRequests = /* @__PURE__ */ new Map();
+    // ============================================
+    // Event Journal Methods (Phase 5.04)
+    // ============================================
+    /** Message listeners for journal and other generic messages */
+    this.messageListeners = /* @__PURE__ */ new Set();
     if (!config.serverUrl && !config.connectionProvider) {
       throw new Error("SyncEngine requires either serverUrl or connectionProvider");
     }
@@ -491,6 +739,7 @@ var SyncEngine = class {
       this.useConnectionProvider = false;
       this.initConnection();
     }
+    this.conflictResolverClient = new ConflictResolverClient(this);
     this.loadOpLog();
   }
   // ============================================
@@ -973,6 +1222,7 @@ var SyncEngine = class {
     });
   }
   async handleServerMessage(message) {
+    this.emitMessage(message);
     switch (message.type) {
       case "BATCH": {
         const batchData = message.data;
@@ -1299,6 +1549,51 @@ var SyncEngine = class {
         }
         break;
       }
+      // ============ PN Counter Message Handlers (Phase 5.2) ============
+      case "COUNTER_UPDATE": {
+        const { name, state } = message.payload;
+        logger.debug({ name }, "Received COUNTER_UPDATE");
+        this.handleCounterUpdate(name, state);
+        break;
+      }
+      case "COUNTER_RESPONSE": {
+        const { name, state } = message.payload;
+        logger.debug({ name }, "Received COUNTER_RESPONSE");
+        this.handleCounterUpdate(name, state);
+        break;
+      }
+      // ============ Entry Processor Message Handlers (Phase 5.03) ============
+      case "ENTRY_PROCESS_RESPONSE": {
+        logger.debug({ requestId: message.requestId, success: message.success }, "Received ENTRY_PROCESS_RESPONSE");
+        this.handleEntryProcessResponse(message);
+        break;
+      }
+      case "ENTRY_PROCESS_BATCH_RESPONSE": {
+        logger.debug({ requestId: message.requestId }, "Received ENTRY_PROCESS_BATCH_RESPONSE");
+        this.handleEntryProcessBatchResponse(message);
+        break;
+      }
+      // ============ Conflict Resolver Message Handlers (Phase 5.05) ============
+      case "REGISTER_RESOLVER_RESPONSE": {
+        logger.debug({ requestId: message.requestId, success: message.success }, "Received REGISTER_RESOLVER_RESPONSE");
+        this.conflictResolverClient.handleRegisterResponse(message);
+        break;
+      }
+      case "UNREGISTER_RESOLVER_RESPONSE": {
+        logger.debug({ requestId: message.requestId, success: message.success }, "Received UNREGISTER_RESOLVER_RESPONSE");
+        this.conflictResolverClient.handleUnregisterResponse(message);
+        break;
+      }
+      case "LIST_RESOLVERS_RESPONSE": {
+        logger.debug({ requestId: message.requestId }, "Received LIST_RESOLVERS_RESPONSE");
+        this.conflictResolverClient.handleListResponse(message);
+        break;
+      }
+      case "MERGE_REJECTED": {
+        logger.debug({ mapName: message.mapName, key: message.key, reason: message.reason }, "Received MERGE_REJECTED");
+        this.conflictResolverClient.handleMergeRejected(message);
+        break;
+      }
     }
     if (message.timestamp) {
       this.hlc.update(message.timestamp);
@@ -1812,16 +2107,371 @@ var SyncEngine = class {
     }
     this.pendingWriteConcernPromises.clear();
   }
+  /**
+   * Subscribe to counter updates from server.
+   * @param name Counter name
+   * @param listener Callback when counter state is updated
+   * @returns Unsubscribe function
+   */
+  onCounterUpdate(name, listener) {
+    if (!this.counterUpdateListeners.has(name)) {
+      this.counterUpdateListeners.set(name, /* @__PURE__ */ new Set());
+    }
+    this.counterUpdateListeners.get(name).add(listener);
+    return () => {
+      this.counterUpdateListeners.get(name)?.delete(listener);
+      if (this.counterUpdateListeners.get(name)?.size === 0) {
+        this.counterUpdateListeners.delete(name);
+      }
+    };
+  }
+  /**
+   * Request initial counter state from server.
+   * @param name Counter name
+   */
+  requestCounter(name) {
+    if (this.isAuthenticated()) {
+      this.sendMessage({
+        type: "COUNTER_REQUEST",
+        payload: { name }
+      });
+    }
+  }
+  /**
+   * Sync local counter state to server.
+   * @param name Counter name
+   * @param state Counter state to sync
+   */
+  syncCounter(name, state) {
+    if (this.isAuthenticated()) {
+      const stateObj = {
+        positive: Object.fromEntries(state.positive),
+        negative: Object.fromEntries(state.negative)
+      };
+      this.sendMessage({
+        type: "COUNTER_SYNC",
+        payload: {
+          name,
+          state: stateObj
+        }
+      });
+    }
+  }
+  /**
+   * Handle incoming counter update from server.
+   * Called by handleServerMessage for COUNTER_UPDATE messages.
+   */
+  handleCounterUpdate(name, stateObj) {
+    const state = {
+      positive: new Map(Object.entries(stateObj.positive)),
+      negative: new Map(Object.entries(stateObj.negative))
+    };
+    const listeners = this.counterUpdateListeners.get(name);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(state);
+        } catch (e) {
+          logger.error({ err: e, counterName: name }, "Counter update listener error");
+        }
+      }
+    }
+  }
+  /**
+   * Execute an entry processor on a single key atomically.
+   *
+   * @param mapName Name of the map
+   * @param key Key to process
+   * @param processor Processor definition
+   * @returns Promise resolving to the processor result
+   */
+  async executeOnKey(mapName, key, processor) {
+    if (!this.isAuthenticated()) {
+      return {
+        success: false,
+        error: "Not connected to server"
+      };
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingProcessorRequests.delete(requestId);
+        reject(new Error("Entry processor request timed out"));
+      }, _SyncEngine.PROCESSOR_TIMEOUT);
+      this.pendingProcessorRequests.set(requestId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+        timeout
+      });
+      const sent = this.sendMessage({
+        type: "ENTRY_PROCESS",
+        requestId,
+        mapName,
+        key,
+        processor: {
+          name: processor.name,
+          code: processor.code,
+          args: processor.args
+        }
+      }, key);
+      if (!sent) {
+        this.pendingProcessorRequests.delete(requestId);
+        clearTimeout(timeout);
+        reject(new Error("Failed to send entry processor request"));
+      }
+    });
+  }
+  /**
+   * Execute an entry processor on multiple keys.
+   *
+   * @param mapName Name of the map
+   * @param keys Keys to process
+   * @param processor Processor definition
+   * @returns Promise resolving to a map of key -> result
+   */
+  async executeOnKeys(mapName, keys, processor) {
+    if (!this.isAuthenticated()) {
+      const results = /* @__PURE__ */ new Map();
+      const error = {
+        success: false,
+        error: "Not connected to server"
+      };
+      for (const key of keys) {
+        results.set(key, error);
+      }
+      return results;
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingBatchProcessorRequests.delete(requestId);
+        reject(new Error("Entry processor batch request timed out"));
+      }, _SyncEngine.PROCESSOR_TIMEOUT);
+      this.pendingBatchProcessorRequests.set(requestId, {
+        resolve: (results) => {
+          clearTimeout(timeout);
+          resolve(results);
+        },
+        reject,
+        timeout
+      });
+      const sent = this.sendMessage({
+        type: "ENTRY_PROCESS_BATCH",
+        requestId,
+        mapName,
+        keys,
+        processor: {
+          name: processor.name,
+          code: processor.code,
+          args: processor.args
+        }
+      });
+      if (!sent) {
+        this.pendingBatchProcessorRequests.delete(requestId);
+        clearTimeout(timeout);
+        reject(new Error("Failed to send entry processor batch request"));
+      }
+    });
+  }
+  /**
+   * Handle entry processor response from server.
+   * Called by handleServerMessage for ENTRY_PROCESS_RESPONSE messages.
+   */
+  handleEntryProcessResponse(message) {
+    const pending = this.pendingProcessorRequests.get(message.requestId);
+    if (pending) {
+      this.pendingProcessorRequests.delete(message.requestId);
+      pending.resolve({
+        success: message.success,
+        result: message.result,
+        newValue: message.newValue,
+        error: message.error
+      });
+    }
+  }
+  /**
+   * Handle entry processor batch response from server.
+   * Called by handleServerMessage for ENTRY_PROCESS_BATCH_RESPONSE messages.
+   */
+  handleEntryProcessBatchResponse(message) {
+    const pending = this.pendingBatchProcessorRequests.get(message.requestId);
+    if (pending) {
+      this.pendingBatchProcessorRequests.delete(message.requestId);
+      const resultsMap = /* @__PURE__ */ new Map();
+      for (const [key, result] of Object.entries(message.results)) {
+        resultsMap.set(key, {
+          success: result.success,
+          result: result.result,
+          newValue: result.newValue,
+          error: result.error
+        });
+      }
+      pending.resolve(resultsMap);
+    }
+  }
+  /**
+   * Subscribe to all incoming messages.
+   * Used by EventJournalReader to receive journal events.
+   *
+   * @param event Event type (currently only 'message')
+   * @param handler Message handler
+   */
+  on(event, handler2) {
+    if (event === "message") {
+      this.messageListeners.add(handler2);
+    }
+  }
+  /**
+   * Unsubscribe from incoming messages.
+   *
+   * @param event Event type (currently only 'message')
+   * @param handler Message handler to remove
+   */
+  off(event, handler2) {
+    if (event === "message") {
+      this.messageListeners.delete(handler2);
+    }
+  }
+  /**
+   * Send a message to the server.
+   * Public method for EventJournalReader and other components.
+   *
+   * @param message Message object to send
+   */
+  send(message) {
+    this.sendMessage(message);
+  }
+  /**
+   * Emit message to all listeners.
+   * Called internally when a message is received.
+   */
+  emitMessage(message) {
+    for (const listener of this.messageListeners) {
+      try {
+        listener(message);
+      } catch (e) {
+        logger.error({ err: e }, "Message listener error");
+      }
+    }
+  }
+  // ============================================
+  // Conflict Resolver Client (Phase 5.05)
+  // ============================================
+  /**
+   * Get the conflict resolver client for registering custom resolvers
+   * and subscribing to merge rejection events.
+   */
+  getConflictResolverClient() {
+    return this.conflictResolverClient;
+  }
 };
+/** Default timeout for entry processor requests (ms) */
+_SyncEngine.PROCESSOR_TIMEOUT = 3e4;
+var SyncEngine = _SyncEngine;
 
 // src/TopGunClient.ts
 import { LWWMap as LWWMap2, ORMap as ORMap2 } from "@topgunbuild/core";
 
+// src/utils/deepEqual.ts
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return a === b;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(b)) return false;
+  const objA = a;
+  const objB = b;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(objB, key)) return false;
+    if (!deepEqual(objA[key], objB[key])) return false;
+  }
+  return true;
+}
+
+// src/ChangeTracker.ts
+var ChangeTracker = class {
+  constructor() {
+    this.previousSnapshot = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Computes changes between previous and current state.
+   * Updates internal snapshot after computation.
+   *
+   * @param current - Current state as a Map
+   * @param timestamp - HLC timestamp for the changes
+   * @returns Array of change events (may be empty if no changes)
+   */
+  computeChanges(current, timestamp) {
+    const changes = [];
+    for (const [key, value] of current) {
+      const previous = this.previousSnapshot.get(key);
+      if (previous === void 0) {
+        changes.push({ type: "add", key, value, timestamp });
+      } else if (!deepEqual(previous, value)) {
+        changes.push({
+          type: "update",
+          key,
+          value,
+          previousValue: previous,
+          timestamp
+        });
+      }
+    }
+    for (const [key, value] of this.previousSnapshot) {
+      if (!current.has(key)) {
+        changes.push({
+          type: "remove",
+          key,
+          previousValue: value,
+          timestamp
+        });
+      }
+    }
+    this.previousSnapshot = new Map(
+      Array.from(current.entries()).map(([k, v]) => [
+        k,
+        typeof v === "object" && v !== null ? { ...v } : v
+      ])
+    );
+    return changes;
+  }
+  /**
+   * Reset tracker (e.g., on query change or reconnect)
+   */
+  reset() {
+    this.previousSnapshot.clear();
+  }
+  /**
+   * Get current snapshot size for debugging/metrics
+   */
+  get size() {
+    return this.previousSnapshot.size;
+  }
+};
+
 // src/QueryHandle.ts
 var QueryHandle = class {
   constructor(syncEngine, mapName, filter = {}) {
     this.listeners = /* @__PURE__ */ new Set();
     this.currentResults = /* @__PURE__ */ new Map();
+    // Change tracking (Phase 5.1)
+    this.changeTracker = new ChangeTracker();
+    this.pendingChanges = [];
+    this.changeListeners = /* @__PURE__ */ new Set();
     // Track if we've received authoritative server response
     this.hasReceivedServerData = false;
     this.id = crypto.randomUUID();
@@ -1864,14 +2514,15 @@ var QueryHandle = class {
    * - Works with any async storage adapter (PostgreSQL, SQLite, Redis, etc.)
    */
   onResult(items, source = "server") {
-    console.log(`[QueryHandle:${this.mapName}] onResult called with ${items.length} items`, {
+    logger.debug({
+      mapName: this.mapName,
+      itemCount: items.length,
       source,
       currentResultsCount: this.currentResults.size,
-      newItemKeys: items.map((i) => i.key),
       hasReceivedServerData: this.hasReceivedServerData
-    });
+    }, "QueryHandle onResult");
     if (source === "server" && items.length === 0 && !this.hasReceivedServerData) {
-      console.log(`[QueryHandle:${this.mapName}] Ignoring empty server response - waiting for authoritative data`);
+      logger.debug({ mapName: this.mapName }, "QueryHandle ignoring empty server response - waiting for authoritative data");
       return;
     }
     if (source === "server" && items.length > 0) {
@@ -1886,12 +2537,20 @@ var QueryHandle = class {
       }
     }
     if (removedKeys.length > 0) {
-      console.log(`[QueryHandle:${this.mapName}] Removed ${removedKeys.length} keys:`, removedKeys);
+      logger.debug({
+        mapName: this.mapName,
+        removedCount: removedKeys.length,
+        removedKeys
+      }, "QueryHandle removed keys");
     }
     for (const item of items) {
       this.currentResults.set(item.key, item.value);
     }
-    console.log(`[QueryHandle:${this.mapName}] After merge: ${this.currentResults.size} results`);
+    logger.debug({
+      mapName: this.mapName,
+      resultCount: this.currentResults.size
+    }, "QueryHandle after merge");
+    this.computeAndNotifyChanges(Date.now());
     this.notify();
   }
   /**
@@ -1903,8 +2562,80 @@ var QueryHandle = class {
     } else {
       this.currentResults.set(key, value);
     }
+    this.computeAndNotifyChanges(Date.now());
     this.notify();
   }
+  /**
+   * Subscribe to change events (Phase 5.1).
+   * Returns an unsubscribe function.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = handle.onChanges((changes) => {
+   *   for (const change of changes) {
+   *     if (change.type === 'add') {
+   *       console.log('Added:', change.key, change.value);
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  onChanges(listener) {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+  /**
+   * Get and clear pending changes (Phase 5.1).
+   * Call this to retrieve all changes since the last consume.
+   */
+  consumeChanges() {
+    const changes = [...this.pendingChanges];
+    this.pendingChanges = [];
+    return changes;
+  }
+  /**
+   * Get last change without consuming (Phase 5.1).
+   * Returns null if no pending changes.
+   */
+  getLastChange() {
+    return this.pendingChanges.length > 0 ? this.pendingChanges[this.pendingChanges.length - 1] : null;
+  }
+  /**
+   * Get all pending changes without consuming (Phase 5.1).
+   */
+  getPendingChanges() {
+    return [...this.pendingChanges];
+  }
+  /**
+   * Clear all pending changes (Phase 5.1).
+   */
+  clearChanges() {
+    this.pendingChanges = [];
+  }
+  /**
+   * Reset change tracker (Phase 5.1).
+   * Use when query filter changes or on reconnect.
+   */
+  resetChangeTracker() {
+    this.changeTracker.reset();
+    this.pendingChanges = [];
+  }
+  computeAndNotifyChanges(timestamp) {
+    const changes = this.changeTracker.computeChanges(this.currentResults, timestamp);
+    if (changes.length > 0) {
+      this.pendingChanges.push(...changes);
+      this.notifyChangeListeners(changes);
+    }
+  }
+  notifyChangeListeners(changes) {
+    for (const listener of this.changeListeners) {
+      try {
+        listener(changes);
+      } catch (e) {
+        logger.error({ err: e }, "QueryHandle change listener error");
+      }
+    }
+  }
   notify() {
     const results = this.getSortedResults();
     for (const listener of this.listeners) {
@@ -2016,6 +2747,294 @@ var TopicHandle = class {
   }
 };
 
+// src/PNCounterHandle.ts
+import { PNCounterImpl } from "@topgunbuild/core";
+var COUNTER_STORAGE_PREFIX = "__counter__:";
+var PNCounterHandle = class {
+  constructor(name, nodeId, syncEngine, storageAdapter) {
+    this.syncScheduled = false;
+    this.persistScheduled = false;
+    this.name = name;
+    this.syncEngine = syncEngine;
+    this.storageAdapter = storageAdapter;
+    this.counter = new PNCounterImpl({ nodeId });
+    this.restoreFromStorage();
+    this.unsubscribeFromUpdates = this.syncEngine.onCounterUpdate(name, (state) => {
+      this.counter.merge(state);
+      this.schedulePersist();
+    });
+    this.syncEngine.requestCounter(name);
+    logger.debug({ name, nodeId }, "PNCounterHandle created");
+  }
+  /**
+   * Restore counter state from local storage.
+   * Called during construction to recover offline state.
+   */
+  async restoreFromStorage() {
+    if (!this.storageAdapter) {
+      return;
+    }
+    try {
+      const storageKey = COUNTER_STORAGE_PREFIX + this.name;
+      const stored = await this.storageAdapter.getMeta(storageKey);
+      if (stored && typeof stored === "object" && "p" in stored && "n" in stored) {
+        const state = PNCounterImpl.objectToState(stored);
+        this.counter.merge(state);
+        logger.debug({ name: this.name, value: this.counter.get() }, "PNCounter restored from storage");
+      }
+    } catch (err) {
+      logger.error({ err, name: this.name }, "Failed to restore PNCounter from storage");
+    }
+  }
+  /**
+   * Persist counter state to local storage.
+   * Debounced to avoid excessive writes during rapid operations.
+   */
+  schedulePersist() {
+    if (!this.storageAdapter || this.persistScheduled) return;
+    this.persistScheduled = true;
+    setTimeout(() => {
+      this.persistScheduled = false;
+      this.persistToStorage();
+    }, 100);
+  }
+  /**
+   * Actually persist state to storage.
+   */
+  async persistToStorage() {
+    if (!this.storageAdapter) return;
+    try {
+      const storageKey = COUNTER_STORAGE_PREFIX + this.name;
+      const stateObj = PNCounterImpl.stateToObject(this.counter.getState());
+      await this.storageAdapter.setMeta(storageKey, stateObj);
+      logger.debug({ name: this.name, value: this.counter.get() }, "PNCounter persisted to storage");
+    } catch (err) {
+      logger.error({ err, name: this.name }, "Failed to persist PNCounter to storage");
+    }
+  }
+  /**
+   * Get current counter value.
+   */
+  get() {
+    return this.counter.get();
+  }
+  /**
+   * Increment by 1 and return new value.
+   */
+  increment() {
+    const value = this.counter.increment();
+    this.scheduleSync();
+    this.schedulePersist();
+    return value;
+  }
+  /**
+   * Decrement by 1 and return new value.
+   */
+  decrement() {
+    const value = this.counter.decrement();
+    this.scheduleSync();
+    this.schedulePersist();
+    return value;
+  }
+  /**
+   * Add delta (positive or negative) and return new value.
+   */
+  addAndGet(delta) {
+    const value = this.counter.addAndGet(delta);
+    if (delta !== 0) {
+      this.scheduleSync();
+      this.schedulePersist();
+    }
+    return value;
+  }
+  /**
+   * Get state for sync.
+   */
+  getState() {
+    return this.counter.getState();
+  }
+  /**
+   * Merge remote state.
+   */
+  merge(remote) {
+    this.counter.merge(remote);
+  }
+  /**
+   * Subscribe to value changes.
+   */
+  subscribe(listener) {
+    return this.counter.subscribe(listener);
+  }
+  /**
+   * Get the counter name.
+   */
+  getName() {
+    return this.name;
+  }
+  /**
+   * Cleanup resources.
+   */
+  dispose() {
+    if (this.unsubscribeFromUpdates) {
+      this.unsubscribeFromUpdates();
+    }
+  }
+  /**
+   * Schedule sync to server with debouncing.
+   * Batches rapid increments to avoid network spam.
+   */
+  scheduleSync() {
+    if (this.syncScheduled) return;
+    this.syncScheduled = true;
+    setTimeout(() => {
+      this.syncScheduled = false;
+      this.syncEngine.syncCounter(this.name, this.counter.getState());
+    }, 50);
+  }
+};
+
+// src/EventJournalReader.ts
+var EventJournalReader = class {
+  constructor(syncEngine) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.subscriptionCounter = 0;
+    this.syncEngine = syncEngine;
+  }
+  /**
+   * Read events from sequence with optional limit.
+   *
+   * @param sequence Starting sequence (inclusive)
+   * @param limit Maximum events to return (default: 100)
+   * @returns Promise resolving to array of events
+   */
+  async readFrom(sequence, limit = 100) {
+    const requestId = this.generateRequestId();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("Journal read timeout"));
+      }, 1e4);
+      const handleResponse = (message) => {
+        if (message.type === "JOURNAL_READ_RESPONSE" && message.requestId === requestId) {
+          clearTimeout(timeout);
+          this.syncEngine.off("message", handleResponse);
+          const events = message.events.map((e) => this.parseEvent(e));
+          resolve(events);
+        }
+      };
+      this.syncEngine.on("message", handleResponse);
+      this.syncEngine.send({
+        type: "JOURNAL_READ",
+        requestId,
+        fromSequence: sequence.toString(),
+        limit
+      });
+    });
+  }
+  /**
+   * Read events for a specific map.
+   *
+   * @param mapName Map name to filter
+   * @param sequence Starting sequence (default: 0n)
+   * @param limit Maximum events to return (default: 100)
+   */
+  async readMapEvents(mapName, sequence = 0n, limit = 100) {
+    const requestId = this.generateRequestId();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("Journal read timeout"));
+      }, 1e4);
+      const handleResponse = (message) => {
+        if (message.type === "JOURNAL_READ_RESPONSE" && message.requestId === requestId) {
+          clearTimeout(timeout);
+          this.syncEngine.off("message", handleResponse);
+          const events = message.events.map((e) => this.parseEvent(e));
+          resolve(events);
+        }
+      };
+      this.syncEngine.on("message", handleResponse);
+      this.syncEngine.send({
+        type: "JOURNAL_READ",
+        requestId,
+        fromSequence: sequence.toString(),
+        limit,
+        mapName
+      });
+    });
+  }
+  /**
+   * Subscribe to new journal events.
+   *
+   * @param listener Callback for each event
+   * @param options Subscription options
+   * @returns Unsubscribe function
+   */
+  subscribe(listener, options = {}) {
+    const subscriptionId = this.generateRequestId();
+    this.listeners.set(subscriptionId, listener);
+    const handleEvent = (message) => {
+      if (message.type === "JOURNAL_EVENT") {
+        const event = this.parseEvent(message.event);
+        if (options.mapName && event.mapName !== options.mapName) return;
+        if (options.types && !options.types.includes(event.type)) return;
+        const listenerFn = this.listeners.get(subscriptionId);
+        if (listenerFn) {
+          try {
+            listenerFn(event);
+          } catch (e) {
+            logger.error({ err: e }, "Journal listener error");
+          }
+        }
+      }
+    };
+    this.syncEngine.on("message", handleEvent);
+    this.syncEngine.send({
+      type: "JOURNAL_SUBSCRIBE",
+      requestId: subscriptionId,
+      fromSequence: options.fromSequence?.toString(),
+      mapName: options.mapName,
+      types: options.types
+    });
+    return () => {
+      this.listeners.delete(subscriptionId);
+      this.syncEngine.off("message", handleEvent);
+      this.syncEngine.send({
+        type: "JOURNAL_UNSUBSCRIBE",
+        subscriptionId
+      });
+    };
+  }
+  /**
+   * Get the latest sequence number from server.
+   */
+  async getLatestSequence() {
+    const events = await this.readFrom(0n, 1);
+    if (events.length === 0) return 0n;
+    return events[events.length - 1].sequence;
+  }
+  /**
+   * Parse network event data to JournalEvent.
+   */
+  parseEvent(raw) {
+    return {
+      sequence: BigInt(raw.sequence),
+      type: raw.type,
+      mapName: raw.mapName,
+      key: raw.key,
+      value: raw.value,
+      previousValue: raw.previousValue,
+      timestamp: raw.timestamp,
+      nodeId: raw.nodeId,
+      metadata: raw.metadata
+    };
+  }
+  /**
+   * Generate unique request ID.
+   */
+  generateRequestId() {
+    return `journal_${Date.now()}_${++this.subscriptionCounter}`;
+  }
+};
+
 // src/cluster/ClusterClient.ts
 import {
   DEFAULT_CONNECTION_POOL_CONFIG as DEFAULT_CONNECTION_POOL_CONFIG2,
@@ -3454,6 +4473,7 @@ var TopGunClient = class {
   constructor(config) {
     this.maps = /* @__PURE__ */ new Map();
     this.topicHandles = /* @__PURE__ */ new Map();
+    this.counters = /* @__PURE__ */ new Map();
     if (config.serverUrl && config.cluster) {
       throw new Error("Cannot specify both serverUrl and cluster config");
     }
@@ -3538,6 +4558,34 @@ var TopGunClient = class {
     }
     return this.topicHandles.get(name);
   }
+  /**
+   * Retrieves a PN Counter instance. If the counter doesn't exist locally, it's created.
+   * PN Counters support increment and decrement operations that work offline
+   * and sync to server when connected.
+   *
+   * @param name The name of the counter (e.g., 'likes:post-123')
+   * @returns A PNCounterHandle instance
+   *
+   * @example
+   * ```typescript
+   * const likes = client.getPNCounter('likes:post-123');
+   * likes.increment(); // +1
+   * likes.decrement(); // -1
+   * likes.addAndGet(10); // +10
+   *
+   * likes.subscribe((value) => {
+   *   console.log('Current likes:', value);
+   * });
+   * ```
+   */
+  getPNCounter(name) {
+    let counter = this.counters.get(name);
+    if (!counter) {
+      counter = new PNCounterHandle(name, this.nodeId, this.syncEngine, this.storageAdapter);
+      this.counters.set(name, counter);
+    }
+    return counter;
+  }
   /**
    * Retrieves an LWWMap instance. If the map doesn't exist locally, it's created.
    * @param name The name of the map.
@@ -3810,6 +4858,175 @@ var TopGunClient = class {
   onBackpressure(event, listener) {
     return this.syncEngine.onBackpressure(event, listener);
   }
+  // ============================================
+  // Entry Processor API (Phase 5.03)
+  // ============================================
+  /**
+   * Execute an entry processor on a single key atomically.
+   *
+   * Entry processors solve the read-modify-write race condition by executing
+   * user-defined logic atomically on the server where the data lives.
+   *
+   * @param mapName Name of the map
+   * @param key Key to process
+   * @param processor Processor definition with name, code, and optional args
+   * @returns Promise resolving to the processor result
+   *
+   * @example
+   * ```typescript
+   * // Increment a counter atomically
+   * const result = await client.executeOnKey('stats', 'pageViews', {
+   *   name: 'increment',
+   *   code: `
+   *     const current = value ?? 0;
+   *     return { value: current + 1, result: current + 1 };
+   *   `,
+   * });
+   *
+   * // Using built-in processor
+   * import { BuiltInProcessors } from '@topgunbuild/core';
+   * const result = await client.executeOnKey(
+   *   'stats',
+   *   'pageViews',
+   *   BuiltInProcessors.INCREMENT(1)
+   * );
+   * ```
+   */
+  async executeOnKey(mapName, key, processor) {
+    const result = await this.syncEngine.executeOnKey(mapName, key, processor);
+    if (result.success && result.newValue !== void 0) {
+      const map = this.maps.get(mapName);
+      if (map instanceof LWWMap2) {
+        map.set(key, result.newValue);
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute an entry processor on multiple keys.
+   *
+   * Each key is processed atomically. The operation returns when all keys
+   * have been processed.
+   *
+   * @param mapName Name of the map
+   * @param keys Keys to process
+   * @param processor Processor definition
+   * @returns Promise resolving to a map of key -> result
+   *
+   * @example
+   * ```typescript
+   * // Reset multiple counters
+   * const results = await client.executeOnKeys(
+   *   'stats',
+   *   ['pageViews', 'uniqueVisitors', 'bounceRate'],
+   *   {
+   *     name: 'reset',
+   *     code: `return { value: 0, result: value };`, // Returns old value
+   *   }
+   * );
+   *
+   * for (const [key, result] of results) {
+   *   console.log(`${key}: was ${result.result}, now 0`);
+   * }
+   * ```
+   */
+  async executeOnKeys(mapName, keys, processor) {
+    const results = await this.syncEngine.executeOnKeys(mapName, keys, processor);
+    const map = this.maps.get(mapName);
+    if (map instanceof LWWMap2) {
+      for (const [key, result] of results) {
+        if (result.success && result.newValue !== void 0) {
+          map.set(key, result.newValue);
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Get the Event Journal reader for subscribing to and reading
+   * map change events.
+   *
+   * The Event Journal provides:
+   * - Append-only log of all map changes (PUT, UPDATE, DELETE)
+   * - Subscription to real-time events
+   * - Historical event replay
+   * - Audit trail for compliance
+   *
+   * @returns EventJournalReader instance
+   *
+   * @example
+   * ```typescript
+   * const journal = client.getEventJournal();
+   *
+   * // Subscribe to all events
+   * const unsubscribe = journal.subscribe((event) => {
+   *   console.log(`${event.type} on ${event.mapName}:${event.key}`);
+   * });
+   *
+   * // Subscribe to specific map
+   * journal.subscribe(
+   *   (event) => console.log('User changed:', event.key),
+   *   { mapName: 'users' }
+   * );
+   *
+   * // Read historical events
+   * const events = await journal.readFrom(0n, 100);
+   * ```
+   */
+  getEventJournal() {
+    if (!this.journalReader) {
+      this.journalReader = new EventJournalReader(this.syncEngine);
+    }
+    return this.journalReader;
+  }
+  // ============================================
+  // Conflict Resolver API (Phase 5.05)
+  // ============================================
+  /**
+   * Get the conflict resolver client for registering custom merge resolvers.
+   *
+   * Conflict resolvers allow you to customize how merge conflicts are handled
+   * on the server. You can implement business logic like:
+   * - First-write-wins for booking systems
+   * - Numeric constraints (non-negative, min/max)
+   * - Owner-only modifications
+   * - Custom merge strategies
+   *
+   * @returns ConflictResolverClient instance
+   *
+   * @example
+   * ```typescript
+   * const resolvers = client.getConflictResolvers();
+   *
+   * // Register a first-write-wins resolver
+   * await resolvers.register('bookings', {
+   *   name: 'first-write-wins',
+   *   code: `
+   *     if (context.localValue !== undefined) {
+   *       return { action: 'reject', reason: 'Slot already booked' };
+   *     }
+   *     return { action: 'accept', value: context.remoteValue };
+   *   `,
+   *   priority: 100,
+   * });
+   *
+   * // Subscribe to merge rejections
+   * resolvers.onRejection((rejection) => {
+   *   console.log(`Merge rejected: ${rejection.reason}`);
+   *   // Optionally refresh local state
+   * });
+   *
+   * // List registered resolvers
+   * const registered = await resolvers.list('bookings');
+   * console.log('Active resolvers:', registered);
+   *
+   * // Unregister when done
+   * await resolvers.unregister('bookings', 'first-write-wins');
+   * ```
+   */
+  getConflictResolvers() {
+    return this.syncEngine.getConflictResolverClient();
+  }
 };
 
 // src/adapters/IDBAdapter.ts
@@ -4240,13 +5457,17 @@ var EncryptedStorageAdapter = class {
 import { LWWMap as LWWMap3, Predicates } from "@topgunbuild/core";
 export {
   BackpressureError,
+  ChangeTracker,
   ClusterClient,
+  ConflictResolverClient,
   ConnectionPool,
   DEFAULT_BACKPRESSURE_CONFIG,
   DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
+  EventJournalReader,
   IDBAdapter,
   LWWMap3 as LWWMap,
+  PNCounterHandle,
   PartitionRouter,
   Predicates,
   QueryHandle,