@topgunbuild/core 0.6.0 → 0.8.0

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthMessageSchema: () => AuthMessageSchema,
+  BM25Scorer: () => BM25Scorer,
   BatchMessageSchema: () => BatchMessageSchema,
   BuiltInProcessors: () => BuiltInProcessors,
   BuiltInResolvers: () => BuiltInResolvers,
@@ -54,6 +55,7 @@ __export(index_exports, {
   DEFAULT_RESOLVER_RATE_LIMITS: () => DEFAULT_RESOLVER_RATE_LIMITS,
   DEFAULT_STOP_WORDS: () => DEFAULT_STOP_WORDS,
   DEFAULT_WRITE_CONCERN_TIMEOUT: () => DEFAULT_WRITE_CONCERN_TIMEOUT,
+  ENGLISH_STOPWORDS: () => ENGLISH_STOPWORDS,
   EntryProcessBatchRequestSchema: () => EntryProcessBatchRequestSchema,
   EntryProcessBatchResponseSchema: () => EntryProcessBatchResponseSchema,
   EntryProcessKeyResultSchema: () => EntryProcessKeyResultSchema,
@@ -63,8 +65,11 @@ __export(index_exports, {
   EntryProcessorSchema: () => EntryProcessorSchema,
   EventJournalImpl: () => EventJournalImpl,
   FORBIDDEN_PATTERNS: () => FORBIDDEN_PATTERNS,
+  FTSInvertedIndex: () => BM25InvertedIndex,
+  FTSTokenizer: () => BM25Tokenizer,
   FallbackIndex: () => FallbackIndex,
   FilteringResultSet: () => FilteringResultSet,
+  FullTextIndex: () => FullTextIndex,
   HLC: () => HLC,
   HashIndex: () => HashIndex,
   IndexRegistry: () => IndexRegistry,
@@ -131,6 +136,18 @@ __export(index_exports, {
   RegisterResolverRequestSchema: () => RegisterResolverRequestSchema,
   RegisterResolverResponseSchema: () => RegisterResolverResponseSchema,
   Ringbuffer: () => Ringbuffer,
+  SearchMessageSchema: () => SearchMessageSchema,
+  SearchOptionsSchema: () => SearchOptionsSchema,
+  SearchPayloadSchema: () => SearchPayloadSchema,
+  SearchRespMessageSchema: () => SearchRespMessageSchema,
+  SearchRespPayloadSchema: () => SearchRespPayloadSchema,
+  SearchSubMessageSchema: () => SearchSubMessageSchema,
+  SearchSubPayloadSchema: () => SearchSubPayloadSchema,
+  SearchUnsubMessageSchema: () => SearchUnsubMessageSchema,
+  SearchUnsubPayloadSchema: () => SearchUnsubPayloadSchema,
+  SearchUpdateMessageSchema: () => SearchUpdateMessageSchema,
+  SearchUpdatePayloadSchema: () => SearchUpdatePayloadSchema,
+  SearchUpdateTypeSchema: () => SearchUpdateTypeSchema,
   SetResultSet: () => SetResultSet,
   SimpleAttribute: () => SimpleAttribute,
   SortedMap: () => SortedMap,
@@ -176,6 +193,7 @@ __export(index_exports, {
   isUsingNativeHash: () => isUsingNativeHash,
   isWriteConcernAchieved: () => isWriteConcernAchieved,
   multiAttribute: () => multiAttribute,
+  porterStem: () => porterStem,
   resetNativeHash: () => resetNativeHash,
   serialize: () => serialize,
   simpleAttribute: () => simpleAttribute,
@@ -2596,6 +2614,66 @@ var JournalReadResponseSchema = import_zod3.z.object({
   events: import_zod3.z.array(JournalEventDataSchema),
   hasMore: import_zod3.z.boolean()
 });
+var SearchOptionsSchema = import_zod3.z.object({
+  limit: import_zod3.z.number().optional(),
+  minScore: import_zod3.z.number().optional(),
+  boost: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.number()).optional()
+});
+var SearchPayloadSchema = import_zod3.z.object({
+  requestId: import_zod3.z.string(),
+  mapName: import_zod3.z.string(),
+  query: import_zod3.z.string(),
+  options: SearchOptionsSchema.optional()
+});
+var SearchMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("SEARCH"),
+  payload: SearchPayloadSchema
+});
+var SearchRespPayloadSchema = import_zod3.z.object({
+  requestId: import_zod3.z.string(),
+  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())
+  })),
+  totalCount: import_zod3.z.number(),
+  error: import_zod3.z.string().optional()
+});
+var SearchRespMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("SEARCH_RESP"),
+  payload: SearchRespPayloadSchema
+});
+var SearchUpdateTypeSchema = import_zod3.z.enum(["ENTER", "UPDATE", "LEAVE"]);
+var SearchSubPayloadSchema = import_zod3.z.object({
+  subscriptionId: import_zod3.z.string(),
+  mapName: import_zod3.z.string(),
+  query: import_zod3.z.string(),
+  options: SearchOptionsSchema.optional()
+});
+var SearchSubMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("SEARCH_SUB"),
+  payload: SearchSubPayloadSchema
+});
+var SearchUpdatePayloadSchema = import_zod3.z.object({
+  subscriptionId: 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()),
+  type: SearchUpdateTypeSchema
+});
+var SearchUpdateMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("SEARCH_UPDATE"),
+  payload: SearchUpdatePayloadSchema
+});
+var SearchUnsubPayloadSchema = import_zod3.z.object({
+  subscriptionId: import_zod3.z.string()
+});
+var SearchUnsubMessageSchema = import_zod3.z.object({
+  type: import_zod3.z.literal("SEARCH_UNSUB"),
+  payload: SearchUnsubPayloadSchema
+});
 var ConflictResolverSchema = import_zod3.z.object({
   name: import_zod3.z.string().min(1).max(100),
   code: import_zod3.z.string().max(5e4),
@@ -2727,7 +2805,14 @@ var MessageSchema = import_zod3.z.discriminatedUnion("type", [
   UnregisterResolverResponseSchema,
   MergeRejectedMessageSchema,
   ListResolversRequestSchema,
-  ListResolversResponseSchema
+  ListResolversResponseSchema,
+  // Phase 11.1: Full-Text Search
+  SearchMessageSchema,
+  SearchRespMessageSchema,
+  // Phase 11.1b: Live Search Subscriptions
+  SearchSubMessageSchema,
+  SearchUpdateMessageSchema,
+  SearchUnsubMessageSchema
 ]);
 
 // src/types/WriteConcern.ts
@@ -8629,10 +8714,1076 @@ var IndexedLWWMap = class extends LWWMap {
   }
 };
 
+// src/query/tokenization/stopwords.ts
+var ENGLISH_STOPWORDS = /* @__PURE__ */ new Set([
+  // Articles
+  "a",
+  "an",
+  "the",
+  // Pronouns
+  "i",
+  "me",
+  "my",
+  "myself",
+  "we",
+  "our",
+  "ours",
+  "ourselves",
+  "you",
+  "your",
+  "yours",
+  "yourself",
+  "yourselves",
+  "he",
+  "him",
+  "his",
+  "himself",
+  "she",
+  "her",
+  "hers",
+  "herself",
+  "it",
+  "its",
+  "itself",
+  "they",
+  "them",
+  "their",
+  "theirs",
+  "themselves",
+  "what",
+  "which",
+  "who",
+  "whom",
+  "this",
+  "that",
+  "these",
+  "those",
+  // Auxiliary verbs
+  "am",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "having",
+  "do",
+  "does",
+  "did",
+  "doing",
+  "will",
+  "would",
+  "shall",
+  "should",
+  "can",
+  "could",
+  "may",
+  "might",
+  "must",
+  "ought",
+  // Prepositions
+  "about",
+  "above",
+  "across",
+  "after",
+  "against",
+  "along",
+  "among",
+  "around",
+  "at",
+  "before",
+  "behind",
+  "below",
+  "beneath",
+  "beside",
+  "between",
+  "beyond",
+  "by",
+  "down",
+  "during",
+  "except",
+  "for",
+  "from",
+  "in",
+  "inside",
+  "into",
+  "near",
+  "of",
+  "off",
+  "on",
+  "onto",
+  "out",
+  "outside",
+  "over",
+  "past",
+  "since",
+  "through",
+  "throughout",
+  "to",
+  "toward",
+  "towards",
+  "under",
+  "underneath",
+  "until",
+  "up",
+  "upon",
+  "with",
+  "within",
+  "without",
+  // Conjunctions
+  "and",
+  "but",
+  "or",
+  "nor",
+  "so",
+  "yet",
+  "both",
+  "either",
+  "neither",
+  "not",
+  "only",
+  "as",
+  "if",
+  "than",
+  "when",
+  "while",
+  "although",
+  "because",
+  "unless",
+  "whether",
+  // Adverbs
+  "here",
+  "there",
+  "where",
+  "when",
+  "how",
+  "why",
+  "all",
+  "each",
+  "every",
+  "any",
+  "some",
+  "no",
+  "none",
+  "more",
+  "most",
+  "other",
+  "such",
+  "own",
+  "same",
+  "too",
+  "very",
+  "just",
+  "also",
+  "now",
+  "then",
+  "again",
+  "ever",
+  "once",
+  // Misc
+  "few",
+  "many",
+  "much",
+  "several",
+  "s",
+  "t",
+  "d",
+  "ll",
+  "m",
+  "ve",
+  "re"
+]);
+
+// src/query/tokenization/porter-stemmer.ts
+function porterStem(word) {
+  if (!word || word.length < 3) {
+    return word;
+  }
+  let stem = word;
+  if (stem.endsWith("sses")) {
+    stem = stem.slice(0, -2);
+  } else if (stem.endsWith("ies")) {
+    stem = stem.slice(0, -2);
+  } else if (!stem.endsWith("ss") && stem.endsWith("s")) {
+    stem = stem.slice(0, -1);
+  }
+  const step1bRegex = /^(.+?)(eed|ed|ing)$/;
+  const step1bMatch = stem.match(step1bRegex);
+  if (step1bMatch) {
+    const [, base, suffix] = step1bMatch;
+    if (suffix === "eed") {
+      if (getMeasure(base) > 0) {
+        stem = base + "ee";
+      }
+    } else if (hasVowel(base)) {
+      stem = base;
+      if (stem.endsWith("at") || stem.endsWith("bl") || stem.endsWith("iz")) {
+        stem = stem + "e";
+      } else if (endsWithDoubleConsonant(stem) && !stem.match(/[lsz]$/)) {
+        stem = stem.slice(0, -1);
+      } else if (getMeasure(stem) === 1 && endsWithCVC(stem)) {
+        stem = stem + "e";
+      }
+    }
+  }
+  if (stem.endsWith("y") && hasVowel(stem.slice(0, -1))) {
+    stem = stem.slice(0, -1) + "i";
+  }
+  const step2Suffixes = [
+    [/ational$/, "ate", 0],
+    [/tional$/, "tion", 0],
+    [/enci$/, "ence", 0],
+    [/anci$/, "ance", 0],
+    [/izer$/, "ize", 0],
+    [/abli$/, "able", 0],
+    [/alli$/, "al", 0],
+    [/entli$/, "ent", 0],
+    [/eli$/, "e", 0],
+    [/ousli$/, "ous", 0],
+    [/ization$/, "ize", 0],
+    [/ation$/, "ate", 0],
+    [/ator$/, "ate", 0],
+    [/alism$/, "al", 0],
+    [/iveness$/, "ive", 0],
+    [/fulness$/, "ful", 0],
+    [/ousness$/, "ous", 0],
+    [/aliti$/, "al", 0],
+    [/iviti$/, "ive", 0],
+    [/biliti$/, "ble", 0]
+  ];
+  for (const [regex, replacement, minMeasure] of step2Suffixes) {
+    if (regex.test(stem)) {
+      const base = stem.replace(regex, "");
+      if (getMeasure(base) > minMeasure) {
+        stem = base + replacement;
+        break;
+      }
+    }
+  }
+  const step3Suffixes = [
+    [/icate$/, "ic", 0],
+    [/ative$/, "", 0],
+    [/alize$/, "al", 0],
+    [/iciti$/, "ic", 0],
+    [/ical$/, "ic", 0],
+    [/ful$/, "", 0],
+    [/ness$/, "", 0]
+  ];
+  for (const [regex, replacement, minMeasure] of step3Suffixes) {
+    if (regex.test(stem)) {
+      const base = stem.replace(regex, "");
+      if (getMeasure(base) > minMeasure) {
+        stem = base + replacement;
+        break;
+      }
+    }
+  }
+  const step4Suffixes = [
+    [/al$/, 1],
+    [/ance$/, 1],
+    [/ence$/, 1],
+    [/er$/, 1],
+    [/ic$/, 1],
+    [/able$/, 1],
+    [/ible$/, 1],
+    [/ant$/, 1],
+    [/ement$/, 1],
+    [/ment$/, 1],
+    [/ent$/, 1],
+    [/ion$/, 1],
+    [/ou$/, 1],
+    [/ism$/, 1],
+    [/ate$/, 1],
+    [/iti$/, 1],
+    [/ous$/, 1],
+    [/ive$/, 1],
+    [/ize$/, 1]
+  ];
+  for (const [regex, minMeasure] of step4Suffixes) {
+    if (regex.test(stem)) {
+      const base = stem.replace(regex, "");
+      if (getMeasure(base) > minMeasure) {
+        if (regex.source === "ion$") {
+          if (base.match(/[st]$/)) {
+            stem = base;
+          }
+        } else {
+          stem = base;
+        }
+        break;
+      }
+    }
+  }
+  if (stem.endsWith("e")) {
+    const base = stem.slice(0, -1);
+    const measure = getMeasure(base);
+    if (measure > 1 || measure === 1 && !endsWithCVC(base)) {
+      stem = base;
+    }
+  }
+  if (getMeasure(stem) > 1 && endsWithDoubleConsonant(stem) && stem.endsWith("l")) {
+    stem = stem.slice(0, -1);
+  }
+  return stem;
+}
+function isVowel(char, prevChar) {
+  if ("aeiou".includes(char)) {
+    return true;
+  }
+  if (char === "y" && prevChar && !"aeiou".includes(prevChar)) {
+    return true;
+  }
+  return false;
+}
+function hasVowel(str) {
+  for (let i = 0; i < str.length; i++) {
+    if (isVowel(str[i], i > 0 ? str[i - 1] : void 0)) {
+      return true;
+    }
+  }
+  return false;
+}
+function getMeasure(str) {
+  let pattern = "";
+  for (let i = 0; i < str.length; i++) {
+    pattern += isVowel(str[i], i > 0 ? str[i - 1] : void 0) ? "v" : "c";
+  }
+  const matches = pattern.match(/vc/g);
+  return matches ? matches.length : 0;
+}
+function endsWithDoubleConsonant(str) {
+  if (str.length < 2) return false;
+  const last = str[str.length - 1];
+  const secondLast = str[str.length - 2];
+  return last === secondLast && !"aeiou".includes(last);
+}
+function endsWithCVC(str) {
+  if (str.length < 3) return false;
+  const last3 = str.slice(-3);
+  const c1 = !"aeiou".includes(last3[0]);
+  const v = isVowel(last3[1], last3[0]);
+  const c2 = !"aeiou".includes(last3[2]) && !"wxy".includes(last3[2]);
+  return c1 && v && c2;
+}
+
+// src/fts/Tokenizer.ts
+var BM25Tokenizer = class {
+  /**
+   * Create a new BM25Tokenizer.
+   *
+   * @param options - Configuration options
+   */
+  constructor(options) {
+    this.options = {
+      lowercase: true,
+      stopwords: ENGLISH_STOPWORDS,
+      stemmer: porterStem,
+      minLength: 2,
+      maxLength: 40,
+      ...options
+    };
+  }
+  /**
+   * Tokenize text into an array of normalized tokens.
+   *
+   * @param text - Text to tokenize
+   * @returns Array of tokens
+   */
+  tokenize(text) {
+    if (!text || typeof text !== "string") {
+      return [];
+    }
+    let processed = this.options.lowercase ? text.toLowerCase() : text;
+    const words = processed.split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 0);
+    const tokens = [];
+    for (const word of words) {
+      if (word.length < this.options.minLength) {
+        continue;
+      }
+      if (this.options.stopwords.has(word)) {
+        continue;
+      }
+      const stemmed = this.options.stemmer(word);
+      if (stemmed.length < this.options.minLength) {
+        continue;
+      }
+      if (stemmed.length > this.options.maxLength) {
+        continue;
+      }
+      tokens.push(stemmed);
+    }
+    return tokens;
+  }
+};
+
+// src/fts/BM25InvertedIndex.ts
+var BM25InvertedIndex = class {
+  constructor() {
+    this.index = /* @__PURE__ */ new Map();
+    this.docLengths = /* @__PURE__ */ new Map();
+    this.docTerms = /* @__PURE__ */ new Map();
+    this.idfCache = /* @__PURE__ */ new Map();
+    this.totalDocs = 0;
+    this.avgDocLength = 0;
+  }
+  /**
+   * Add a document to the index.
+   *
+   * @param docId - Unique document identifier
+   * @param tokens - Array of tokens (already tokenized/stemmed)
+   */
+  addDocument(docId, tokens) {
+    const termFreqs = /* @__PURE__ */ new Map();
+    const uniqueTerms = /* @__PURE__ */ new Set();
+    for (const token of tokens) {
+      termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
+      uniqueTerms.add(token);
+    }
+    for (const [term, freq] of termFreqs) {
+      if (!this.index.has(term)) {
+        this.index.set(term, []);
+      }
+      this.index.get(term).push({
+        docId,
+        termFrequency: freq
+      });
+    }
+    this.docLengths.set(docId, tokens.length);
+    this.docTerms.set(docId, uniqueTerms);
+    this.totalDocs++;
+    this.updateAvgDocLength();
+    this.idfCache.clear();
+  }
+  /**
+   * Remove a document from the index.
+   *
+   * @param docId - Document identifier to remove
+   */
+  removeDocument(docId) {
+    const terms = this.docTerms.get(docId);
+    if (!terms) {
+      return;
+    }
+    for (const term of terms) {
+      const termInfos = this.index.get(term);
+      if (termInfos) {
+        const filtered = termInfos.filter((info) => info.docId !== docId);
+        if (filtered.length === 0) {
+          this.index.delete(term);
+        } else {
+          this.index.set(term, filtered);
+        }
+      }
+    }
+    this.docLengths.delete(docId);
+    this.docTerms.delete(docId);
+    this.totalDocs--;
+    this.updateAvgDocLength();
+    this.idfCache.clear();
+  }
+  /**
+   * Get all documents containing a term.
+   *
+   * @param term - Term to look up
+   * @returns Array of TermInfo objects
+   */
+  getDocumentsForTerm(term) {
+    return this.index.get(term) || [];
+  }
+  /**
+   * Calculate IDF (Inverse Document Frequency) for a term.
+   *
+   * Uses BM25 IDF formula:
+   * IDF = log((N - df + 0.5) / (df + 0.5) + 1)
+   *
+   * Where:
+   * - N = total documents
+   * - df = document frequency (docs containing term)
+   *
+   * @param term - Term to calculate IDF for
+   * @returns IDF value (0 if term doesn't exist)
+   */
+  getIDF(term) {
+    if (this.idfCache.has(term)) {
+      return this.idfCache.get(term);
+    }
+    const termInfos = this.index.get(term);
+    if (!termInfos || termInfos.length === 0) {
+      return 0;
+    }
+    const docFreq = termInfos.length;
+    const idf = Math.log((this.totalDocs - docFreq + 0.5) / (docFreq + 0.5) + 1);
+    this.idfCache.set(term, idf);
+    return idf;
+  }
+  /**
+   * Get the length of a document (number of tokens).
+   *
+   * @param docId - Document identifier
+   * @returns Document length (0 if not found)
+   */
+  getDocLength(docId) {
+    return this.docLengths.get(docId) || 0;
+  }
+  /**
+   * Get the average document length.
+   *
+   * @returns Average length across all documents
+   */
+  getAvgDocLength() {
+    return this.avgDocLength;
+  }
+  /**
+   * Get the total number of documents in the index.
+   *
+   * @returns Total document count
+   */
+  getTotalDocs() {
+    return this.totalDocs;
+  }
+  /**
+   * Get iterator for document lengths (useful for serialization).
+   *
+   * @returns Iterator of [docId, length] pairs
+   */
+  getDocLengths() {
+    return this.docLengths.entries();
+  }
+  /**
+   * Get the number of documents in the index (alias for getTotalDocs).
+   *
+   * @returns Number of indexed documents
+   */
+  getSize() {
+    return this.totalDocs;
+  }
+  /**
+   * Clear all data from the index.
+   */
+  clear() {
+    this.index.clear();
+    this.docLengths.clear();
+    this.docTerms.clear();
+    this.idfCache.clear();
+    this.totalDocs = 0;
+    this.avgDocLength = 0;
+  }
+  /**
+   * Check if a document exists in the index.
+   *
+   * @param docId - Document identifier
+   * @returns True if document exists
+   */
+  hasDocument(docId) {
+    return this.docTerms.has(docId);
+  }
+  /**
+   * Get all unique terms in the index.
+   *
+   * @returns Iterator of all terms
+   */
+  getTerms() {
+    return this.index.keys();
+  }
+  /**
+   * Get the number of unique terms in the index.
+   *
+   * @returns Number of unique terms
+   */
+  getTermCount() {
+    return this.index.size;
+  }
+  /**
+   * Update the average document length after add/remove.
+   */
+  updateAvgDocLength() {
+    if (this.totalDocs === 0) {
+      this.avgDocLength = 0;
+      return;
+    }
+    let sum = 0;
+    for (const length of this.docLengths.values()) {
+      sum += length;
+    }
+    this.avgDocLength = sum / this.totalDocs;
+  }
+};
+
+// src/fts/BM25Scorer.ts
+var BM25Scorer = class {
+  /**
+   * Create a new BM25 scorer.
+   *
+   * @param options - BM25 configuration options
+   */
+  constructor(options) {
+    this.k1 = options?.k1 ?? 1.2;
+    this.b = options?.b ?? 0.75;
+  }
+  /**
+   * Score documents against a query.
+   *
+   * @param queryTerms - Array of query terms (already tokenized/stemmed)
+   * @param index - The inverted index to search
+   * @returns Array of scored documents, sorted by relevance (descending)
+   */
+  score(queryTerms, index) {
+    if (queryTerms.length === 0 || index.getTotalDocs() === 0) {
+      return [];
+    }
+    const avgDocLength = index.getAvgDocLength();
+    const docScores = /* @__PURE__ */ new Map();
+    for (const term of queryTerms) {
+      const idf = index.getIDF(term);
+      if (idf === 0) {
+        continue;
+      }
+      const termInfos = index.getDocumentsForTerm(term);
+      for (const { docId, termFrequency } of termInfos) {
+        const docLength = index.getDocLength(docId);
+        const numerator = termFrequency * (this.k1 + 1);
+        const denominator = termFrequency + this.k1 * (1 - this.b + this.b * (docLength / avgDocLength));
+        const termScore = idf * (numerator / denominator);
+        const current = docScores.get(docId) || { score: 0, terms: /* @__PURE__ */ new Set() };
+        current.score += termScore;
+        current.terms.add(term);
+        docScores.set(docId, current);
+      }
+    }
+    const results = [];
+    for (const [docId, { score, terms }] of docScores) {
+      results.push({
+        docId,
+        score,
+        matchedTerms: Array.from(terms)
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+  /**
+   * Score a single document against query terms.
+   * Uses pre-computed IDF from index but calculates TF locally.
+   *
+   * Complexity: O(Q × D) where Q = query terms, D = document tokens
+   *
+   * @param queryTerms - Tokenized query terms
+   * @param docTokens - Tokenized document terms
+   * @param index - Inverted index for IDF and avgDocLength
+   * @returns BM25 score (0 if no matching terms)
+   */
+  scoreSingleDocument(queryTerms, docTokens, index) {
+    if (queryTerms.length === 0 || docTokens.length === 0) {
+      return 0;
+    }
+    const avgDocLength = index.getAvgDocLength();
+    const docLength = docTokens.length;
+    if (avgDocLength === 0) {
+      return 0;
+    }
+    const termFreqs = /* @__PURE__ */ new Map();
+    for (const token of docTokens) {
+      termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
+    }
+    let score = 0;
+    for (const term of queryTerms) {
+      const tf = termFreqs.get(term) || 0;
+      if (tf === 0) {
+        continue;
+      }
+      const idf = index.getIDF(term);
+      if (idf <= 0) {
+        continue;
+      }
+      const numerator = tf * (this.k1 + 1);
+      const denominator = tf + this.k1 * (1 - this.b + this.b * (docLength / avgDocLength));
+      const termScore = idf * (numerator / denominator);
+      score += termScore;
+    }
+    return score;
+  }
+  /**
+   * Get the k1 parameter value.
+   */
+  getK1() {
+    return this.k1;
+  }
+  /**
+   * Get the b parameter value.
+   */
+  getB() {
+    return this.b;
+  }
+};
+
+// src/fts/IndexSerializer.ts
+var IndexSerializer = class {
+  /**
+   * Serialize inverted index to a JSON-serializable object.
+   * Note: In a real app, you might want to encoding this to binary (msgpack) later.
+   */
+  serialize(index) {
+    const data = {
+      version: 1,
+      metadata: {
+        totalDocs: index.getTotalDocs(),
+        avgDocLength: index.getAvgDocLength(),
+        createdAt: Date.now(),
+        lastModified: Date.now()
+      },
+      terms: this.serializeTerms(index),
+      docLengths: this.serializeDocLengths(index)
+    };
+    return data;
+  }
+  /**
+   * Deserialize from object into a new BM25InvertedIndex.
+   */
+  deserialize(data) {
+    if (data.version !== 1) {
+      throw new Error(`Unsupported index version: ${data.version}`);
+    }
+    const index = new BM25InvertedIndex();
+    this.loadIntoIndex(index, data);
+    return index;
+  }
+  serializeTerms(index) {
+    const terms = [];
+    const indexMap = index.index;
+    for (const term of index.getTerms()) {
+      const termInfos = index.getDocumentsForTerm(term);
+      terms.push({
+        term,
+        idf: index.getIDF(term),
+        postings: termInfos.map((info) => ({
+          docId: info.docId,
+          termFrequency: info.termFrequency,
+          positions: info.fieldPositions
+        }))
+      });
+    }
+    return terms;
+  }
+  serializeDocLengths(index) {
+    const lengths = {};
+    for (const [docId, length] of index.getDocLengths()) {
+      lengths[docId] = length;
+    }
+    return lengths;
+  }
+  loadIntoIndex(index, data) {
+    const idx = index;
+    idx.totalDocs = data.metadata.totalDocs;
+    idx.avgDocLength = data.metadata.avgDocLength;
+    idx.docLengths = new Map(Object.entries(data.docLengths));
+    for (const { term, idf, postings } of data.terms) {
+      const termInfos = postings.map((p) => ({
+        docId: p.docId,
+        termFrequency: p.termFrequency,
+        fieldPositions: p.positions
+      }));
+      idx.index.set(term, termInfos);
+      idx.idfCache.set(term, idf);
+      for (const info of termInfos) {
+        if (!idx.docTerms.has(info.docId)) {
+          idx.docTerms.set(info.docId, /* @__PURE__ */ new Set());
+        }
+        idx.docTerms.get(info.docId).add(term);
+      }
+    }
+  }
+};
+
+// src/fts/FullTextIndex.ts
+var FullTextIndex = class {
+  /**
+   * Create a new FullTextIndex.
+   *
+   * @param config - Index configuration
+   */
+  constructor(config) {
+    this.fields = config.fields;
+    this.tokenizer = new BM25Tokenizer(config.tokenizer);
+    this.scorer = new BM25Scorer(config.bm25);
+    this.fieldIndexes = /* @__PURE__ */ new Map();
+    this.combinedIndex = new BM25InvertedIndex();
+    this.indexedDocs = /* @__PURE__ */ new Set();
+    this.serializer = new IndexSerializer();
+    this.documentTokensCache = /* @__PURE__ */ new Map();
+    for (const field of this.fields) {
+      this.fieldIndexes.set(field, new BM25InvertedIndex());
+    }
+  }
+  /**
+   * Index a document (add or update).
+   * Called when a document is set in the CRDT map.
+   *
+   * @param docId - Document identifier
+   * @param document - Document data containing fields to index
+   */
+  onSet(docId, document) {
+    if (!document || typeof document !== "object") {
+      this.documentTokensCache.delete(docId);
+      return;
+    }
+    if (this.indexedDocs.has(docId)) {
+      this.removeFromIndexes(docId);
+    }
+    const allTokens = [];
+    for (const field of this.fields) {
+      const value = document[field];
+      if (typeof value !== "string") {
+        continue;
+      }
+      const tokens = this.tokenizer.tokenize(value);
+      if (tokens.length > 0) {
+        const fieldIndex = this.fieldIndexes.get(field);
+        fieldIndex.addDocument(docId, tokens);
+        allTokens.push(...tokens);
+      }
+    }
+    if (allTokens.length > 0) {
+      this.combinedIndex.addDocument(docId, allTokens);
+      this.indexedDocs.add(docId);
+      this.documentTokensCache.set(docId, allTokens);
+    } else {
+      this.documentTokensCache.delete(docId);
+    }
+  }
+  /**
+   * Remove a document from the index.
+   * Called when a document is deleted from the CRDT map.
+   *
+   * @param docId - Document identifier to remove
+   */
+  onRemove(docId) {
+    if (!this.indexedDocs.has(docId)) {
+      return;
+    }
+    this.removeFromIndexes(docId);
+    this.indexedDocs.delete(docId);
+    this.documentTokensCache.delete(docId);
+  }
+  /**
+   * Search the index with a query.
+   *
+   * @param query - Search query text
+   * @param options - Search options (limit, minScore, boost)
+   * @returns Array of search results, sorted by relevance
+   */
+  search(query, options) {
+    const queryTerms = this.tokenizer.tokenize(query);
+    if (queryTerms.length === 0) {
+      return [];
+    }
+    const boost = options?.boost;
+    let results;
+    if (boost && Object.keys(boost).length > 0) {
+      results = this.searchWithBoost(queryTerms, boost);
+    } else {
+      results = this.scorer.score(queryTerms, this.combinedIndex);
+    }
+    if (options?.minScore !== void 0) {
+      results = results.filter((r) => r.score >= options.minScore);
+    }
+    if (options?.limit !== void 0 && options.limit > 0) {
+      results = results.slice(0, options.limit);
+    }
+    return results.map((r) => ({
+      docId: r.docId,
+      score: r.score,
+      matchedTerms: r.matchedTerms,
+      source: "fulltext"
+    }));
+  }
+  /**
+   * Serialize the index state.
+   *
+   * @returns Serialized index data
+   */
+  serialize() {
+    return this.serializer.serialize(this.combinedIndex);
+  }
+  /**
+   * Load index from serialized state.
+   *
+   * @param data - Serialized index data
+   */
+  load(data) {
+    this.combinedIndex = this.serializer.deserialize(data);
+    this.indexedDocs.clear();
+    for (const [docId] of this.combinedIndex.getDocLengths()) {
+      this.indexedDocs.add(docId);
+    }
+    this.fieldIndexes.clear();
+    for (const field of this.fields) {
+      this.fieldIndexes.set(field, new BM25InvertedIndex());
+    }
+    this.documentTokensCache.clear();
+  }
+  /**
+   * Build the index from an array of entries.
+   * Useful for initial bulk loading.
+   *
+   * @param entries - Array of [docId, document] tuples
+   */
+  buildFromEntries(entries) {
+    for (const [docId, document] of entries) {
+      this.onSet(docId, document);
+    }
+  }
+  /**
+   * Clear all data from the index.
+   */
+  clear() {
+    this.combinedIndex.clear();
+    for (const fieldIndex of this.fieldIndexes.values()) {
+      fieldIndex.clear();
+    }
+    this.indexedDocs.clear();
+    this.documentTokensCache.clear();
+  }
+  /**
+   * Get the number of indexed documents.
+   *
+   * @returns Number of documents in the index
+   */
+  getSize() {
+    return this.indexedDocs.size;
+  }
+  /**
+   * Tokenize a query string using the index's tokenizer.
+   * Public method for external use (e.g., SearchCoordinator).
+   *
+   * @param query - Query text to tokenize
+   * @returns Array of tokenized terms
+   */
+  tokenizeQuery(query) {
+    return this.tokenizer.tokenize(query);
+  }
+  /**
+   * Score a single document against query terms.
+   * O(Q × D) complexity where Q = query terms, D = document tokens.
+   *
+   * This method is optimized for checking if a single document
+   * matches a query, avoiding full index scan.
+   *
+   * @param docId - Document ID to score
+   * @param queryTerms - Pre-tokenized query terms
+   * @param document - Optional document data (used if not in cache)
+   * @returns SearchResult with score and matched terms, or null if no match
+   */
+  scoreSingleDocument(docId, queryTerms, document) {
+    if (queryTerms.length === 0) {
+      return null;
+    }
+    let docTokens = this.documentTokensCache.get(docId);
+    if (!docTokens && document) {
+      docTokens = this.tokenizeDocument(document);
+    }
+    if (!docTokens || docTokens.length === 0) {
+      return null;
+    }
+    const docTokenSet = new Set(docTokens);
+    const matchedTerms = queryTerms.filter((term) => docTokenSet.has(term));
+    if (matchedTerms.length === 0) {
+      return null;
+    }
+    const score = this.scorer.scoreSingleDocument(
+      queryTerms,
+      docTokens,
+      this.combinedIndex
+    );
+    if (score <= 0) {
+      return null;
+    }
+    return {
+      docId,
+      score,
+      matchedTerms,
+      source: "fulltext"
+    };
+  }
+  /**
+   * Tokenize all indexed fields of a document.
+   * Internal helper for scoreSingleDocument when document not in cache.
+   *
+   * @param document - Document data
+   * @returns Array of all tokens from indexed fields
+   */
+  tokenizeDocument(document) {
+    const allTokens = [];
+    for (const field of this.fields) {
+      const value = document[field];
+      if (typeof value === "string") {
+        const tokens = this.tokenizer.tokenize(value);
+        allTokens.push(...tokens);
+      }
+    }
+    return allTokens;
+  }
+  /**
+   * Get the index name (for debugging/display).
+   *
+   * @returns Descriptive name including indexed fields
+   */
+  get name() {
+    return `FullTextIndex(${this.fields.join(", ")})`;
+  }
+  /**
+   * Remove document from all indexes (internal).
+   */
+  removeFromIndexes(docId) {
+    this.combinedIndex.removeDocument(docId);
+    for (const fieldIndex of this.fieldIndexes.values()) {
+      fieldIndex.removeDocument(docId);
+    }
+  }
+  /**
+   * Search with field boosting.
+   * Scores are computed per-field and combined with boost weights.
+   */
+  searchWithBoost(queryTerms, boost) {
+    const docScores = /* @__PURE__ */ new Map();
+    for (const field of this.fields) {
+      const fieldIndex = this.fieldIndexes.get(field);
+      const boostWeight = boost[field] ?? 1;
+      const fieldResults = this.scorer.score(queryTerms, fieldIndex);
+      for (const result of fieldResults) {
+        const current = docScores.get(result.docId) || {
+          score: 0,
+          terms: /* @__PURE__ */ new Set()
+        };
+        current.score += result.score * boostWeight;
+        for (const term of result.matchedTerms) {
+          current.terms.add(term);
+        }
+        docScores.set(result.docId, current);
+      }
+    }
+    const results = [];
+    for (const [docId, { score, terms }] of docScores) {
+      results.push({
+        docId,
+        score,
+        matchedTerms: Array.from(terms)
+      });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+};
+
 // src/IndexedORMap.ts
 var IndexedORMap = class extends ORMap {
   constructor(hlc, options = {}) {
     super(hlc);
+    // Full-Text Search (Phase 11)
+    this.fullTextIndex = null;
     this.options = options;
     this.indexRegistry = new IndexRegistry();
     this.queryOptimizer = new QueryOptimizer({
@@ -8713,6 +9864,104 @@ var IndexedORMap = class extends ORMap {
     this.indexRegistry.addIndex(index);
     this.buildIndexFromExisting(index);
   }
+  // ==================== Full-Text Search (Phase 11) ====================
+  /**
+   * Enable BM25-based full-text search on specified fields.
+   * This creates a FullTextIndex for relevance-ranked search.
+   *
+   * Note: This is different from addInvertedIndex which provides
+   * boolean matching (contains/containsAll/containsAny). This method
+   * provides BM25 relevance scoring for true full-text search.
+   *
+   * @param config - Full-text index configuration
+   * @returns The created FullTextIndex
+   *
+   * @example
+   * ```typescript
+   * const map = new IndexedORMap(hlc);
+   * map.enableFullTextSearch({
+   *   fields: ['title', 'body'],
+   *   tokenizer: { minLength: 2 },
+   *   bm25: { k1: 1.2, b: 0.75 }
+   * });
+   *
+   * map.add('doc1', { title: 'Hello World', body: 'Test content' });
+   * const results = map.search('hello');
+   * // [{ key: 'doc1', tag: '...', value: {...}, score: 0.5, matchedTerms: ['hello'] }]
+   * ```
+   */
+  enableFullTextSearch(config) {
+    this.fullTextIndex = new FullTextIndex(config);
+    const snapshot = this.getSnapshot();
+    const entries = [];
+    for (const [key, tagMap] of snapshot.items) {
+      for (const [tag, record] of tagMap) {
+        if (!snapshot.tombstones.has(tag)) {
+          const compositeKey = this.createCompositeKey(key, tag);
+          entries.push([compositeKey, record.value]);
+        }
+      }
+    }
+    this.fullTextIndex.buildFromEntries(entries);
+    return this.fullTextIndex;
+  }
+  /**
+   * Check if full-text search is enabled.
+   *
+   * @returns true if full-text search is enabled
+   */
+  isFullTextSearchEnabled() {
+    return this.fullTextIndex !== null;
+  }
+  /**
+   * Get the full-text index (if enabled).
+   *
+   * @returns The FullTextIndex or null
+   */
+  getFullTextIndex() {
+    return this.fullTextIndex;
+  }
+  /**
+   * Perform a BM25-ranked full-text search.
+   * Results are sorted by relevance score (highest first).
+   *
+   * @param query - Search query text
+   * @param options - Search options (limit, minScore, boost)
+   * @returns Array of search results with scores, sorted by relevance
+   *
+   * @throws Error if full-text search is not enabled
+   */
+  search(query, options) {
+    if (!this.fullTextIndex) {
+      throw new Error("Full-text search is not enabled. Call enableFullTextSearch() first.");
+    }
+    const scoredDocs = this.fullTextIndex.search(query, options);
+    const results = [];
+    for (const { docId: compositeKey, score, matchedTerms } of scoredDocs) {
+      const [key, tag] = this.parseCompositeKey(compositeKey);
+      const records = this.getRecords(key);
+      const record = records.find((r) => r.tag === tag);
+      if (record) {
+        results.push({
+          key,
+          tag,
+          value: record.value,
+          score,
+          matchedTerms: matchedTerms ?? []
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Disable full-text search and release the index.
+   */
+  disableFullTextSearch() {
+    if (this.fullTextIndex) {
+      this.fullTextIndex.clear();
+      this.fullTextIndex = null;
+    }
+  }
   /**
    * Remove an index.
    *
@@ -8866,6 +10115,9 @@ var IndexedORMap = class extends ORMap {
     const record = super.add(key, value, ttlMs);
     const compositeKey = this.createCompositeKey(key, record.tag);
     this.indexRegistry.onRecordAdded(compositeKey, value);
+    if (this.fullTextIndex) {
+      this.fullTextIndex.onSet(compositeKey, value);
+    }
     return record;
   }
   /**
@@ -8878,6 +10130,9 @@ var IndexedORMap = class extends ORMap {
     for (const record of matchingRecords) {
       const compositeKey = this.createCompositeKey(key, record.tag);
       this.indexRegistry.onRecordRemoved(compositeKey, record.value);
+      if (this.fullTextIndex) {
+        this.fullTextIndex.onRemove(compositeKey);
+      }
     }
     return result;
   }
@@ -8889,6 +10144,9 @@ var IndexedORMap = class extends ORMap {
     if (applied) {
       const compositeKey = this.createCompositeKey(key, record.tag);
       this.indexRegistry.onRecordAdded(compositeKey, record.value);
+      if (this.fullTextIndex) {
+        this.fullTextIndex.onSet(compositeKey, record.value);
+      }
     }
     return applied;
   }
@@ -8911,6 +10169,9 @@ var IndexedORMap = class extends ORMap {
     if (removedValue !== void 0 && removedKey !== void 0) {
       const compositeKey = this.createCompositeKey(removedKey, tag);
       this.indexRegistry.onRecordRemoved(compositeKey, removedValue);
+      if (this.fullTextIndex) {
+        this.fullTextIndex.onRemove(compositeKey);
+      }
     }
   }
   /**
@@ -8919,6 +10180,9 @@ var IndexedORMap = class extends ORMap {
   clear() {
     super.clear();
     this.indexRegistry.clear();
+    if (this.fullTextIndex) {
+      this.fullTextIndex.clear();
+    }
   }
   // ==================== Helper Methods ====================
   /**
@@ -9272,6 +10536,7 @@ var IndexedORMap = class extends ORMap {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthMessageSchema,
+  BM25Scorer,
   BatchMessageSchema,
   BuiltInProcessors,
   BuiltInResolvers,
@@ -9295,6 +10560,7 @@ var IndexedORMap = class extends ORMap {
   DEFAULT_RESOLVER_RATE_LIMITS,
   DEFAULT_STOP_WORDS,
   DEFAULT_WRITE_CONCERN_TIMEOUT,
+  ENGLISH_STOPWORDS,
   EntryProcessBatchRequestSchema,
   EntryProcessBatchResponseSchema,
   EntryProcessKeyResultSchema,
@@ -9304,8 +10570,11 @@ var IndexedORMap = class extends ORMap {
   EntryProcessorSchema,
   EventJournalImpl,
   FORBIDDEN_PATTERNS,
+  FTSInvertedIndex,
+  FTSTokenizer,
   FallbackIndex,
   FilteringResultSet,
+  FullTextIndex,
   HLC,
   HashIndex,
   IndexRegistry,
@@ -9372,6 +10641,18 @@ var IndexedORMap = class extends ORMap {
   RegisterResolverRequestSchema,
   RegisterResolverResponseSchema,
   Ringbuffer,
+  SearchMessageSchema,
+  SearchOptionsSchema,
+  SearchPayloadSchema,
+  SearchRespMessageSchema,
+  SearchRespPayloadSchema,
+  SearchSubMessageSchema,
+  SearchSubPayloadSchema,
+  SearchUnsubMessageSchema,
+  SearchUnsubPayloadSchema,
+  SearchUpdateMessageSchema,
+  SearchUpdatePayloadSchema,
+  SearchUpdateTypeSchema,
   SetResultSet,
   SimpleAttribute,
   SortedMap,
@@ -9417,6 +10698,7 @@ var IndexedORMap = class extends ORMap {
   isUsingNativeHash,
   isWriteConcernAchieved,
   multiAttribute,
+  porterStem,
   resetNativeHash,
   serialize,
   simpleAttribute,