@topgunbuild/client 0.7.0 → 0.8.1

package/dist/index.js

@@ -39,12 +39,14 @@ __export(index_exports, {
   DEFAULT_CLUSTER_CONFIG: () => DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter: () => EncryptedStorageAdapter,
   EventJournalReader: () => EventJournalReader,
+  HybridQueryHandle: () => HybridQueryHandle,
   IDBAdapter: () => IDBAdapter,
   LWWMap: () => import_core9.LWWMap,
   PNCounterHandle: () => PNCounterHandle,
   PartitionRouter: () => PartitionRouter,
   Predicates: () => import_core9.Predicates,
   QueryHandle: () => QueryHandle,
+  SearchHandle: () => SearchHandle,
   SingleServerProvider: () => SingleServerProvider,
   SyncEngine: () => SyncEngine,
   SyncState: () => SyncState,
@@ -769,6 +771,16 @@ var _SyncEngine = class _SyncEngine {
     // ============================================
     /** Message listeners for journal and other generic messages */
     this.messageListeners = /* @__PURE__ */ new Set();
+    // ============================================
+    // Full-Text Search Methods (Phase 11.1a)
+    // ============================================
+    /** Pending search requests by requestId */
+    this.pendingSearchRequests = /* @__PURE__ */ new Map();
+    // ============================================
+    // Hybrid Query Support (Phase 12)
+    // ============================================
+    /** Active hybrid query subscriptions */
+    this.hybridQueries = /* @__PURE__ */ new Map();
     if (!config.serverUrl && !config.connectionProvider) {
       throw new Error("SyncEngine requires either serverUrl or connectionProvider");
     }
@@ -1654,6 +1666,21 @@ var _SyncEngine = class _SyncEngine {
         this.conflictResolverClient.handleMergeRejected(message);
         break;
       }
+      // ============ Full-Text Search Message Handlers (Phase 11.1a) ============
+      case "SEARCH_RESP": {
+        logger.debug({ requestId: message.payload?.requestId, resultCount: message.payload?.results?.length }, "Received SEARCH_RESP");
+        this.handleSearchResponse(message.payload);
+        break;
+      }
+      // ============ Live Search Message Handlers (Phase 11.1b) ============
+      case "SEARCH_UPDATE": {
+        logger.debug({
+          subscriptionId: message.payload?.subscriptionId,
+          key: message.payload?.key,
+          type: message.payload?.type
+        }, "Received SEARCH_UPDATE");
+        break;
+      }
     }
     if (message.timestamp) {
       this.hlc.update(message.timestamp);
@@ -2417,6 +2444,65 @@ var _SyncEngine = class _SyncEngine {
       }
     }
   }
+  /**
+   * Perform a one-shot BM25 search on the server.
+   *
+   * @param mapName Name of the map to search
+   * @param query Search query text
+   * @param options Search options (limit, minScore, boost)
+   * @returns Promise resolving to search results
+   */
+  async search(mapName, query, options) {
+    if (!this.isAuthenticated()) {
+      throw new Error("Not connected to server");
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingSearchRequests.delete(requestId);
+        reject(new Error("Search request timed out"));
+      }, _SyncEngine.SEARCH_TIMEOUT);
+      this.pendingSearchRequests.set(requestId, {
+        resolve: (results) => {
+          clearTimeout(timeout);
+          resolve(results);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+        timeout
+      });
+      const sent = this.sendMessage({
+        type: "SEARCH",
+        payload: {
+          requestId,
+          mapName,
+          query,
+          options
+        }
+      });
+      if (!sent) {
+        this.pendingSearchRequests.delete(requestId);
+        clearTimeout(timeout);
+        reject(new Error("Failed to send search request"));
+      }
+    });
+  }
+  /**
+   * Handle search response from server.
+   */
+  handleSearchResponse(payload) {
+    const pending = this.pendingSearchRequests.get(payload.requestId);
+    if (pending) {
+      this.pendingSearchRequests.delete(payload.requestId);
+      if (payload.error) {
+        pending.reject(new Error(payload.error));
+      } else {
+        pending.resolve(payload.results);
+      }
+    }
+  }
   // ============================================
   // Conflict Resolver Client (Phase 5.05)
   // ============================================
