@topgunbuild/core 0.8.1 → 0.10.0

package/dist/index.js

@@ -37,6 +37,24 @@ __export(index_exports, {
   BuiltInResolvers: () => BuiltInResolvers,
   ClientOpMessageSchema: () => ClientOpMessageSchema,
   ClientOpSchema: () => ClientOpSchema,
+  ClusterSearchReqMessageSchema: () => ClusterSearchReqMessageSchema,
+  ClusterSearchReqPayloadSchema: () => ClusterSearchReqPayloadSchema,
+  ClusterSearchRespMessageSchema: () => ClusterSearchRespMessageSchema,
+  ClusterSearchRespPayloadSchema: () => ClusterSearchRespPayloadSchema,
+  ClusterSearchSubscribeMessageSchema: () => ClusterSearchSubscribeMessageSchema,
+  ClusterSearchSubscribePayloadSchema: () => ClusterSearchSubscribePayloadSchema,
+  ClusterSearchUnsubscribeMessageSchema: () => ClusterSearchUnsubscribeMessageSchema,
+  ClusterSearchUnsubscribePayloadSchema: () => ClusterSearchUnsubscribePayloadSchema,
+  ClusterSearchUpdateMessageSchema: () => ClusterSearchUpdateMessageSchema,
+  ClusterSearchUpdatePayloadSchema: () => ClusterSearchUpdatePayloadSchema,
+  ClusterSubAckMessageSchema: () => ClusterSubAckMessageSchema,
+  ClusterSubAckPayloadSchema: () => ClusterSubAckPayloadSchema,
+  ClusterSubRegisterMessageSchema: () => ClusterSubRegisterMessageSchema,
+  ClusterSubRegisterPayloadSchema: () => ClusterSubRegisterPayloadSchema,
+  ClusterSubUnregisterMessageSchema: () => ClusterSubUnregisterMessageSchema,
+  ClusterSubUnregisterPayloadSchema: () => ClusterSubUnregisterPayloadSchema,
+  ClusterSubUpdateMessageSchema: () => ClusterSubUpdateMessageSchema,
+  ClusterSubUpdatePayloadSchema: () => ClusterSubUpdatePayloadSchema,
   ConflictResolverDefSchema: () => ConflictResolverDefSchema,
   ConflictResolverSchema: () => ConflictResolverSchema,
   ConsistencyLevel: () => ConsistencyLevel,
@@ -44,13 +62,16 @@ __export(index_exports, {
   CounterResponseSchema: () => CounterResponseSchema,
   CounterSyncSchema: () => CounterSyncSchema,
   CounterUpdateSchema: () => CounterUpdateSchema,
+  CursorStatusSchema: () => CursorStatusSchema,
   DEFAULT_BACKUP_COUNT: () => DEFAULT_BACKUP_COUNT,
   DEFAULT_CIRCUIT_BREAKER_CONFIG: () => DEFAULT_CIRCUIT_BREAKER_CONFIG,
   DEFAULT_CONNECTION_POOL_CONFIG: () => DEFAULT_CONNECTION_POOL_CONFIG,
+  DEFAULT_CURSOR_MAX_AGE_MS: () => DEFAULT_CURSOR_MAX_AGE_MS,
   DEFAULT_EVENT_JOURNAL_CONFIG: () => DEFAULT_EVENT_JOURNAL_CONFIG,
   DEFAULT_MIGRATION_CONFIG: () => DEFAULT_MIGRATION_CONFIG,
   DEFAULT_PARTITION_ROUTER_CONFIG: () => DEFAULT_PARTITION_ROUTER_CONFIG,
   DEFAULT_PROCESSOR_RATE_LIMITS: () => DEFAULT_PROCESSOR_RATE_LIMITS,
+  DEFAULT_QUERY_CURSOR_MAX_AGE_MS: () => DEFAULT_QUERY_CURSOR_MAX_AGE_MS,
   DEFAULT_REPLICATION_CONFIG: () => DEFAULT_REPLICATION_CONFIG,
   DEFAULT_RESOLVER_RATE_LIMITS: () => DEFAULT_RESOLVER_RATE_LIMITS,
   DEFAULT_STOP_WORDS: () => DEFAULT_STOP_WORDS,
@@ -128,7 +149,10 @@ __export(index_exports, {
   PredicateNodeSchema: () => PredicateNodeSchema,
   PredicateOpSchema: () => PredicateOpSchema,
   Predicates: () => Predicates,
+  QueryCursor: () => QueryCursor,
   QueryOptimizer: () => QueryOptimizer,
+  QueryRespMessageSchema: () => QueryRespMessageSchema,
+  QueryRespPayloadSchema: () => QueryRespPayloadSchema,
   QuerySchema: () => QuerySchema,
   QuerySubMessageSchema: () => QuerySubMessageSchema,
   QueryUnsubMessageSchema: () => QueryUnsubMessageSchema,
@@ -137,6 +161,7 @@ __export(index_exports, {
   RegisterResolverRequestSchema: () => RegisterResolverRequestSchema,
   RegisterResolverResponseSchema: () => RegisterResolverResponseSchema,
   Ringbuffer: () => Ringbuffer,
+  SearchCursor: () => SearchCursor,
   SearchMessageSchema: () => SearchMessageSchema,
   SearchOptionsSchema: () => SearchOptionsSchema,
   SearchPayloadSchema: () => SearchPayloadSchema,
@@ -179,15 +204,19 @@ __export(index_exports, {
   combineHashes: () => combineHashes,
   compareHLCTimestamps: () => compareHLCTimestamps,
   compareTimestamps: () => compareTimestamps,
+  compareValues: () => compareValues,
   createFieldComparator: () => createFieldComparator,
   createPredicateMatcher: () => createPredicateMatcher,
+  decodeBase64Url: () => decodeBase64Url,
   deepMerge: () => deepMerge,
   deserialize: () => deserialize,
   disableNativeHash: () => disableNativeHash,
+  encodeBase64Url: () => encodeBase64Url,
   evaluatePredicate: () => evaluatePredicate,
   getHighestWriteConcernLevel: () => getHighestWriteConcernLevel,
   hashORMapEntry: () => hashORMapEntry,
   hashORMapRecord: () => hashORMapRecord,
+  hashObject: () => hashObject,
   hashString: () => hashString,
   isLogicalQuery: () => isLogicalQuery,
   isSimpleQuery: () => isSimpleQuery,
@@ -337,6 +366,18 @@ function resetNativeHash() {
   nativeHash = null;
   nativeLoadAttempted = false;
 }
+function hashObject(obj) {
+  const json = JSON.stringify(obj, (_, value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce((sorted, key) => {
+        sorted[key] = value[key];
+        return sorted;
+      }, {});
+    }
+    return value;
+  });
+  return hashString(json);
+}
 
 // src/MerkleTree.ts
 var MerkleTree = class {
@@ -2365,7 +2406,24 @@ var QuerySchema = import_zod3.z.object({
   predicate: PredicateNodeSchema.optional(),
   sort: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.enum(["asc", "desc"])).optional(),
   limit: import_zod3.z.number().optional(),
-  offset: import_zod3.z.number().optional()
+  cursor: import_zod3.z.string().optional()
+  // Phase 14.1: replaces offset
+});
+var CursorStatusSchema = import_zod3.z.enum(["valid", "expired", "invalid", "none"]);
+var QueryRespPayloadSchema = import_zod3.z.object({
+  queryId: import_zod3.z.string(),
+  results: import_zod3.z.array(import_zod3.z.object({
+    key: import_zod3.z.string(),
+    value: import_zod3.z.unknown()
+  })),
+  nextCursor: import_zod3.z.string().optional(),
+  hasMore: import_zod3.z.boolean().optional(),
+  /** Debug info: status of input cursor processing */
+  cursorStatus: CursorStatusSchema.optional()
+});
+var QueryRespMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("QUERY_RESP"),
+  payload: QueryRespPayloadSchema
 });
 var ClientOpSchema = import_zod3.z.object({
   id: import_zod3.z.string().optional(),
@@ -2845,6 +2903,87 @@ var OpRejectedMessageSchema = import_zod3.z.object({
     code: import_zod3.z.number().optional()
   })
 });
+var ClusterSubRegisterPayloadSchema = import_zod3.z.object({
+  /** Unique subscription ID */
+  subscriptionId: import_zod3.z.string(),
+  /** Node ID of the coordinator (receives updates) */
+  coordinatorNodeId: import_zod3.z.string(),
+  /** Map name to subscribe to */
+  mapName: import_zod3.z.string(),
+  /** Subscription type */
+  type: import_zod3.z.enum(["SEARCH", "QUERY"]),
+  // For FTS subscriptions
+  /** Search query string (for SEARCH type) */
+  searchQuery: import_zod3.z.string().optional(),
+  /** Search options (for SEARCH type) */
+  searchOptions: import_zod3.z.object({
+    limit: import_zod3.z.number().int().positive().optional(),
+    minScore: import_zod3.z.number().optional(),
+    boost: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.number()).optional()
+  }).optional(),
+  // For Query subscriptions
+  /** Query predicate (for QUERY type) */
+  queryPredicate: import_zod3.z.any().optional(),
+  /** Query sort order (for QUERY type) */
+  querySort: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.enum(["asc", "desc"])).optional()
+});
+var ClusterSubRegisterMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SUB_REGISTER"),
+  payload: ClusterSubRegisterPayloadSchema
+});
+var ClusterSubAckPayloadSchema = import_zod3.z.object({
+  /** Correlates to subscriptionId */
+  subscriptionId: import_zod3.z.string(),
+  /** Node that registered this subscription */
+  nodeId: import_zod3.z.string(),
+  /** Registration success status */
+  success: import_zod3.z.boolean(),
+  /** Error message if failed */
+  error: import_zod3.z.string().optional(),
+  /** Initial results from this node */
+  initialResults: import_zod3.z.array(import_zod3.z.object({
+    key: import_zod3.z.string(),
+    value: import_zod3.z.unknown(),
+    score: import_zod3.z.number().optional(),
+    matchedTerms: import_zod3.z.array(import_zod3.z.string()).optional()
+  })).optional(),
+  /** Total matching documents on this node */
+  totalHits: import_zod3.z.number().int().nonnegative().optional()
+});
+var ClusterSubAckMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SUB_ACK"),
+  payload: ClusterSubAckPayloadSchema
+});
+var ClusterSubUpdatePayloadSchema = import_zod3.z.object({
+  /** Subscription ID this update belongs to */
+  subscriptionId: import_zod3.z.string(),
+  /** Node that produced this update */
+  sourceNodeId: import_zod3.z.string(),
+  /** Document key */
+  key: import_zod3.z.string(),
+  /** Document value (null for LEAVE) */
+  value: import_zod3.z.unknown(),
+  /** Search score (for SEARCH type) */
+  score: import_zod3.z.number().optional(),
+  /** Matched terms (for SEARCH type) */
+  matchedTerms: import_zod3.z.array(import_zod3.z.string()).optional(),
+  /** Change type: ENTER (new match), UPDATE (still matches), LEAVE (no longer matches) */
+  changeType: import_zod3.z.enum(["ENTER", "UPDATE", "LEAVE"]),
+  /** Timestamp for ordering */
+  timestamp: import_zod3.z.number()
+});
+var ClusterSubUpdateMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SUB_UPDATE"),
+  payload: ClusterSubUpdatePayloadSchema
+});
+var ClusterSubUnregisterPayloadSchema = import_zod3.z.object({
+  /** Subscription ID to remove */
+  subscriptionId: import_zod3.z.string()
+});
+var ClusterSubUnregisterMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SUB_UNREGISTER"),
+  payload: ClusterSubUnregisterPayloadSchema
+});
 var MessageSchema = import_zod3.z.discriminatedUnion("type", [
   AuthMessageSchema,
   QuerySubMessageSchema,
@@ -2902,8 +3041,95 @@ var MessageSchema = import_zod3.z.discriminatedUnion("type", [
   // Phase 11.1b: Live Search Subscriptions
   SearchSubMessageSchema,
   SearchUpdateMessageSchema,
-  SearchUnsubMessageSchema
+  SearchUnsubMessageSchema,
+  // Phase 14.2: Distributed Live Subscriptions (cluster-internal)
+  ClusterSubRegisterMessageSchema,
+  ClusterSubAckMessageSchema,
+  ClusterSubUpdateMessageSchema,
+  ClusterSubUnregisterMessageSchema
 ]);
+var ClusterSearchReqPayloadSchema = import_zod3.z.object({
+  /** Unique request ID for correlation */
+  requestId: import_zod3.z.string(),
+  /** Map name to search */
+  mapName: import_zod3.z.string(),
+  /** Search query text */
+  query: import_zod3.z.string(),
+  /** Search options */
+  options: import_zod3.z.object({
+    /** Maximum results per node (for Top-K) */
+    limit: import_zod3.z.number().int().positive().max(1e3),
+    /** Minimum score threshold */
+    minScore: import_zod3.z.number().optional(),
+    /** Fields to boost */
+    boost: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.number()).optional(),
+    /** Include matched terms in response */
+    includeMatchedTerms: import_zod3.z.boolean().optional(),
+    /** For cursor-based pagination: return results after this score */
+    afterScore: import_zod3.z.number().optional(),
+    /** For cursor-based pagination: return results after this key (tie-breaking) */
+    afterKey: import_zod3.z.string().optional()
+  }),
+  /** Timeout in milliseconds */
+  timeoutMs: import_zod3.z.number().int().positive().optional()
+});
+var ClusterSearchReqMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SEARCH_REQ"),
+  payload: ClusterSearchReqPayloadSchema
+});
+var ClusterSearchRespPayloadSchema = import_zod3.z.object({
+  /** Correlates to requestId */
+  requestId: import_zod3.z.string(),
+  /** Node that produced these results */
+  nodeId: import_zod3.z.string(),
+  /** Search results with scores */
+  results: import_zod3.z.array(import_zod3.z.object({
+    key: import_zod3.z.string(),
+    value: import_zod3.z.unknown(),
+    score: import_zod3.z.number(),
+    matchedTerms: import_zod3.z.array(import_zod3.z.string()).optional()
+  })),
+  /** Total matching documents on this node (for pagination) */
+  totalHits: import_zod3.z.number().int().nonnegative(),
+  /** Execution time on this node in ms (for monitoring) */
+  executionTimeMs: import_zod3.z.number().nonnegative(),
+  /** Error if search failed on this node */
+  error: import_zod3.z.string().optional()
+});
+var ClusterSearchRespMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SEARCH_RESP"),
+  payload: ClusterSearchRespPayloadSchema
+});
+var ClusterSearchSubscribePayloadSchema = import_zod3.z.object({
+  subscriptionId: import_zod3.z.string(),
+  mapName: import_zod3.z.string(),
+  query: import_zod3.z.string(),
+  options: SearchOptionsSchema.optional()
+});
+var ClusterSearchSubscribeMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SEARCH_SUBSCRIBE"),
+  payload: ClusterSearchSubscribePayloadSchema
+});
+var ClusterSearchUnsubscribePayloadSchema = import_zod3.z.object({
+  subscriptionId: import_zod3.z.string()
+});
+var ClusterSearchUnsubscribeMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SEARCH_UNSUBSCRIBE"),
+  payload: ClusterSearchUnsubscribePayloadSchema
+});
+var ClusterSearchUpdatePayloadSchema = import_zod3.z.object({
+  subscriptionId: import_zod3.z.string(),
+  nodeId: import_zod3.z.string(),
+  key: import_zod3.z.string(),
+  value: import_zod3.z.unknown(),
+  score: import_zod3.z.number(),
+  matchedTerms: import_zod3.z.array(import_zod3.z.string()).optional(),
+  type: SearchUpdateTypeSchema
+});
+var ClusterSearchUpdateMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("CLUSTER_SEARCH_UPDATE"),
+  payload: ClusterSearchUpdatePayloadSchema
+});
 
 // src/types/WriteConcern.ts
 var WriteConcern = /* @__PURE__ */ ((WriteConcern2) => {
@@ -6228,7 +6454,7 @@ var QueryOptimizer = class {
    */
   optimizeWithOptions(query, options) {
     const basePlan = this.optimize(query);
-    if (!options.sort && options.limit === void 0 && options.offset === void 0) {
+    if (!options.sort && options.limit === void 0 && options.cursor === void 0) {
       return basePlan;
     }
     let indexedSort = false;
@@ -6250,7 +6476,8 @@ var QueryOptimizer = class {
       indexedSort,
       sort: sortField && sortDirection ? { field: sortField, direction: sortDirection } : void 0,
       limit: options.limit,
-      offset: options.offset
+      cursor: options.cursor
+      // Phase 14.1: replaces offset
     };
   }
   /**
@@ -8370,6 +8597,264 @@ var ReciprocalRankFusion = class {
   }
 };
 
+// src/utils/base64url.ts
+function encodeBase64Url(str) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(str, "utf8").toString("base64url");
+  }
+  const base64 = btoa(unescape(encodeURIComponent(str)));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeBase64Url(encoded) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(encoded, "base64url").toString("utf8");
+  }
+  let base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = base64.length % 4;
+  if (pad) {
+    base64 += "=".repeat(4 - pad);
+  }
+  return decodeURIComponent(escape(atob(base64)));
+}
+
+// src/utils/compare.ts
+function compareValues(a, b) {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    const dateA = Date.parse(a);
+    const dateB = Date.parse(b);
+    if (!isNaN(dateA) && !isNaN(dateB)) {
+      return dateA - dateB;
+    }
+    return a.localeCompare(b);
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return a === b ? 0 : a ? 1 : -1;
+  }
+  return String(a).localeCompare(String(b));
+}
+
+// src/query/QueryCursor.ts
+var DEFAULT_QUERY_CURSOR_MAX_AGE_MS = 10 * 60 * 1e3;
+var QueryCursor = class {
+  /**
+   * Encode cursor data to an opaque base64url string.
+   *
+   * @param data - Cursor data to encode
+   * @returns Opaque cursor string
+   */
+  static encode(data) {
+    const json = JSON.stringify(data);
+    return encodeBase64Url(json);
+  }
+  /**
+   * Decode cursor string back to data.
+   *
+   * @param cursor - Opaque cursor string
+   * @returns Decoded cursor data, or null if invalid
+   */
+  static decode(cursor) {
+    try {
+      const json = decodeBase64Url(cursor);
+      const data = JSON.parse(json);
+      if (typeof data !== "object" || typeof data.nodeValues !== "object" || typeof data.nodeKeys !== "object" || typeof data.sortField !== "string" || data.sortDirection !== "asc" && data.sortDirection !== "desc" || typeof data.predicateHash !== "number" || typeof data.sortHash !== "number" || typeof data.timestamp !== "number") {
+        return null;
+      }
+      return data;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Create a cursor from query results.
+   *
+   * The cursor captures the last seen position for each node that contributed
+   * results, enabling efficient resumption in the next page request.
+   *
+   * @param results - Array of results with sort values and optional node tracking
+   * @param sort - Sort configuration (single field only for v1)
+   * @param predicate - Query predicate (for validation)
+   * @returns Encoded cursor string
+   */
+  static fromResults(results, sort, predicate) {
+    const nodeValues = {};
+    const nodeKeys = {};
+    const sortEntries = Object.entries(sort);
+    if (sortEntries.length === 0) {
+      throw new Error("Sort configuration required for cursor pagination");
+    }
+    const [sortField, sortDirection] = sortEntries[0];
+    for (const result of results) {
+      const nodeId = result.nodeId ?? "local";
+      nodeValues[nodeId] = result.sortValue;
+      nodeKeys[nodeId] = result.key;
+    }
+    const data = {
+      nodeValues,
+      nodeKeys,
+      sortField,
+      sortDirection,
+      predicateHash: hashObject(predicate ?? null),
+      sortHash: hashObject(sort),
+      timestamp: Date.now()
+    };
+    return this.encode(data);
+  }
+  /**
+   * Create a cursor from the last result only.
+   * Useful for local-only queries.
+   *
+   * @param lastResult - The last result in the current page
+   * @param sort - Sort configuration
+   * @param predicate - Query predicate
+   * @returns Encoded cursor string
+   */
+  static fromLastResult(lastResult, sort, predicate) {
+    return this.fromResults([lastResult], sort, predicate);
+  }
+  /**
+   * Validate that a cursor is valid for the given query.
+   *
+   * Checks:
+   * 1. Predicate hash matches (cursor was created for this query)
+   * 2. Sort hash matches (sort configuration unchanged)
+   * 3. Cursor is not expired
+   *
+   * @param cursor - Decoded cursor data
+   * @param predicate - Query predicate to validate against
+   * @param sort - Sort configuration to validate against
+   * @param options - Validation options
+   * @returns true if cursor is valid
+   */
+  static isValid(cursor, predicate, sort, options) {
+    const maxAge = options?.maxAgeMs ?? DEFAULT_QUERY_CURSOR_MAX_AGE_MS;
+    if (cursor.predicateHash !== hashObject(predicate ?? null)) {
+      return false;
+    }
+    if (cursor.sortHash !== hashObject(sort)) {
+      return false;
+    }
+    if (Date.now() - cursor.timestamp > maxAge) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Get the cursor position for a specific node.
+   *
+   * @param cursor - Decoded cursor data
+   * @param nodeId - Node ID to get position for (defaults to 'local')
+   * @returns Position info or null if node not in cursor
+   */
+  static getNodePosition(cursor, nodeId = "local") {
+    if (!(nodeId in cursor.nodeValues)) {
+      return null;
+    }
+    return {
+      afterValue: cursor.nodeValues[nodeId],
+      afterKey: cursor.nodeKeys[nodeId]
+    };
+  }
+  /**
+   * Check if a result should be included based on cursor position.
+   *
+   * For ASC sort: value > cursorValue OR (value === cursorValue AND key > cursorKey)
+   * For DESC sort: value < cursorValue OR (value === cursorValue AND key > cursorKey)
+   *
+   * @param result - Result to check
+   * @param cursor - Decoded cursor data
+   * @returns true if result should be included (is after cursor)
+   */
+  static isAfterCursor(result, cursor) {
+    const nodeId = result.nodeId ?? "local";
+    const position = this.getNodePosition(cursor, nodeId);
+    if (!position) {
+      return true;
+    }
+    const cmp = this.compareValues(result.sortValue, position.afterValue);
+    if (cursor.sortDirection === "asc") {
+      if (cmp > 0) return true;
+      if (cmp === 0 && result.key > position.afterKey) return true;
+    } else {
+      if (cmp < 0) return true;
+      if (cmp === 0 && result.key > position.afterKey) return true;
+    }
+    return false;
+  }
+  /**
+   * Compare two values with type-aware comparison.
+   * Delegates to shared compareValues utility.
+   *
+   * @param a - First value
+   * @param b - Second value
+   * @returns Negative if a < b, 0 if equal, positive if a > b
+   */
+  static compareValues(a, b) {
+    return compareValues(a, b);
+  }
+  /**
+   * Merge multiple cursors into one.
+   * Useful when combining results from multiple sub-queries or nodes.
+   *
+   * Keeps the furthest position for each node.
+   *
+   * @param cursors - Array of decoded cursor data
+   * @param sort - Sort configuration
+   * @param predicate - Query predicate
+   * @returns New merged cursor
+   */
+  static merge(cursors, sort, predicate) {
+    const nodeValues = {};
+    const nodeKeys = {};
+    const sortEntries = Object.entries(sort);
+    const [sortField, sortDirection] = sortEntries[0];
+    for (const cursor of cursors) {
+      for (const nodeId of Object.keys(cursor.nodeValues)) {
+        const existingValue = nodeValues[nodeId];
+        const newValue = cursor.nodeValues[nodeId];
+        if (existingValue === void 0) {
+          nodeValues[nodeId] = newValue;
+          nodeKeys[nodeId] = cursor.nodeKeys[nodeId];
+        } else {
+          const cmp = this.compareValues(newValue, existingValue);
+          const isFurther = sortDirection === "asc" ? cmp > 0 || cmp === 0 && cursor.nodeKeys[nodeId] > nodeKeys[nodeId] : cmp < 0 || cmp === 0 && cursor.nodeKeys[nodeId] > nodeKeys[nodeId];
+          if (isFurther) {
+            nodeValues[nodeId] = newValue;
+            nodeKeys[nodeId] = cursor.nodeKeys[nodeId];
+          }
+        }
+      }
+    }
+    return {
+      nodeValues,
+      nodeKeys,
+      sortField,
+      sortDirection,
+      predicateHash: hashObject(predicate ?? null),
+      sortHash: hashObject(sort),
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Extract sort value from a record for cursor generation.
+   *
+   * @param record - Record to extract sort value from
+   * @param sortField - Field to extract
+   * @returns Sort value
+   */
+  static extractSortValue(record, sortField) {
+    return record[sortField];
+  }
+};
+
 // src/IndexedLWWMap.ts
 var IndexedLWWMap = class extends LWWMap {
   constructor(hlc, options = {}) {
@@ -10945,6 +11430,179 @@ var IndexedORMap = class extends ORMap {
     return null;
   }
 };
+
+// src/search/SearchCursor.ts
+var DEFAULT_CURSOR_MAX_AGE_MS = 5 * 60 * 1e3;
+var SearchCursor = class {
+  /**
+   * Encode cursor data to an opaque base64url string.
+   *
+   * @param data - Cursor data to encode
+   * @returns Opaque cursor string
+   */
+  static encode(data) {
+    const json = JSON.stringify(data);
+    return encodeBase64Url(json);
+  }
+  /**
+   * Decode cursor string back to data.
+   *
+   * @param cursor - Opaque cursor string
+   * @returns Decoded cursor data, or null if invalid
+   */
+  static decode(cursor) {
+    try {
+      const json = decodeBase64Url(cursor);
+      const data = JSON.parse(json);
+      if (typeof data !== "object" || typeof data.nodeScores !== "object" || typeof data.nodeKeys !== "object" || typeof data.queryHash !== "number" || typeof data.timestamp !== "number") {
+        return null;
+      }
+      return data;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Create a cursor from the last results of a search.
+   *
+   * The cursor captures the last seen position for each node that contributed
+   * results, enabling efficient resumption in the next page request.
+   *
+   * @param results - Array of results with node tracking
+   * @param query - Original query string (for validation)
+   * @returns Encoded cursor string
+   */
+  static fromResults(results, query) {
+    const nodeScores = {};
+    const nodeKeys = {};
+    for (const result of results) {
+      nodeScores[result.nodeId] = result.score;
+      nodeKeys[result.nodeId] = result.key;
+    }
+    const data = {
+      nodeScores,
+      nodeKeys,
+      queryHash: hashString(query),
+      timestamp: Date.now()
+    };
+    return this.encode(data);
+  }
+  /**
+   * Create a cursor from the last result only.
+   * Useful when you only have the final merged result.
+   *
+   * @param lastResult - The last result in the current page
+   * @param query - Original query string
+   * @returns Encoded cursor string
+   */
+  static fromLastResult(lastResult, query) {
+    return this.fromResults([lastResult], query);
+  }
+  /**
+   * Generate a hash for a query string.
+   * Used to validate that cursor matches the current query.
+   *
+   * @param query - Query string to hash
+   * @returns Numeric hash
+   */
+  static hashQuery(query) {
+    return hashString(query);
+  }
+  /**
+   * Validate that a cursor is valid for the given query.
+   *
+   * Checks:
+   * 1. Query hash matches (cursor was created for this query)
+   * 2. Cursor is not expired
+   *
+   * @param cursor - Decoded cursor data
+   * @param query - Query string to validate against
+   * @param maxAgeMs - Maximum cursor age in milliseconds (default: 5 minutes)
+   * @returns true if cursor is valid
+   */
+  static isValid(cursor, query, maxAgeMs = DEFAULT_CURSOR_MAX_AGE_MS) {
+    if (cursor.queryHash !== hashString(query)) {
+      return false;
+    }
+    if (Date.now() - cursor.timestamp > maxAgeMs) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Get the cursor position for a specific node.
+   *
+   * @param cursor - Decoded cursor data
+   * @param nodeId - Node ID to get position for
+   * @returns Position info or null if node not in cursor
+   */
+  static getNodePosition(cursor, nodeId) {
+    if (!(nodeId in cursor.nodeScores)) {
+      return null;
+    }
+    return {
+      afterScore: cursor.nodeScores[nodeId],
+      afterKey: cursor.nodeKeys[nodeId]
+    };
+  }
+  /**
+   * Check if a result should be included based on cursor position.
+   *
+   * Results are ordered by score descending, then key ascending for tie-breaking.
+   * A result should be included if it comes AFTER the cursor position:
+   * - score < cursorScore, OR
+   * - score === cursorScore AND key > cursorKey
+   *
+   * @param result - Result to check
+   * @param cursor - Decoded cursor data
+   * @returns true if result should be included (is after cursor)
+   */
+  static isAfterCursor(result, cursor) {
+    const position = this.getNodePosition(cursor, result.nodeId);
+    if (!position) {
+      return true;
+    }
+    if (result.score < position.afterScore) {
+      return true;
+    }
+    if (result.score === position.afterScore && result.key > position.afterKey) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Merge multiple cursors into one.
+   * Useful when combining results from multiple sub-queries.
+   *
+   * @param cursors - Array of decoded cursor data
+   * @param query - Original query string
+   * @returns New merged cursor
+   */
+  static merge(cursors, query) {
+    const nodeScores = {};
+    const nodeKeys = {};
+    for (const cursor of cursors) {
+      for (const nodeId of Object.keys(cursor.nodeScores)) {
+        const existingScore = nodeScores[nodeId];
+        const newScore = cursor.nodeScores[nodeId];
+        if (existingScore === void 0 || newScore < existingScore) {
+          nodeScores[nodeId] = newScore;
+          nodeKeys[nodeId] = cursor.nodeKeys[nodeId];
+        } else if (newScore === existingScore) {
+          if (cursor.nodeKeys[nodeId] > nodeKeys[nodeId]) {
+            nodeKeys[nodeId] = cursor.nodeKeys[nodeId];
+          }
+        }
+      }
+    }
+    return {
+      nodeScores,
+      nodeKeys,
+      queryHash: hashString(query),
+      timestamp: Date.now()
+    };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthMessageSchema,
@@ -10954,6 +11612,24 @@ var IndexedORMap = class extends ORMap {
   BuiltInResolvers,
   ClientOpMessageSchema,
   ClientOpSchema,
+  ClusterSearchReqMessageSchema,
+  ClusterSearchReqPayloadSchema,
+  ClusterSearchRespMessageSchema,
+  ClusterSearchRespPayloadSchema,
+  ClusterSearchSubscribeMessageSchema,
+  ClusterSearchSubscribePayloadSchema,
+  ClusterSearchUnsubscribeMessageSchema,
+  ClusterSearchUnsubscribePayloadSchema,
+  ClusterSearchUpdateMessageSchema,
+  ClusterSearchUpdatePayloadSchema,
+  ClusterSubAckMessageSchema,
+  ClusterSubAckPayloadSchema,
+  ClusterSubRegisterMessageSchema,
+  ClusterSubRegisterPayloadSchema,
+  ClusterSubUnregisterMessageSchema,
+  ClusterSubUnregisterPayloadSchema,
+  ClusterSubUpdateMessageSchema,
+  ClusterSubUpdatePayloadSchema,
   ConflictResolverDefSchema,
   ConflictResolverSchema,
   ConsistencyLevel,
@@ -10961,13 +11637,16 @@ var IndexedORMap = class extends ORMap {
   CounterResponseSchema,
   CounterSyncSchema,
   CounterUpdateSchema,
+  CursorStatusSchema,
   DEFAULT_BACKUP_COUNT,
   DEFAULT_CIRCUIT_BREAKER_CONFIG,
   DEFAULT_CONNECTION_POOL_CONFIG,
+  DEFAULT_CURSOR_MAX_AGE_MS,
   DEFAULT_EVENT_JOURNAL_CONFIG,
   DEFAULT_MIGRATION_CONFIG,
   DEFAULT_PARTITION_ROUTER_CONFIG,
   DEFAULT_PROCESSOR_RATE_LIMITS,
+  DEFAULT_QUERY_CURSOR_MAX_AGE_MS,
   DEFAULT_REPLICATION_CONFIG,
   DEFAULT_RESOLVER_RATE_LIMITS,
   DEFAULT_STOP_WORDS,
@@ -11045,7 +11724,10 @@ var IndexedORMap = class extends ORMap {
   PredicateNodeSchema,
   PredicateOpSchema,
   Predicates,
+  QueryCursor,
   QueryOptimizer,
+  QueryRespMessageSchema,
+  QueryRespPayloadSchema,
   QuerySchema,
   QuerySubMessageSchema,
   QueryUnsubMessageSchema,
@@ -11054,6 +11736,7 @@ var IndexedORMap = class extends ORMap {
   RegisterResolverRequestSchema,
   RegisterResolverResponseSchema,
   Ringbuffer,
+  SearchCursor,
   SearchMessageSchema,
   SearchOptionsSchema,
   SearchPayloadSchema,
@@ -11096,15 +11779,19 @@ var IndexedORMap = class extends ORMap {
   combineHashes,
   compareHLCTimestamps,
   compareTimestamps,
+  compareValues,
   createFieldComparator,
   createPredicateMatcher,
+  decodeBase64Url,
   deepMerge,
   deserialize,
   disableNativeHash,
+  encodeBase64Url,
   evaluatePredicate,
   getHighestWriteConcernLevel,
   hashORMapEntry,
   hashORMapRecord,
+  hashObject,
   hashString,
   isLogicalQuery,
   isSimpleQuery,