@delali/narsil 0.2.4-next.49 → 0.2.4-next.50

package/dist/chunk-ZHUQKZBE.mjs

@@ -0,0 +1,1292 @@
+import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, DEFAULT_LIMIT, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, DEFAULT_OFFSET } from './chunk-XE6XR2OE.mjs';
+import { clampRowCount, sortSignatureOf, requireSortableFields, decodePageCursor, requireMatchingCursor, resolveProjection, encodePageCursor, requireWithinResultWindow, normalizeSort, fanOutQuery, flattenSchema, applySorting, applyPagination, countsWithoutScores, fanOutMatchCount, tokenize, fnv1aBytes, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, partitionsIn } from './chunk-CMVG2UEF.mjs';
+import { compareCodePoints, compareComparableKeys } from './chunk-2GWVQWGA.mjs';
+import { NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+
+// src/search/cursor-binding.ts
+var ABSENT_TAG = 0;
+var NULL_TAG = 1;
+var FALSE_TAG = 2;
+var TRUE_TAG = 3;
+var NUMBER_TAG = 4;
+var STRING_TAG = 5;
+var LIST_TAG = 6;
+var MAP_TAG = 7;
+var encoder = new TextEncoder();
+function ensureCapacity(stream, extra) {
+  if (stream.length + extra <= stream.bytes.length) return;
+  const grown = new Uint8Array(Math.max(stream.bytes.length * 2, stream.length + extra));
+  grown.set(stream.bytes.subarray(0, stream.length));
+  stream.bytes = grown;
+}
+function writeByte(stream, value) {
+  ensureCapacity(stream, 1);
+  stream.bytes[stream.length] = value;
+  stream.length += 1;
+}
+function writeUint32(stream, value) {
+  ensureCapacity(stream, 4);
+  stream.bytes[stream.length] = value >>> 24 & 255;
+  stream.bytes[stream.length + 1] = value >>> 16 & 255;
+  stream.bytes[stream.length + 2] = value >>> 8 & 255;
+  stream.bytes[stream.length + 3] = value & 255;
+  stream.length += 4;
+}
+var numberBytes = new DataView(new ArrayBuffer(8));
+function writeNumber(stream, value) {
+  numberBytes.setFloat64(0, value, false);
+  ensureCapacity(stream, 8);
+  for (let i = 0; i < 8; i++) {
+    stream.bytes[stream.length + i] = numberBytes.getUint8(i);
+  }
+  stream.length += 8;
+}
+function writeString(stream, value) {
+  const encoded = encoder.encode(value);
+  writeUint32(stream, encoded.length);
+  ensureCapacity(stream, encoded.length);
+  stream.bytes.set(encoded, stream.length);
+  stream.length += encoded.length;
+}
+var NumberList = class {
+  constructor(members) {
+    this.members = members;
+  }
+};
+var NUMBER_MEMBER_BYTES = 9;
+var LIST_HEADER_BYTES = 5;
+function writeNumberList(stream, list) {
+  const count = list.members.length;
+  ensureCapacity(stream, LIST_HEADER_BYTES + count * NUMBER_MEMBER_BYTES);
+  const bytes = stream.bytes;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let at = stream.length;
+  bytes[at] = LIST_TAG;
+  view.setUint32(at + 1, count, false);
+  at += LIST_HEADER_BYTES;
+  for (let i = 0; i < count; i++) {
+    bytes[at] = NUMBER_TAG;
+    view.setFloat64(at + 1, Math.fround(list.members[i]), false);
+    at += NUMBER_MEMBER_BYTES;
+  }
+  stream.length = at;
+}
+function writeValue(stream, value) {
+  if (value instanceof NumberList) {
+    writeNumberList(stream, value);
+    return;
+  }
+  if (value === void 0) {
+    writeByte(stream, ABSENT_TAG);
+    return;
+  }
+  if (value === null) {
+    writeByte(stream, NULL_TAG);
+    return;
+  }
+  if (typeof value === "boolean") {
+    writeByte(stream, value ? TRUE_TAG : FALSE_TAG);
+    return;
+  }
+  if (typeof value === "number") {
+    writeByte(stream, NUMBER_TAG);
+    writeNumber(stream, value);
+    return;
+  }
+  if (typeof value === "string") {
+    writeByte(stream, STRING_TAG);
+    writeString(stream, value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    writeByte(stream, LIST_TAG);
+    writeUint32(stream, value.length);
+    for (const member of value) {
+      writeValue(stream, member ?? null);
+    }
+    return;
+  }
+  const record = value;
+  const keys = Object.keys(record).sort(compareCodePoints);
+  writeByte(stream, MAP_TAG);
+  writeUint32(stream, keys.length);
+  for (const key of keys) {
+    writeByte(stream, STRING_TAG);
+    writeString(stream, key);
+    writeValue(stream, record[key] ?? null);
+  }
+}
+function boundVectorOf(vector) {
+  if (vector === void 0) return void 0;
+  const bound = { ...vector };
+  if (vector.value !== void 0) {
+    bound.value = new NumberList(vector.value);
+  }
+  if (vector.text !== void 0) {
+    delete bound.value;
+  }
+  return bound;
+}
+var FILTERS_SLOT = 2;
+var BOUND_SLOT_COUNT = 15;
+function bindingOf(values) {
+  const stream = { bytes: new Uint8Array(256), length: 0 };
+  for (const value of values) {
+    writeValue(stream, value);
+  }
+  return fnv1aBytes(stream.bytes.subarray(0, stream.length)).toString(16).padStart(8, "0");
+}
+function queryBindingOf(params) {
+  return bindingOf([
+    params.term,
+    params.fields,
+    params.filters,
+    params.boost,
+    params.minScore,
+    params.termMatch,
+    params.tolerance,
+    params.prefixLength,
+    params.prefix,
+    params.exact,
+    params.pinned,
+    params.mode,
+    params.hybrid,
+    boundVectorOf(params.vector),
+    params.scoring ?? "local"
+  ]);
+}
+function listBindingOf(filters) {
+  const values = new Array(BOUND_SLOT_COUNT).fill(void 0);
+  values[FILTERS_SLOT] = filters;
+  return bindingOf(values);
+}
+
+// src/engine/validation.ts
+function now() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+function validateIndexName(name) {
+  if (!name || name.length === 0) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "Index name must not be empty", { indexName: name });
+  }
+  if (name.length > MAX_INDEX_NAME_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.INDEX_NOT_FOUND,
+      `Index name must not exceed ${MAX_INDEX_NAME_LENGTH} characters`,
+      {
+        indexName: name,
+        length: name.length
+      }
+    );
+  }
+  if (!INDEX_NAME_PATTERN.test(name)) {
+    throw new NarsilError(
+      ErrorCodes.INDEX_NOT_FOUND,
+      `Index name "${name}" contains invalid characters; use alphanumeric, dots, hyphens, and underscores only`,
+      { indexName: name }
+    );
+  }
+  if (name.includes("..")) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index name "${name}" must not contain ".."`, { indexName: name });
+  }
+}
+function validateDocId(docId) {
+  if (!docId || docId.length === 0) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not be empty", { docId });
+  }
+  if (docId.length > MAX_DOC_ID_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Document ID must not exceed ${MAX_DOC_ID_LENGTH} characters`,
+      {
+        docId,
+        length: docId.length
+      }
+    );
+  }
+  if (docId.includes("\0")) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not contain null bytes", { docId });
+  }
+}
+function validatePartitionConfig(partitions) {
+  const { maxDocsPerPartition, maxPartitions, watermark } = partitions;
+  if (maxDocsPerPartition !== void 0 && (!Number.isInteger(maxDocsPerPartition) || maxDocsPerPartition < 1)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "partitions.maxDocsPerPartition must be a positive integer", {
+      maxDocsPerPartition
+    });
+  }
+  if (maxPartitions !== void 0 && (!Number.isInteger(maxPartitions) || maxPartitions < 1)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "partitions.maxPartitions must be a positive integer", {
+      maxPartitions
+    });
+  }
+  if (watermark !== void 0 && (typeof watermark !== "number" || !(watermark > 0) || watermark > 1)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "partitions.watermark must be above 0 and at most 1", {
+      watermark
+    });
+  }
+}
+function requirePositiveSafeInteger(field, value) {
+  if (value === void 0) return;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, `${field} must be a positive safe integer`, { field, value });
+  }
+}
+function validateWorkerConfig(workers, lifecycle) {
+  if (workers === void 0) return;
+  requirePositiveSafeInteger("workers.count", workers.count);
+  requirePositiveSafeInteger("workers.promotionThreshold", workers.promotionThreshold);
+  requirePositiveSafeInteger("workers.idleTimeoutMs", workers.idleTimeoutMs);
+  if (workers.mainCopyQueries !== void 0 && workers.mainCopyQueries !== "lone" && workers.mainCopyQueries !== "none") {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "workers.mainCopyQueries must be 'lone' or 'none'", {
+      mainCopyQueries: workers.mainCopyQueries
+    });
+  }
+  const closeAfter = lifecycle?.idleTimeoutMs;
+  if (workers.idleTimeoutMs !== void 0 && closeAfter !== void 0 && workers.idleTimeoutMs > closeAfter) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      "workers.idleTimeoutMs must be at most lifecycle.idleTimeoutMs, so that an index drops its copies before it closes",
+      { workersIdleTimeoutMs: workers.idleTimeoutMs, lifecycleIdleTimeoutMs: closeAfter }
+    );
+  }
+}
+function validateBM25Params(bm25) {
+  if (bm25 === void 0) return;
+  const { k1, b } = bm25;
+  if (k1 !== void 0 && (!Number.isFinite(k1) || k1 < 0)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "bm25.k1 must be a finite number at or above 0", { k1 });
+  }
+  if (b !== void 0 && (!Number.isFinite(b) || b < 0 || b > 1)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "bm25.b must be between 0 and 1", { b });
+  }
+}
+function clampLimit(limit) {
+  return clampRowCount(limit, DEFAULT_LIMIT);
+}
+function clampOffset(offset) {
+  return clampRowCount(offset, DEFAULT_OFFSET);
+}
+
+// src/engine/list-documents/index.ts
+function clampListLimit(limit) {
+  const clamped = Math.max(1, clampLimit(limit));
+  requireWithinResultWindow(clamped, 0);
+  return clamped;
+}
+function firstIdAfter(sorted, anchor) {
+  let low = 0;
+  let high = sorted.length;
+  while (low < high) {
+    const mid = low + high >>> 1;
+    if (compareCodePoints(sorted[mid], anchor) <= 0) low = mid + 1;
+    else high = mid;
+  }
+  return low;
+}
+function collectFilterMatches(partitions, filters, schema) {
+  const perPartition = partitions.map((partition) => partition.filterMatches(filters, schema));
+  let total = 0;
+  for (const matches of perPartition) total += matches.count;
+  return { matchesFor: (partitionIndex) => perPartition[partitionIndex] ?? null, total };
+}
+function collectCandidates(partition, anchor, matches, wanted, out) {
+  const sorted = partition.sortedDocIds();
+  let index = anchor === null ? 0 : firstIdAfter(sorted, anchor);
+  let taken = 0;
+  while (index < sorted.length && taken < wanted) {
+    const docId = sorted[index];
+    index++;
+    if (matches !== null && !matches.hasExternal(docId)) continue;
+    out.push(docId);
+    taken++;
+  }
+}
+function pageInIdOrder(partitions, cursor, filtered, limit, binding) {
+  const anchor = cursor === null ? null : cursor.anchor;
+  const candidates = [];
+  for (let index = 0; index < partitions.length; index++) {
+    collectCandidates(
+      partitions[index],
+      anchor,
+      filtered === null ? null : filtered.matchesFor(index),
+      limit + 1,
+      candidates
+    );
+  }
+  candidates.sort(compareCodePoints);
+  const hasMore = candidates.length > limit;
+  const ids = hasMore ? candidates.slice(0, limit) : candidates;
+  const nextCursor = hasMore && ids.length > 0 ? { anchor: ids[ids.length - 1], score: null, sortKey: null, sortSignature: null, binding } : null;
+  return { ids, nextCursor };
+}
+function pageInSortOrder(partitions, cursor, filtered, limit, sort, signature, schema, binding) {
+  const normalized = normalizeSort(sort);
+  const fields = normalized.map((entry) => entry.field);
+  const directions = normalized.map((entry) => entry.direction);
+  const flatSchema = flattenSchema(schema);
+  const fieldTypes = fields.map((field) => flatSchema[field]);
+  const request = {
+    fields,
+    directions,
+    fieldTypes,
+    limit: limit + 1,
+    anchorKey: cursor === null ? null : cursor.sortKey,
+    anchorId: cursor === null ? null : cursor.anchor
+  };
+  const merged = [];
+  for (let index = 0; index < partitions.length; index++) {
+    const matches = filtered === null ? null : filtered.matchesFor(index);
+    for (const entry of partitions[index].sortedPage({ ...request, matches })) merged.push(entry);
+  }
+  merged.sort((a, b) => compareComparableKeys(a.key, b.key, directions) || compareCodePoints(a.id, b.id));
+  const hasMore = merged.length > limit;
+  const page = hasMore ? merged.slice(0, limit) : merged;
+  const last = page[page.length - 1];
+  const nextCursor = hasMore && last !== void 0 ? { anchor: last.id, score: null, sortKey: last.key, sortSignature: signature, binding } : null;
+  return { ids: page.map((entry) => entry.id), nextCursor };
+}
+function countAcrossPartitions(manager, partitionIds, partitions) {
+  if (partitionIds === void 0) {
+    return manager.countDocuments();
+  }
+  let total = 0;
+  for (const partition of partitions) {
+    total += partition.count();
+  }
+  return total;
+}
+function executeListDocuments(params, context) {
+  const { manager, schema } = context;
+  const startTime = now();
+  const limit = clampListLimit(params.limit);
+  const signature = sortSignatureOf(params.sort);
+  requireSortableFields(params.sort, schema);
+  const binding = listBindingOf(params.filters);
+  let cursor = null;
+  if (params.cursor !== void 0) {
+    cursor = decodePageCursor(params.cursor);
+    requireMatchingCursor(cursor, params.cursor, signature, false, binding);
+  }
+  const partitions = context.partitionIds === void 0 ? manager.getAllPartitions() : context.partitionIds.map((partitionId) => manager.partitionAt(partitionId)).filter((partition) => partition !== void 0);
+  const filtered = params.filters === void 0 ? null : collectFilterMatches(partitions, params.filters, schema);
+  const total = filtered === null ? countAcrossPartitions(manager, context.partitionIds, partitions) : filtered.total;
+  const page = params.sort === void 0 || signature === null ? pageInIdOrder(partitions, cursor, filtered, limit, binding) : pageInSortOrder(partitions, cursor, filtered, limit, params.sort, signature, schema, binding);
+  const projection = resolveProjection(params.document);
+  const documents = [];
+  for (const docId of page.ids) {
+    if (projection.kind === "none") {
+      documents.push({ id: docId, document: {} });
+      continue;
+    }
+    const stored = manager.get(docId, projection);
+    if (stored === void 0) continue;
+    documents.push({ id: docId, document: stored });
+  }
+  if (page.nextCursor === null) {
+    for (const partition of partitions) partition.releaseSortedDocIds();
+  }
+  return {
+    documents,
+    cursor: page.nextCursor === null ? null : encodePageCursor(page.nextCursor),
+    total,
+    elapsed: now() - startTime
+  };
+}
+
+// src/search/grouping.ts
+function getNestedValue(obj, path) {
+  const segments = path.split(".");
+  let current = obj;
+  for (const segment of segments) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    if (!Object.hasOwn(current, segment)) {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function applyGrouping(hits, group, getDocument) {
+  if (!group.fields || group.fields.length === 0) {
+    return [{ values: {}, hits }];
+  }
+  const groupMap = /* @__PURE__ */ new Map();
+  for (const hit of hits) {
+    const doc = getDocument(hit.id);
+    const fieldValues = [];
+    const valuesRecord = {};
+    for (const field of group.fields) {
+      const value = doc ? getNestedValue(doc, field) : void 0;
+      fieldValues.push(value);
+      valuesRecord[field] = value;
+    }
+    const compositeKey = JSON.stringify(fieldValues);
+    const existing = groupMap.get(compositeKey);
+    if (existing) {
+      existing.hits.push(hit);
+    } else {
+      groupMap.set(compositeKey, { values: valuesRecord, hits: [hit] });
+    }
+  }
+  const groups = [];
+  for (const entry of groupMap.values()) {
+    let groupHits = entry.hits;
+    if (group.maxPerGroup !== void 0 && group.maxPerGroup > 0) {
+      groupHits = groupHits.slice(0, group.maxPerGroup);
+    }
+    const result = { values: entry.values, hits: groupHits };
+    if (group.reduce) {
+      const folded = foldGroupReducer(
+        group.reduce,
+        groupHits.map((hit) => ({ document: getDocument(hit.id), score: hit.score ?? 0 }))
+      );
+      if (folded.reducerError !== void 0) {
+        result.reducerError = folded.reducerError;
+      } else {
+        result.reduced = folded.reduced;
+      }
+    }
+    groups.push(result);
+  }
+  groups.sort((a, b) => {
+    const aScore = a.hits.length > 0 ? a.hits[0].score ?? 0 : 0;
+    const bScore = b.hits.length > 0 ? b.hits[0].score ?? 0 : 0;
+    if (aScore !== bScore) return bScore - aScore;
+    const aId = a.hits.length > 0 ? a.hits[0].id : "";
+    const bId = b.hits.length > 0 ? b.hits[0].id : "";
+    return compareCodePoints(aId, bId);
+  });
+  if (group.limit !== void 0 && Number.isFinite(group.limit) && group.limit >= 0) {
+    const cap = Math.floor(group.limit);
+    if (groups.length > cap) {
+      groups.length = cap;
+    }
+  }
+  return groups;
+}
+function foldGroupReducer(reduce, rows) {
+  try {
+    let accumulator = reduce.initialValue();
+    for (const row of rows) {
+      if (row.document !== void 0) {
+        accumulator = reduce.reducer(accumulator, row.document, row.score);
+      }
+    }
+    return { reduced: accumulator };
+  } catch (err) {
+    return { reducerError: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+// src/search/pinning.ts
+function dedupePinnedEntries(pinned) {
+  const deduped = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of pinned) {
+    if (seen.has(entry.docId)) continue;
+    seen.add(entry.docId);
+    deduped.push(entry);
+  }
+  return deduped;
+}
+function applyPinning(hits, pinned, resolveDoc) {
+  const result = hits.slice();
+  const deduped = dedupePinnedEntries(pinned);
+  const pinnedDocIds = new Set(deduped.map((entry) => entry.docId));
+  for (let i = result.length - 1; i >= 0; i--) {
+    if (pinnedDocIds.has(result[i].id)) {
+      result.splice(i, 1);
+    }
+  }
+  const sorted = deduped.sort((a, b) => a.position - b.position);
+  for (const entry of sorted) {
+    const doc = resolveDoc(entry.docId);
+    if (!doc) continue;
+    const pos = Math.max(0, Math.min(entry.position, result.length));
+    result.splice(pos, 0, doc);
+  }
+  return result;
+}
+
+// src/highlighting/highlighter.ts
+function buildTokenCharOffsets(text, originalTokens) {
+  const offsets = [];
+  let searchFrom = 0;
+  for (const token of originalTokens) {
+    const idx = text.indexOf(token, searchFrom);
+    if (idx === -1) continue;
+    offsets.push({ start: idx, end: idx + token.length });
+    searchFrom = idx + token.length;
+  }
+  return offsets;
+}
+function mergeOverlapping(ranges) {
+  if (ranges.length === 0) return [];
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  const merged = [sorted[0]];
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = merged[merged.length - 1];
+    const curr = sorted[i];
+    if (curr.start <= prev.end) {
+      prev.end = Math.max(prev.end, curr.end);
+    } else {
+      merged.push(curr);
+    }
+  }
+  return merged;
+}
+function findDensestWindow(positions, text, windowSize) {
+  if (positions.length === 0) {
+    return { start: 0, end: Math.min(windowSize, text.length) };
+  }
+  let bestStart = 0;
+  let bestCount = 0;
+  for (const pos of positions) {
+    const windowStart = Math.max(0, pos.start - Math.floor(windowSize / 2));
+    const windowEnd = Math.min(text.length, windowStart + windowSize);
+    const adjustedStart = Math.max(0, windowEnd - windowSize);
+    let count = 0;
+    for (const p of positions) {
+      if (p.start >= adjustedStart && p.end <= windowEnd) {
+        count++;
+      }
+    }
+    if (count > bestCount) {
+      bestCount = count;
+      bestStart = adjustedStart;
+    }
+  }
+  return { start: bestStart, end: Math.min(text.length, bestStart + windowSize) };
+}
+function applySnippetTruncation(taggedText, originalText, positions, maxLen, preTag, postTag) {
+  if (maxLen <= 0 || originalText.length <= maxLen) {
+    return { snippet: taggedText, adjustedPositions: positions };
+  }
+  const window = findDensestWindow(positions, originalText, maxLen);
+  const snippetRaw = originalText.substring(window.start, window.end);
+  const adjustedPositions = [];
+  for (const pos of positions) {
+    if (pos.start >= window.start && pos.end <= window.end) {
+      adjustedPositions.push({
+        start: pos.start - window.start,
+        end: pos.end - window.start
+      });
+    }
+  }
+  let snippet = snippetRaw;
+  const sortedDesc = [...adjustedPositions].sort((a, b) => b.start - a.start);
+  for (const pos of sortedDesc) {
+    snippet = snippet.substring(0, pos.start) + preTag + snippet.substring(pos.start, pos.end) + postTag + snippet.substring(pos.end);
+  }
+  const needsLeadingEllipsis = window.start > 0;
+  const needsTrailingEllipsis = window.end < originalText.length;
+  if (needsLeadingEllipsis) snippet = `...${snippet}`;
+  if (needsTrailingEllipsis) snippet = `${snippet}...`;
+  return { snippet, adjustedPositions };
+}
+function highlightField(text, queryTokens, language, options) {
+  const preTag = options?.preTag ?? "<mark>";
+  const postTag = options?.postTag ?? "</mark>";
+  const maxSnippetLength = options?.maxSnippetLength ?? 200;
+  if (text.length === 0) {
+    return { snippet: text, positions: [] };
+  }
+  const fieldResult = tokenize(text, language, { stem: false, removeStopWords: false });
+  if (fieldResult.tokens.length === 0) {
+    return { snippet: text, positions: [] };
+  }
+  const lowercaseText = text.normalize("NFC").toLowerCase();
+  const charOffsets = buildTokenCharOffsets(lowercaseText, fieldResult.originalTokens);
+  const stemmedQueryTokens = queryTokens.map((qt) => {
+    if (language.stemmer) {
+      return language.stemmer(qt.token.toLowerCase());
+    }
+    return qt.token.toLowerCase();
+  });
+  const matchedRanges = [];
+  const prefixToken = options?.prefixToken;
+  for (let i = 0; i < fieldResult.tokens.length; i++) {
+    if (i >= charOffsets.length) break;
+    const fieldToken = fieldResult.tokens[i].token;
+    const stemmedField = language.stemmer ? language.stemmer(fieldToken) : fieldToken;
+    if (prefixToken !== void 0 && fieldToken.startsWith(prefixToken)) {
+      matchedRanges.push({ start: charOffsets[i].start, end: charOffsets[i].end });
+      continue;
+    }
+    for (const stemmedQuery of stemmedQueryTokens) {
+      if (stemmedField === stemmedQuery) {
+        matchedRanges.push({ start: charOffsets[i].start, end: charOffsets[i].end });
+        break;
+      }
+    }
+  }
+  const mergedPositions = mergeOverlapping(matchedRanges);
+  if (mergedPositions.length === 0) {
+    if (maxSnippetLength > 0 && text.length > maxSnippetLength) {
+      const truncated = text.substring(0, maxSnippetLength);
+      return { snippet: `${truncated}...`, positions: [] };
+    }
+    return { snippet: text, positions: [] };
+  }
+  if (maxSnippetLength > 0 && text.length > maxSnippetLength) {
+    const { snippet, adjustedPositions } = applySnippetTruncation(
+      text,
+      text,
+      mergedPositions,
+      maxSnippetLength,
+      preTag,
+      postTag
+    );
+    return { snippet, positions: adjustedPositions };
+  }
+  let result = text;
+  const sortedDesc = [...mergedPositions].sort((a, b) => b.start - a.start);
+  for (const pos of sortedDesc) {
+    result = result.substring(0, pos.start) + preTag + result.substring(pos.start, pos.end) + postTag + result.substring(pos.end);
+  }
+  return { snippet: result, positions: mergedPositions };
+}
+
+// src/engine/query/highlight.ts
+function applyHighlights(hits, params, language, analysis) {
+  if (!params.highlight) return;
+  const queryTokenResult = tokenize(params.term ?? "", language, {
+    stem: true,
+    removeStopWords: true,
+    customTokenizer: analysis.customTokenizer,
+    stopWordOverride: analysis.stopWords
+  });
+  let prefixToken;
+  if (params.prefix === true && params.exact !== true && queryTokenResult.tokens.length > 0) {
+    const lastPosition = queryTokenResult.tokens[queryTokenResult.tokens.length - 1].position;
+    const unstemmed = tokenize(params.term ?? "", language, {
+      stem: false,
+      removeStopWords: true,
+      customTokenizer: analysis.customTokenizer,
+      stopWordOverride: analysis.stopWords
+    });
+    for (const t of unstemmed.tokens) {
+      if (t.position === lastPosition) {
+        prefixToken = t.token;
+        break;
+      }
+    }
+  }
+  for (const hit of hits) {
+    const highlights = {};
+    for (const field of params.highlight.fields) {
+      const doc = hit.document;
+      const fieldValue = doc[field];
+      if (typeof fieldValue === "string") {
+        highlights[field] = highlightField(fieldValue, queryTokenResult.tokens, language, {
+          preTag: params.highlight.preTag,
+          postTag: params.highlight.postTag,
+          maxSnippetLength: params.highlight.maxSnippetLength,
+          prefixToken
+        });
+      }
+    }
+    hit.highlights = highlights;
+  }
+}
+
+// src/engine/query/shared.ts
+function partitionsFor(manager, partitionIds) {
+  return partitionsIn(manager, partitionIds);
+}
+function coverageFor(manager, partitionIds) {
+  if (partitionIds === void 0) {
+    return {
+      totalPartitions: manager.partitionCount,
+      queriedPartitions: manager.partitionCount,
+      timedOutPartitions: 0,
+      failedPartitions: 0
+    };
+  }
+  const queriedPartitions = partitionsFor(manager, partitionIds).length;
+  return {
+    totalPartitions: partitionIds.length,
+    queriedPartitions,
+    timedOutPartitions: 0,
+    failedPartitions: partitionIds.length - queriedPartitions
+  };
+}
+function partitionsForVectorSearch(manager, vecIndex, partitionIds) {
+  if (partitionIds === void 0) {
+    return void 0;
+  }
+  if (!vecIndex.partitionsKnown()) {
+    vecIndex.assignPartitions((docId) => manager.partitionIdOf(docId));
+  }
+  return new Set(partitionIds);
+}
+function scoringConfigFor(params, context) {
+  const scoringMode = params.scoring ?? context.config.defaultScoring ?? "local";
+  if (scoringMode !== "broadcast") {
+    return { scoringMode, partitionIds: context.partitionIds };
+  }
+  return { scoringMode, globalStats: context.broadcastStats?.(context.indexName), partitionIds: context.partitionIds };
+}
+function broadcastStatsForWorker(params, context, scoring) {
+  if (scoring.scoringMode !== "broadcast" || scoring.globalStats === void 0) {
+    return void 0;
+  }
+  const term = params.term;
+  if (term === void 0 || term.trim().length === 0) {
+    return void 0;
+  }
+  return pruneStatsToQueryTerms(scoring.globalStats, term, context.language, context.manager.analysis);
+}
+function searchOptionsFor(manager) {
+  return {
+    bm25Params: manager.config.bm25,
+    stopWords: manager.analysis.stopWords,
+    customTokenizer: manager.analysis.customTokenizer
+  };
+}
+function collectFilterDocIds(manager, params, schema, partitionIds) {
+  const filterDocIds = /* @__PURE__ */ new Set();
+  if (!params.filters) return filterDocIds;
+  for (const partition of partitionsFor(manager, partitionIds)) {
+    const partitionFiltered = partition.applyFilters(params.filters, schema);
+    for (const docId of partitionFiltered) {
+      filterDocIds.add(docId);
+    }
+  }
+  return filterDocIds;
+}
+function vectorResultsToScored(results) {
+  return results.map((r) => ({
+    docId: r.docId,
+    score: r.score,
+    termFrequencies: {},
+    fieldLengths: {},
+    idf: {}
+  }));
+}
+function vectorSearchersOf(context) {
+  return context.vectorSearchers ?? context.manager.getVectorIndexes();
+}
+function resolveVectorIndex(context, fieldName) {
+  return vectorSearchersOf(context).get(fieldName);
+}
+function clampAlpha(alpha) {
+  if (alpha === void 0) return 0.5;
+  if (!Number.isFinite(alpha)) return 0.5;
+  if (alpha < 0) return 0;
+  if (alpha > 1) return 1;
+  return alpha;
+}
+
+// src/engine/query/sorted.ts
+function sortsWithoutScores(params) {
+  return params.includeScores !== true && params.includeScoreComponents !== true && params.minScore === void 0 && params.group === void 0 && params.pinned === void 0 && (params.termMatch === void 0 || params.termMatch === "any");
+}
+function executeSortedQueryPage(params, context, limit, offset, sortSignature) {
+  const { manager, language, config } = context;
+  const schema = config.schema;
+  let anchorKey = null;
+  let anchorId = null;
+  if (params.searchAfter !== void 0) {
+    const decoded = decodePageCursor(params.searchAfter);
+    requireMatchingCursor(decoded, params.searchAfter, sortSignature, true, context.cursorBinding);
+    anchorKey = decoded.sortKey;
+    anchorId = decoded.anchor;
+  }
+  const normalized = normalizeSort(params.sort);
+  const fields = normalized.map((entry) => entry.field);
+  const directions = normalized.map((entry) => entry.direction);
+  const flatSchema = flattenSchema(schema);
+  const fieldTypes = fields.map((field) => flatSchema[field]);
+  const options = searchOptionsFor(manager);
+  const partitions = partitionsFor(manager, context.partitionIds);
+  const partitionLimit = offset + limit + 1;
+  const merged = [];
+  const partitionFacets = [];
+  let count = 0;
+  for (const partition of partitions) {
+    const matches = fulltextMatches(partition, params, language, schema, options);
+    if (params.facets !== void 0) {
+      partitionFacets.push(
+        partition.computeFacets(
+          matches === null ? /* @__PURE__ */ new Set() : { ordinalBitset: matches.ordinalBitset() },
+          params.facets,
+          schema
+        )
+      );
+    }
+    if (matches === null || matches.count === 0) continue;
+    count += matches.count;
+    const page2 = partition.sortedPage({
+      fields,
+      directions,
+      fieldTypes,
+      limit: partitionLimit,
+      anchorKey,
+      anchorId,
+      matches
+    });
+    for (const entry of page2) merged.push(entry);
+  }
+  merged.sort((a, b) => compareComparableKeys(a.key, b.key, directions) || compareCodePoints(a.id, b.id));
+  const hasMore = merged.length > offset + limit;
+  const page = merged.slice(offset, offset + limit);
+  const last = page[page.length - 1];
+  let cursor;
+  if (hasMore && last !== void 0) {
+    cursor = encodePageCursor({
+      anchor: last.id,
+      score: null,
+      sortKey: last.key,
+      sortSignature,
+      binding: context.cursorBinding
+    });
+  }
+  return {
+    hits: page.map((entry) => ({ id: entry.id, document: void 0 })),
+    count,
+    cursor,
+    facets: partitionFacets.length > 0 ? mergeFacets(partitionFacets) : void 0
+  };
+}
+
+// src/search/fusion.ts
+function reciprocalRankFusion(lists, options) {
+  const k = options.k > 0 ? options.k : 60;
+  const scores = /* @__PURE__ */ new Map();
+  const docData = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const doc = list[rank];
+      const rrfContribution = 1 / (k + rank + 1);
+      scores.set(doc.docId, (scores.get(doc.docId) ?? 0) + rrfContribution);
+      if (!docData.has(doc.docId)) {
+        docData.set(doc.docId, doc);
+      }
+    }
+  }
+  const result = [];
+  for (const [docId, score] of scores) {
+    const original = docData.get(docId);
+    if (!original) continue;
+    result.push({
+      docId,
+      score,
+      termFrequencies: original.termFrequencies,
+      fieldLengths: original.fieldLengths,
+      idf: original.idf
+    });
+  }
+  result.sort((a, b) => b.score - a.score || compareCodePoints(a.docId, b.docId));
+  return result;
+}
+function linearCombination(textResults, vectorResults, options) {
+  const { alpha } = options;
+  const normalizedText = minMaxNormalize(textResults);
+  const normalizedVector = minMaxNormalize(vectorResults);
+  const textScoreMap = /* @__PURE__ */ new Map();
+  for (const doc of normalizedText) {
+    textScoreMap.set(doc.docId, doc.score);
+  }
+  const textDocMap = /* @__PURE__ */ new Map();
+  for (const doc of textResults) {
+    textDocMap.set(doc.docId, doc);
+  }
+  const vectorScoreMap = /* @__PURE__ */ new Map();
+  for (const doc of normalizedVector) {
+    vectorScoreMap.set(doc.docId, doc.score);
+  }
+  const allDocIds = /* @__PURE__ */ new Set();
+  for (const doc of textResults) allDocIds.add(doc.docId);
+  for (const doc of vectorResults) allDocIds.add(doc.docId);
+  const result = [];
+  for (const docId of allDocIds) {
+    const tScore = textScoreMap.get(docId) ?? 0;
+    const vScore = vectorScoreMap.get(docId) ?? 0;
+    const combined = alpha * vScore + (1 - alpha) * tScore;
+    const original = textDocMap.get(docId);
+    result.push({
+      docId,
+      score: combined,
+      termFrequencies: original?.termFrequencies ?? {},
+      fieldLengths: original?.fieldLengths ?? {},
+      idf: original?.idf ?? {}
+    });
+  }
+  result.sort((a, b) => b.score - a.score || compareCodePoints(a.docId, b.docId));
+  return result;
+}
+function minMaxNormalize(docs) {
+  if (docs.length === 0) return [];
+  let min = docs[0].score;
+  let max = docs[0].score;
+  for (let i = 1; i < docs.length; i++) {
+    if (docs[i].score < min) min = docs[i].score;
+    if (docs[i].score > max) max = docs[i].score;
+  }
+  const range = max - min;
+  if (range === 0) {
+    return docs.map((d) => ({ docId: d.docId, score: 1 }));
+  }
+  return docs.map((d) => ({ docId: d.docId, score: (d.score - min) / range }));
+}
+
+// src/engine/query/vector.ts
+async function executeVectorSearch(params, context, limit, offset) {
+  const { manager, config, partitionIds } = context;
+  const vectorConfig = params.vector;
+  if (!vectorConfig || !vectorConfig.value) {
+    return { scored: [], totalMatched: 0 };
+  }
+  const vecIndex = resolveVectorIndex(context, vectorConfig.field);
+  if (!vecIndex) {
+    return { scored: [], totalMatched: 0 };
+  }
+  let filterDocIds;
+  let filterPartitions;
+  if (params.filters) {
+    filterDocIds = collectFilterDocIds(manager, params, config.schema, partitionIds);
+    if (filterDocIds.size === 0) {
+      return { scored: [], totalMatched: 0 };
+    }
+  } else {
+    filterPartitions = partitionsForVectorSearch(manager, vecIndex, partitionIds);
+  }
+  const queryVec = new Float32Array(vectorConfig.value);
+  const k = limit + offset + 1;
+  const results = await vecIndex.searchParallel(queryVec, k, {
+    metric: vectorConfig.metric ?? "cosine",
+    minSimilarity: vectorConfig.similarity ?? -Infinity,
+    ...filterDocIds !== void 0 ? { filterDocIds } : {},
+    ...filterPartitions !== void 0 ? { filterPartitions } : {},
+    efSearch: vectorConfig.efSearch
+  });
+  const scored = vectorResultsToScored(results);
+  return { scored, totalMatched: scored.length };
+}
+async function textLeg(textOnlyParams, context) {
+  const { manager, language, config, workerSearch, indexName } = context;
+  const scoring = scoringConfigFor(textOnlyParams, context);
+  if (workerSearch) {
+    const viaWorker = await workerSearch(
+      indexName,
+      textOnlyParams,
+      broadcastStatsForWorker(textOnlyParams, context, scoring),
+      context.partitionIds
+    );
+    if (viaWorker) return viaWorker;
+  }
+  return fanOutQuery(manager, textOnlyParams, language, config.schema, scoring, searchOptionsFor(manager));
+}
+async function vectorLeg(vectorConfig, queryVector, context, filterDocIds, k) {
+  const { manager } = context;
+  const vecIndex = resolveVectorIndex(context, vectorConfig.field);
+  if (!vecIndex) return [];
+  const filterPartitions = filterDocIds === void 0 ? partitionsForVectorSearch(manager, vecIndex, context.partitionIds) : void 0;
+  const results = await vecIndex.searchParallel(queryVector, k, {
+    metric: vectorConfig.metric ?? "cosine",
+    minSimilarity: vectorConfig.similarity ?? -Infinity,
+    ...filterDocIds !== void 0 ? { filterDocIds } : {},
+    ...filterPartitions !== void 0 ? { filterPartitions } : {},
+    efSearch: vectorConfig.efSearch
+  });
+  return vectorResultsToScored(results);
+}
+async function executeHybridSearch(params, context, limit, offset) {
+  const { manager, config } = context;
+  const { vector: vectorConfig, mode: _mode, hybrid: _hybrid, ...textOnlyParams } = params;
+  let filterDocIds;
+  if (params.filters) {
+    filterDocIds = collectFilterDocIds(manager, params, config.schema, context.partitionIds);
+    if (filterDocIds.size === 0) {
+      return { scored: [], totalMatched: 0 };
+    }
+  }
+  if (!vectorConfig || !vectorConfig.value) {
+    const textOnly = await textLeg(textOnlyParams, context);
+    return { scored: textOnly.scored, totalMatched: textOnly.totalMatched, facets: textOnly.facets };
+  }
+  const vectorPending = vectorLeg(
+    vectorConfig,
+    new Float32Array(vectorConfig.value),
+    context,
+    filterDocIds,
+    limit + offset + 1
+  );
+  const [textFanOutResult, vectorScored] = await Promise.all([textLeg(textOnlyParams, context), vectorPending]);
+  const hybridConfig = params.hybrid ?? {};
+  const strategy = hybridConfig.strategy ?? "rrf";
+  let fusedScored;
+  if (strategy === "rrf") {
+    const rrfK = hybridConfig.k !== void 0 && hybridConfig.k > 0 ? hybridConfig.k : 60;
+    fusedScored = reciprocalRankFusion([textFanOutResult.scored, vectorScored], { k: rrfK });
+  } else {
+    const alpha = clampAlpha(hybridConfig.alpha);
+    fusedScored = linearCombination(textFanOutResult.scored, vectorScored, { alpha });
+  }
+  if (params.minScore !== void 0 && params.minScore > 0) {
+    const threshold = params.minScore;
+    fusedScored = fusedScored.filter((doc) => doc.score >= threshold);
+  }
+  return {
+    scored: fusedScored,
+    totalMatched: fusedScored.length,
+    facets: textFanOutResult.facets
+  };
+}
+
+// src/engine/query/index.ts
+async function executeQuery(params, context) {
+  const { manager, language, config, workerSearch, indexName } = context;
+  const startTime = now();
+  const limit = clampLimit(params.limit);
+  const offset = clampOffset(params.offset);
+  requireWithinResultWindow(limit, offset);
+  const sortFields = normalizeSort(params.sort);
+  const sortSignature = sortSignatureOf(params.sort);
+  const hasTerm = params.term !== void 0 && params.term.trim().length > 0;
+  const hasVector = params.vector !== void 0 && params.vector.value !== void 0;
+  const isHybridMode = params.mode === "hybrid" || hasTerm && hasVector;
+  const isVectorOnly = (params.mode === "vector" || hasVector && !hasTerm) && !isHybridMode;
+  if (sortSignature !== null && (isHybridMode || params.hybrid !== void 0)) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_MODE,
+      "A hybrid query cannot carry a sort, because fusion defines the order of hybrid results",
+      { sort: sortFields.map((entry) => entry.field) }
+    );
+  }
+  requireSortableFields(params.sort, config.schema);
+  let paginated;
+  let nextCursor;
+  let count;
+  let facets;
+  let groups;
+  if (sortSignature !== null && hasTerm && !isVectorOnly && !isHybridMode && sortsWithoutScores(params)) {
+    const page = executeSortedQueryPage(params, context, limit, offset, sortSignature);
+    paginated = page.hits;
+    nextCursor = page.cursor;
+    count = page.count;
+    facets = page.facets;
+  } else {
+    const requestedVectorField = params.vector?.field;
+    const hasGlobalVectorIndex = requestedVectorField !== void 0 && vectorSearchersOf(context).has(requestedVectorField);
+    let fanOutResult;
+    if (isVectorOnly && hasGlobalVectorIndex) {
+      fanOutResult = await executeVectorSearch(params, context, limit, offset);
+    } else if (isHybridMode && hasGlobalVectorIndex) {
+      fanOutResult = await executeHybridSearch(params, context, limit, offset);
+    } else {
+      const scoring = scoringConfigFor(params, context);
+      const workerResult = workerSearch ? await workerSearch(indexName, params, broadcastStatsForWorker(params, context, scoring), context.partitionIds) : null;
+      if (workerResult) {
+        fanOutResult = workerResult;
+      } else {
+        fanOutResult = await fanOutQuery(manager, params, language, config.schema, scoring, searchOptionsFor(manager));
+      }
+    }
+    const needsFullHits = params.sort !== void 0 || params.group !== void 0 || params.pinned !== void 0 || params.searchAfter !== void 0;
+    let hits;
+    if (needsFullHits) {
+      hits = fanOutResult.scored.map((scored) => ({
+        id: scored.docId,
+        score: scored.score,
+        document: void 0,
+        scoreComponents: params.includeScoreComponents ? { termFrequencies: scored.termFrequencies, fieldLengths: scored.fieldLengths, idf: scored.idf } : void 0
+      }));
+    } else {
+      const end = Math.min(offset + limit + 1, fanOutResult.scored.length);
+      hits = new Array(end);
+      for (let i = 0; i < end; i++) {
+        const scored = fanOutResult.scored[i];
+        hits[i] = {
+          id: scored.docId,
+          score: scored.score,
+          document: void 0,
+          scoreComponents: params.includeScoreComponents ? { termFrequencies: scored.termFrequencies, fieldLengths: scored.fieldLengths, idf: scored.idf } : void 0
+        };
+      }
+    }
+    const sortFieldNames = sortFields.map((entry) => entry.field);
+    const sortFlatSchema = sortFieldNames.length === 0 ? {} : flattenSchema(config.schema);
+    const sortFieldTypes = sortFieldNames.map((field) => sortFlatSchema[field]);
+    const sortKeyCache = /* @__PURE__ */ new Map();
+    const sortKeyOf = (docId) => {
+      let key = sortKeyCache.get(docId);
+      if (key === void 0) {
+        key = manager.sortValues(docId, sortFieldNames, sortFieldTypes);
+        sortKeyCache.set(docId, key);
+      }
+      return key;
+    };
+    if (params.sort) {
+      hits = applySorting(hits, params.sort, sortKeyOf);
+    }
+    if (params.group) {
+      groups = applyGrouping(hits, params.group, (docId) => manager.getRef(docId));
+    }
+    if (params.pinned && params.searchAfter === void 0 && context.partitionIds === void 0) {
+      hits = applyPinning(hits, params.pinned, (docId) => {
+        const doc = manager.getRef(docId);
+        if (!doc) return void 0;
+        return { id: docId, score: 0, document: doc };
+      });
+    }
+    let sortContext;
+    if (sortSignature !== null) {
+      sortContext = {
+        signature: sortSignature,
+        directions: sortFields.map((entry) => entry.direction),
+        sortKeyOf
+      };
+    }
+    const pinnedIds = params.pinned !== void 0 && params.searchAfter === void 0 ? new Set(params.pinned.map((entry) => entry.docId)) : void 0;
+    const paged = applyPagination(
+      hits,
+      limit,
+      offset,
+      context.cursorBinding,
+      params.searchAfter,
+      sortContext,
+      pinnedIds
+    );
+    paginated = paged.paginated;
+    nextCursor = paged.nextCursor;
+    count = fanOutResult.totalMatched;
+    facets = fanOutResult.facets;
+    if (sortSignature !== null && params.includeScores !== true) {
+      for (const hit of hits) hit.score = void 0;
+    }
+  }
+  const projection = resolveProjection(params.document);
+  if (projection.kind === "none") {
+    for (const hit of paginated) {
+      hit.document = {};
+    }
+  } else {
+    for (const hit of paginated) {
+      hit.document = manager.get(hit.id, projection) ?? {};
+    }
+  }
+  if (groups) {
+    for (const group of groups) {
+      for (const hit of group.hits) {
+        if (projection.kind === "none") {
+          hit.document = {};
+          continue;
+        }
+        hit.document = manager.get(hit.id, projection) ?? {};
+      }
+    }
+  }
+  if (params.highlight) {
+    applyHighlights(paginated, params, language, manager.analysis);
+  }
+  const elapsed = now() - startTime;
+  return {
+    hits: paginated,
+    count,
+    elapsed,
+    cursor: nextCursor,
+    facets,
+    groups,
+    coverage: coverageFor(manager, context.partitionIds)
+  };
+}
+async function executePreflight(params, context) {
+  const { manager, language, config, workerSearch, indexName } = context;
+  const startTime = now();
+  const hasTerm = params.term !== void 0 && params.term.trim().length > 0;
+  const hasVector = params.vector !== void 0 && params.vector.value !== void 0;
+  const isHybridMode = params.mode === "hybrid" || hasTerm && hasVector;
+  const isVectorOnly = (params.mode === "vector" || hasVector && !hasTerm) && !isHybridMode;
+  const requestedVectorField = params.vector?.field;
+  const hasGlobalVectorIndex = requestedVectorField !== void 0 && vectorSearchersOf(context).has(requestedVectorField);
+  let totalMatched;
+  const preflightLimit = 1e3;
+  const preflightOffset = 0;
+  if (isVectorOnly && hasGlobalVectorIndex) {
+    const result = await executeVectorSearch(params, context, preflightLimit, preflightOffset);
+    totalMatched = result.totalMatched;
+  } else if (isHybridMode && hasGlobalVectorIndex) {
+    const result = await executeHybridSearch(params, context, preflightLimit, preflightOffset);
+    totalMatched = result.totalMatched;
+  } else if (countsWithoutScores(params)) {
+    totalMatched = fanOutMatchCount(manager, params, language, config.schema, {
+      searchOptions: searchOptionsFor(manager),
+      partitionIds: context.partitionIds
+    });
+  } else {
+    const scoring = scoringConfigFor(params, context);
+    const workerResult = workerSearch ? await workerSearch(indexName, params, broadcastStatsForWorker(params, context, scoring), context.partitionIds) : null;
+    if (workerResult) {
+      totalMatched = workerResult.totalMatched;
+    } else {
+      const fanOutResult = await fanOutQuery(
+        manager,
+        params,
+        language,
+        config.schema,
+        scoring,
+        searchOptionsFor(manager)
+      );
+      totalMatched = fanOutResult.totalMatched;
+    }
+  }
+  const elapsed = now() - startTime;
+  return { count: totalMatched, elapsed };
+}
+
+// src/engine/suggest.ts
+function executeSuggest(manager, language, params, partitionIds) {
+  const t0 = performance.now();
+  const ceiling = partitionIds === void 0 ? MAX_SUGGEST_LIMIT : MAX_SUGGEST_SCATTER_LIMIT;
+  const limit = Math.max(1, Math.min(clampRowCount(params.limit, DEFAULT_SUGGEST_LIMIT), ceiling));
+  const rawPrefix = params.prefix.trim();
+  if (rawPrefix.length === 0) {
+    return { terms: [], elapsed: performance.now() - t0 };
+  }
+  const unstemmed = tokenize(rawPrefix, language, { stem: false, removeStopWords: false });
+  const lastToken = unstemmed.tokens.length > 0 ? unstemmed.tokens[unstemmed.tokens.length - 1].token : rawPrefix.toLowerCase();
+  if (lastToken.length === 0) {
+    return { terms: [], elapsed: performance.now() - t0 };
+  }
+  const stemmed = language.stemmer ? language.stemmer(lastToken) : lastToken;
+  const merged = /* @__PURE__ */ new Map();
+  const perPartitionLimit = limit * 2;
+  const partitions = partitionIds === void 0 ? manager.getAllPartitions() : partitionIds.map((partitionId) => manager.partitionAt(partitionId)).filter((partition) => partition !== void 0);
+  for (const partition of partitions) {
+    for (const suggestion of partition.suggestTerms(lastToken, stemmed, perPartitionLimit)) {
+      let entry = merged.get(suggestion.token);
+      if (!entry) {
+        entry = { documentFrequency: 0, surfaceOccurrences: /* @__PURE__ */ new Map() };
+        merged.set(suggestion.token, entry);
+      }
+      entry.documentFrequency += suggestion.documentFrequency;
+      for (const s of suggestion.surfaces) {
+        entry.surfaceOccurrences.set(s.surface, (entry.surfaceOccurrences.get(s.surface) ?? 0) + s.occurrences);
+      }
+    }
+  }
+  const terms = Array.from(merged.values()).map((entry) => ({ term: pickDisplaySurface(entry.surfaceOccurrences), documentFrequency: entry.documentFrequency })).sort((a, b) => b.documentFrequency - a.documentFrequency || compareCodePoints(a.term, b.term));
+  if (terms.length > limit) terms.length = limit;
+  return { terms, elapsed: performance.now() - t0 };
+}
+function pickDisplaySurface(surfaceOccurrences) {
+  let best = "";
+  let bestCount = -1;
+  for (const [surface, occurrences] of surfaceOccurrences) {
+    if (occurrences > bestCount || occurrences === bestCount && compareCodePoints(surface, best) < 0) {
+      best = surface;
+      bestCount = occurrences;
+    }
+  }
+  return best;
+}
+
+export { clampLimit, dedupePinnedEntries, executeListDocuments, executePreflight, executeQuery, executeSuggest, foldGroupReducer, listBindingOf, now, queryBindingOf, validateBM25Params, validateDocId, validateIndexName, validatePartitionConfig, validateWorkerConfig };