@@ -2427,9 +2513,156 @@ var _SyncEngine = class _SyncEngine {
   getConflictResolverClient() {
     return this.conflictResolverClient;
   }
+  /**
+   * Subscribe to a hybrid query (FTS + filter combination).
+   */
+  subscribeToHybridQuery(query) {
+    this.hybridQueries.set(query.id, query);
+    const filter = query.getFilter();
+    const mapName = query.getMapName();
+    if (query.hasFTSPredicate() && this.stateMachine.getState() === "CONNECTED" /* CONNECTED */) {
+      this.sendHybridQuerySubscription(query.id, mapName, filter);
+    }
+    this.runLocalHybridQuery(mapName, filter).then((results) => {
+      query.onResult(results, "local");
+    });
+  }
+  /**
+   * Unsubscribe from a hybrid query.
+   */
+  unsubscribeFromHybridQuery(queryId) {
+    const query = this.hybridQueries.get(queryId);
+    if (query) {
+      this.hybridQueries.delete(queryId);
+      if (this.stateMachine.getState() === "CONNECTED" /* CONNECTED */ && query.hasFTSPredicate()) {
+        this.sendMessage({
+          type: "HYBRID_QUERY_UNSUBSCRIBE",
+          payload: { subscriptionId: queryId }
+        });
+      }
+    }
+  }
+  /**
+   * Send hybrid query subscription to server.
+   */
+  sendHybridQuerySubscription(queryId, mapName, filter) {
+    this.sendMessage({
+      type: "HYBRID_QUERY_SUBSCRIBE",
+      payload: {
+        subscriptionId: queryId,
+        mapName,
+        predicate: filter.predicate,
+        where: filter.where,
+        sort: filter.sort,
+        limit: filter.limit,
+        offset: filter.offset
+      }
+    });
+  }
+  /**
+   * Run a local hybrid query (FTS + filter combination).
+   * For FTS predicates, returns results with score = 0 (local-only mode).
+   * Server provides actual FTS scoring.
+   */
+  async runLocalHybridQuery(mapName, filter) {
+    if (!this.storageAdapter) {
+      return [];
+    }
+    const results = [];
+    const allKeys = await this.storageAdapter.getAllKeys();
+    const mapPrefix = `${mapName}:`;
+    const entries = [];
+    for (const fullKey of allKeys) {
+      if (fullKey.startsWith(mapPrefix)) {
+        const key = fullKey.substring(mapPrefix.length);
+        const record = await this.storageAdapter.get(fullKey);
+        if (record) {
+          entries.push([key, record]);
+        }
+      }
+    }
+    for (const [key, record] of entries) {
+      if (record === null || record.value === null) continue;
+      const value = record.value;
+      if (filter.predicate) {
+        const matches = (0, import_core.evaluatePredicate)(filter.predicate, value);
+        if (!matches) continue;
+      }
+      if (filter.where) {
+        let whereMatches = true;
+        for (const [field, expected] of Object.entries(filter.where)) {
+          if (value[field] !== expected) {
+            whereMatches = false;
+            break;
+          }
+        }
+        if (!whereMatches) continue;
+      }
+      results.push({
+        key,
+        value,
+        score: 0,
+        // Local doesn't have FTS scoring
+        matchedTerms: []
+      });
+    }
+    if (filter.sort) {
+      results.sort((a, b) => {
+        for (const [field, direction] of Object.entries(filter.sort)) {
+          let valA;
+          let valB;
+          if (field === "_score") {
+            valA = a.score ?? 0;
+            valB = b.score ?? 0;
+          } else if (field === "_key") {
+            valA = a.key;
+            valB = b.key;
+          } else {
+            valA = a.value[field];
+            valB = b.value[field];
+          }
+          if (valA < valB) return direction === "asc" ? -1 : 1;
+          if (valA > valB) return direction === "asc" ? 1 : -1;
+        }
+        return 0;
+      });
+    }
+    let sliced = results;
+    if (filter.offset) {
+      sliced = sliced.slice(filter.offset);
+    }
+    if (filter.limit) {
+      sliced = sliced.slice(0, filter.limit);
+    }
+    return sliced;
+  }
+  /**
+   * Handle hybrid query response from server.
+   */
+  handleHybridQueryResponse(payload) {
+    const query = this.hybridQueries.get(payload.subscriptionId);
+    if (query) {
+      query.onResult(payload.results, "server");
+    }
+  }
+  /**
+   * Handle hybrid query delta update from server.
+   */
+  handleHybridQueryDelta(payload) {
+    const query = this.hybridQueries.get(payload.subscriptionId);
+    if (query) {
+      if (payload.type === "LEAVE") {
+        query.onUpdate(payload.key, null);
+      } else {
+        query.onUpdate(payload.key, payload.value, payload.score, payload.matchedTerms);
+      }
+    }
+  }
 };
 /** Default timeout for entry processor requests (ms) */
 _SyncEngine.PROCESSOR_TIMEOUT = 3e4;
+/** Default timeout for search requests (ms) */
+_SyncEngine.SEARCH_TIMEOUT = 3e4;
 var SyncEngine = _SyncEngine;
 
 // src/TopGunClient.ts
@@ -3095,6 +3328,446 @@ var EventJournalReader = class {
   }
 };
 
+// src/SearchHandle.ts
+var SearchHandle = class {
+  constructor(syncEngine, mapName, query, options) {
+    /** Current results map (key → result) */
+    this.results = /* @__PURE__ */ new Map();
+    /** Result change listeners */
+    this.listeners = /* @__PURE__ */ new Set();
+    /** Whether the handle has been disposed */
+    this.disposed = false;
+    this.syncEngine = syncEngine;
+    this.mapName = mapName;
+    this._query = query;
+    this._options = options;
+    this.subscriptionId = crypto.randomUUID();
+    this.messageHandler = this.handleMessage.bind(this);
+    this.syncEngine.on("message", this.messageHandler);
+    this.sendSubscribe();
+  }
+  /**
+   * Handle incoming messages (both SEARCH_RESP and SEARCH_UPDATE).
+   */
+  handleMessage(message) {
+    if (message.type === "SEARCH_RESP") {
+      this.handleSearchResponse(message);
+    } else if (message.type === "SEARCH_UPDATE") {
+      this.handleSearchUpdate(message);
+    }
+  }
+  /**
+   * Get the current query string.
+   */
+  get query() {
+    return this._query;
+  }
+  /**
+   * Subscribe to result changes.
+   * Callback is immediately called with current results.
+   *
+   * @param callback - Function called with updated results
+   * @returns Unsubscribe function
+   */
+  subscribe(callback) {
+    if (this.disposed) {
+      throw new Error("SearchHandle has been disposed");
+    }
+    this.listeners.add(callback);
+    callback(this.getResults());
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+  /**
+   * Get current results snapshot sorted by score (highest first).
+   *
+   * @returns Array of search results
+   */
+  getResults() {
+    return Array.from(this.results.values()).sort((a, b) => b.score - a.score);
+  }
+  /**
+   * Get result count.
+   */
+  get size() {
+    return this.results.size;
+  }
+  /**
+   * Update the search query.
+   * Triggers a new subscription with the updated query.
+   *
+   * @param query - New query string
+   */
+  setQuery(query) {
+    if (this.disposed) {
+      throw new Error("SearchHandle has been disposed");
+    }
+    if (query === this._query) {
+      return;
+    }
+    this.sendUnsubscribe();
+    this.results.clear();
+    this._query = query;
+    this.subscriptionId = crypto.randomUUID();
+    this.sendSubscribe();
+    this.notifyListeners();
+  }
+  /**
+   * Update search options.
+   *
+   * @param options - New search options
+   */
+  setOptions(options) {
+    if (this.disposed) {
+      throw new Error("SearchHandle has been disposed");
+    }
+    this.sendUnsubscribe();
+    this.results.clear();
+    this._options = options;
+    this.subscriptionId = crypto.randomUUID();
+    this.sendSubscribe();
+    this.notifyListeners();
+  }
+  /**
+   * Dispose of the handle and cleanup resources.
+   * After disposal, the handle cannot be used.
+   */
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.sendUnsubscribe();
+    this.syncEngine.off("message", this.messageHandler);
+    this.results.clear();
+    this.listeners.clear();
+  }
+  /**
+   * Check if handle is disposed.
+   */
+  isDisposed() {
+    return this.disposed;
+  }
+  /**
+   * Send SEARCH_SUB message to server.
+   */
+  sendSubscribe() {
+    this.syncEngine.send({
+      type: "SEARCH_SUB",
+      payload: {
+        subscriptionId: this.subscriptionId,
+        mapName: this.mapName,
+        query: this._query,
+        options: this._options
+      }
+    });
+  }
+  /**
+   * Send SEARCH_UNSUB message to server.
+   */
+  sendUnsubscribe() {
+    this.syncEngine.send({
+      type: "SEARCH_UNSUB",
+      payload: {
+        subscriptionId: this.subscriptionId
+      }
+    });
+  }
+  /**
+   * Handle SEARCH_RESP message (initial results).
+   */
+  handleSearchResponse(message) {
+    if (message.type !== "SEARCH_RESP") return;
+    if (message.payload?.requestId !== this.subscriptionId) return;
+    const { results } = message.payload;
+    if (Array.isArray(results)) {
+      for (const result of results) {
+        this.results.set(result.key, {
+          key: result.key,
+          value: result.value,
+          score: result.score,
+          matchedTerms: result.matchedTerms || []
+        });
+      }
+      this.notifyListeners();
+    }
+  }
+  /**
+   * Handle SEARCH_UPDATE message (delta updates).
+   */
+  handleSearchUpdate(message) {
+    if (message.type !== "SEARCH_UPDATE") return;
+    if (message.payload?.subscriptionId !== this.subscriptionId) return;
+    const { key, value, score, matchedTerms, type } = message.payload;
+    switch (type) {
+      case "ENTER":
+        this.results.set(key, {
+          key,
+          value,
+          score,
+          matchedTerms: matchedTerms || []
+        });
+        break;
+      case "UPDATE":
+        const existing = this.results.get(key);
+        if (existing) {
+          existing.score = score;
+          existing.matchedTerms = matchedTerms || [];
+          existing.value = value;
+        }
+        break;
+      case "LEAVE":
+        this.results.delete(key);
+        break;
+    }
+    this.notifyListeners();
+  }
+  /**
+   * Notify all listeners of result changes.
+   */
+  notifyListeners() {
+    const results = this.getResults();
+    for (const listener of this.listeners) {
+      try {
+        listener(results);
+      } catch (err) {
+        console.error("SearchHandle listener error:", err);
+      }
+    }
+  }
+};
+
+// src/HybridQueryHandle.ts
+var HybridQueryHandle = class {
+  constructor(syncEngine, mapName, filter = {}) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.currentResults = /* @__PURE__ */ new Map();
+    // Change tracking
+    this.changeTracker = new ChangeTracker();
+    this.pendingChanges = [];
+    this.changeListeners = /* @__PURE__ */ new Set();
+    // Track server data reception
+    this.hasReceivedServerData = false;
+    this.id = crypto.randomUUID();
+    this.syncEngine = syncEngine;
+    this.mapName = mapName;
+    this.filter = filter;
+  }
+  /**
+   * Subscribe to query results.
+   */
+  subscribe(callback) {
+    this.listeners.add(callback);
+    if (this.listeners.size === 1) {
+      this.syncEngine.subscribeToHybridQuery(this);
+    } else {
+      callback(this.getSortedResults());
+    }
+    this.loadInitialLocalData().then((data) => {
+      if (this.currentResults.size === 0) {
+        this.onResult(data, "local");
+      }
+    });
+    return () => {
+      this.listeners.delete(callback);
+      if (this.listeners.size === 0) {
+        this.syncEngine.unsubscribeFromHybridQuery(this.id);
+      }
+    };
+  }
+  async loadInitialLocalData() {
+    return this.syncEngine.runLocalHybridQuery(this.mapName, this.filter);
+  }
+  /**
+   * Called by SyncEngine with query results.
+   */
+  onResult(items, source = "server") {
+    logger.debug(
+      {
+        mapName: this.mapName,
+        itemCount: items.length,
+        source,
+        currentResultsCount: this.currentResults.size,
+        hasReceivedServerData: this.hasReceivedServerData
+      },
+      "HybridQueryHandle onResult"
+    );
+    if (source === "server" && items.length === 0 && !this.hasReceivedServerData) {
+      logger.debug(
+        { mapName: this.mapName },
+        "HybridQueryHandle ignoring empty server response"
+      );
+      return;
+    }
+    if (source === "server" && items.length > 0) {
+      this.hasReceivedServerData = true;
+    }
+    const newKeys = new Set(items.map((i) => i.key));
+    for (const key of this.currentResults.keys()) {
+      if (!newKeys.has(key)) {
+        this.currentResults.delete(key);
+      }
+    }
+    for (const item of items) {
+      this.currentResults.set(item.key, {
+        value: item.value,
+        score: item.score,
+        matchedTerms: item.matchedTerms
+      });
+    }
+    this.computeAndNotifyChanges(Date.now());
+    this.notify();
+  }
+  /**
+   * Called by SyncEngine on live update.
+   */
+  onUpdate(key, value, score, matchedTerms) {
+    if (value === null) {
+      this.currentResults.delete(key);
+    } else {
+      this.currentResults.set(key, { value, score, matchedTerms });
+    }
+    this.computeAndNotifyChanges(Date.now());
+    this.notify();
+  }
+  /**
+   * Subscribe to change events.
+   */
+  onChanges(listener) {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+  /**
+   * Get and clear pending changes.
+   */
+  consumeChanges() {
+    const changes = [...this.pendingChanges];
+    this.pendingChanges = [];
+    return changes;
+  }
+  /**
+   * Get last change without consuming.
+   */
+  getLastChange() {
+    return this.pendingChanges.length > 0 ? this.pendingChanges[this.pendingChanges.length - 1] : null;
+  }
+  /**
+   * Get all pending changes without consuming.
+   */
+  getPendingChanges() {
+    return [...this.pendingChanges];
+  }
+  /**
+   * Clear all pending changes.
+   */
+  clearChanges() {
+    this.pendingChanges = [];
+  }
+  /**
+   * Reset change tracker.
+   */
+  resetChangeTracker() {
+    this.changeTracker.reset();
+    this.pendingChanges = [];
+  }
+  computeAndNotifyChanges(timestamp) {
+    const dataMap = /* @__PURE__ */ new Map();
+    for (const [key, entry] of this.currentResults) {
+      dataMap.set(key, entry.value);
+    }
+    const changes = this.changeTracker.computeChanges(dataMap, 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 }, "HybridQueryHandle change listener error");
+      }
+    }
+  }
+  notify() {
+    const results = this.getSortedResults();
+    for (const listener of this.listeners) {
+      listener(results);
+    }
+  }
+  /**
+   * Get sorted results with _key and _score.
+   */
+  getSortedResults() {
+    const results = Array.from(this.currentResults.entries()).map(
+      ([key, entry]) => ({
+        value: entry.value,
+        _key: key,
+        _score: entry.score,
+        _matchedTerms: entry.matchedTerms
+      })
+    );
+    if (this.filter.sort) {
+      results.sort((a, b) => {
+        for (const [field, direction] of Object.entries(this.filter.sort)) {
+          let valA;
+          let valB;
+          if (field === "_score") {
+            valA = a._score ?? 0;
+            valB = b._score ?? 0;
+          } else if (field === "_key") {
+            valA = a._key;
+            valB = b._key;
+          } else {
+            valA = a.value[field];
+            valB = b.value[field];
+          }
+          if (valA < valB) return direction === "asc" ? -1 : 1;
+          if (valA > valB) return direction === "asc" ? 1 : -1;
+        }
+        return 0;
+      });
+    }
+    let sliced = results;
+    if (this.filter.offset) {
+      sliced = sliced.slice(this.filter.offset);
+    }
+    if (this.filter.limit) {
+      sliced = sliced.slice(0, this.filter.limit);
+    }
+    return sliced;
+  }
+  /**
+   * Get the filter configuration.
+   */
+  getFilter() {
+    return this.filter;
+  }
+  /**
+   * Get the map name.
+   */
+  getMapName() {
+    return this.mapName;
+  }
+  /**
+   * Check if this query contains FTS predicates.
+   */
+  hasFTSPredicate() {
+    return this.filter.predicate ? this.containsFTS(this.filter.predicate) : false;
+  }
+  containsFTS(predicate) {
+    if (predicate.op === "match" || predicate.op === "matchPhrase" || predicate.op === "matchPrefix") {
+      return true;
+    }
+    if (predicate.children) {
+      return predicate.children.some((child) => this.containsFTS(child));
+    }
+    return false;
+  }
+};
+
 // src/cluster/ClusterClient.ts
 var import_core6 = require("@topgunbuild/core");
 
@@ -4908,6 +5581,113 @@ var TopGunClient = class {
     return this.syncEngine.onBackpressure(event, listener);
   }
   // ============================================
+  // Full-Text Search API (Phase 11.1a)
+  // ============================================
+  /**
+   * Perform a one-shot BM25 search on the server.
+   *
+   * Searches the specified map using BM25 ranking algorithm.
+   * Requires FTS to be enabled for the map on the server.
+   *
+   * @param mapName Name of the map to search
+   * @param query Search query text
+   * @param options Search options
+   * @returns Promise resolving to search results sorted by relevance
+   *
+   * @example
+   * ```typescript
+   * const results = await client.search<Article>('articles', 'machine learning', {
+   *   limit: 20,
+   *   minScore: 0.5,
+   *   boost: { title: 2.0, body: 1.0 }
+   * });
+   *
+   * for (const result of results) {
+   *   console.log(`${result.key}: ${result.value.title} (score: ${result.score})`);
+   * }
+   * ```
+   */
+  async search(mapName, query, options) {
+    return this.syncEngine.search(mapName, query, options);
+  }
+  // ============================================
+  // Live Search API (Phase 11.1b)
+  // ============================================
+  /**
+   * Subscribe to live search results with real-time updates.
+   *
+   * Unlike the one-shot `search()` method, `searchSubscribe()` returns a handle
+   * that receives delta updates (ENTER/UPDATE/LEAVE) when documents change.
+   * This is ideal for live search UIs that need to reflect data changes.
+   *
+   * @param mapName Name of the map to search
+   * @param query Search query text
+   * @param options Search options (limit, minScore, boost)
+   * @returns SearchHandle for managing the subscription
+   *
+   * @example
+   * ```typescript
+   * const handle = client.searchSubscribe<Article>('articles', 'machine learning', {
+   *   limit: 20,
+   *   minScore: 0.5
+   * });
+   *
+   * // Subscribe to result changes
+   * const unsubscribe = handle.subscribe((results) => {
+   *   setSearchResults(results);
+   * });
+   *
+   * // Update query dynamically
+   * handle.setQuery('deep learning');
+   *
+   * // Get current snapshot
+   * const snapshot = handle.getResults();
+   *
+   * // Cleanup when done
+   * handle.dispose();
+   * ```
+   */
+  searchSubscribe(mapName, query, options) {
+    return new SearchHandle(this.syncEngine, mapName, query, options);
+  }
+  // ============================================
+  // Hybrid Query API (Phase 12)
+  // ============================================
+  /**
+   * Create a hybrid query combining FTS with traditional filters.
+   *
+   * Hybrid queries allow combining full-text search predicates (match, matchPhrase, matchPrefix)
+   * with traditional filter predicates (eq, gt, lt, contains, etc.) in a single query.
+   * Results include relevance scores for FTS ranking.
+   *
+   * @param mapName Name of the map to query
+   * @param filter Hybrid query filter with predicate, where, sort, limit, offset
+   * @returns HybridQueryHandle for managing the subscription
+   *
+   * @example
+   * ```typescript
+   * import { Predicates } from '@topgunbuild/core';
+   *
+   * // Hybrid query: FTS + filter
+   * const handle = client.hybridQuery<Article>('articles', {
+   *   predicate: Predicates.and(
+   *     Predicates.match('body', 'machine learning'),
+   *     Predicates.equal('category', 'tech')
+   *   ),
+   *   sort: { _score: 'desc' },
+   *   limit: 20
+   * });
+   *
+   * // Subscribe to results
+   * handle.subscribe((results) => {
+   *   results.forEach(r => console.log(`${r._key}: score=${r._score}`));
+   * });
+   * ```
+   */
+  hybridQuery(mapName, filter = {}) {
+    return new HybridQueryHandle(this.syncEngine, mapName, filter);
+  }
+  // ============================================
   // Entry Processor API (Phase 5.03)
   // ============================================
   /**
@@ -5515,12 +6295,14 @@ var import_core9 = require("@topgunbuild/core");
   DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
   EventJournalReader,
+  HybridQueryHandle,
   IDBAdapter,
   LWWMap,
   PNCounterHandle,
   PartitionRouter,
   Predicates,
   QueryHandle,
+  SearchHandle,
   SingleServerProvider,
   SyncEngine,
   SyncState,