@delali/narsil 0.2.4-next.55 → 0.3.0

package/dist/{chunk-TVT5V4E7.mjs → chunk-B2TFROFX.mjs}

@@ -1,9 +1,9 @@
-import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, DEFAULT_LIMIT, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, ABSOLUTE_WINDOWS_PATH_PATTERN, MODULE_URL_SCHEME_PATTERN, DEFAULT_OFFSET } from './chunk-D2S642IV.mjs';
-import { clampRowCount, sortSignatureOf, requireSortableFields, decodePageCursor, requireMatchingCursor, resolveProjection, encodePageCursor, requireWithinResultWindow, normalizeSort, fanOutQuery, applySorting, applyPagination, projectionKeepsField, countsWithoutScores, fanOutMatchCount, tokenize, fnv1aBytes, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, partitionsIn } from './chunk-5T6AOR37.mjs';
-import { flattenSchema } from './chunk-L225SHNB.mjs';
+import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, DEFAULT_LIMIT, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, ABSOLUTE_WINDOWS_PATH_PATTERN, MODULE_URL_SCHEME_PATTERN, DEFAULT_OFFSET } from './chunk-3LHGNRYE.mjs';
+import { clampRowCount, sortSignatureOf, requireSortableFields, decodePageCursor, requireMatchingCursor, resolveProjection, encodePageCursor, requireWithinResultWindow, normalizeSort, fanOutQuery, sortModesOf, applySorting, applyPagination, projectionKeepsField, countsWithoutScores, fanOutMatchCount, tokenize, fnv1aBytes, requireValidFilter, everyValueFacetConfig, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, partitionsIn, undeclaredFieldOnStrictIndex, fuzzyTermMatches } from './chunk-ZNZBXMP5.mjs';
+import { DEFAULT_MAX_PER_GROUP, flattenSchema, DEFAULT_LINEAR_ALPHA, MIN_LINEAR_ALPHA, MAX_LINEAR_ALPHA, DEFAULT_RANK_CONSTANT, MIN_RANK_CONSTANT, DEFAULT_FUZZY_PREFIX_LENGTH, RESULT_WINDOW, isTextFieldType, isGeopointOrVectorType } from './chunk-L6TNPLAR.mjs';
 import { MIN_OVERSAMPLE } from './chunk-ZJ4CSAB2.mjs';
-import { compareCodePoints, compareComparableKeys } from './chunk-2GWVQWGA.mjs';
-import { NarsilError, ErrorCodes } from './chunk-FRQVMFY7.mjs';
+import { compareCodePoints, compareComparableKeys } from './chunk-YMZCMH5M.mjs';
+import { NarsilError, ErrorCodes } from './chunk-USKFU7J5.mjs';
 
 // src/search/cursor-binding.ts
 var ABSENT_TAG = 0;
@@ -163,6 +163,169 @@ function listBindingOf(filters) {
   return bindingOf(values);
 }
 
+// src/search/query-fields.ts
+function requireBoostableFields(boost, flatSchema) {
+  for (const [field, weight] of Object.entries(boost)) {
+    const fieldType = flatSchema[field];
+    if (fieldType === void 0 || !isTextFieldType(fieldType) && fieldType !== "string[]") {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_FIELD,
+        fieldType === void 0 ? `The engine boosts a text field that the schema declares, and the schema declares no field "${field}"` : `The engine boosts a text field alone, and the schema declares field "${field}" as "${fieldType}"`,
+        { field, ...fieldType === void 0 ? {} : { fieldType } }
+      );
+    }
+    if (typeof weight !== "number" || !Number.isFinite(weight)) {
+      throw new NarsilError(
+        ErrorCodes.CONFIG_INVALID,
+        `The boost on field "${field}" must be a finite number, and this query sets ${String(weight)}`,
+        { field, boost: String(weight) }
+      );
+    }
+  }
+}
+function requireFacetableFields(facets, flatSchema, strict) {
+  for (const field of Object.keys(facets)) {
+    const fieldType = flatSchema[field];
+    if (strict && fieldType === void 0) throw undeclaredFieldOnStrictIndex(field, "facet");
+    if (isGeopointOrVectorType(fieldType)) {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_FIELD,
+        `The engine counts the values of a text, number, boolean, or enum field, and the schema declares field "${field}" as "${fieldType}"`,
+        { field, fieldType }
+      );
+    }
+  }
+}
+function requireDeclaredGroupFields(fields, flatSchema) {
+  for (const field of fields) {
+    if (flatSchema[field] === void 0) throw undeclaredFieldOnStrictIndex(field, "group");
+  }
+}
+function requireUsableQueryFields(params, schema, strict = false) {
+  const checksGroup = strict && Array.isArray(params.group?.fields);
+  if (params.boost === void 0 && params.facets === void 0 && !checksGroup) return;
+  const flatSchema = flattenSchema(schema);
+  if (params.boost !== void 0) requireBoostableFields(params.boost, flatSchema);
+  if (params.facets !== void 0) requireFacetableFields(params.facets, flatSchema, strict);
+  if (checksGroup && params.group !== void 0) requireDeclaredGroupFields(params.group.fields, flatSchema);
+}
+
+// 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);
+}
+var SEARCH_MODES = /* @__PURE__ */ new Set(["fulltext", "vector", "hybrid"]);
+function requireKnownMode(params) {
+  if (params.mode === void 0 || SEARCH_MODES.has(params.mode)) return;
+  throw new NarsilError(
+    ErrorCodes.SEARCH_INVALID_MODE,
+    `A search takes the mode "fulltext", "vector", or "hybrid", while this query names "${String(params.mode)}"`,
+    { mode: String(params.mode), modes: [...SEARCH_MODES] }
+  );
+}
+function requireValidQueryOptions(params, config) {
+  const strict = config.strict === true;
+  requireSortableFields(params.sort, config.schema, strict);
+  requireValidQueryFilter(params.filters, config.schema, strict);
+  requireUsableQueryFields(params, config.schema, strict);
+}
+function requireValidQueryFilter(filters, schema, strict = false) {
+  if (filters !== void 0) requireValidFilter(filters, flattenSchema(schema), strict);
+}
+function requireVectorSearchable(params, context, needsVector) {
+  if (!needsVector) return;
+  const field = params.vector?.field;
+  if (field === void 0) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_MODE,
+      `A "${params.mode}" query needs a vector clause naming the field to search`,
+      { mode: params.mode }
+    );
+  }
+  if (vectorSearchersOf(context).has(field)) return;
+  throw new NarsilError(
+    ErrorCodes.SEARCH_INVALID_FIELD,
+    `Field "${field}" has no vector index, so a vector search cannot use it`,
+    { field, vectorFields: [...vectorSearchersOf(context).keys()] }
+  );
+}
+
 // src/engine/validation.ts
 function now() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
@@ -351,6 +514,7 @@ function pageInSortOrder(partitions, cursor, filtered, limit, sort, signature, s
     fields,
     directions,
     fieldTypes,
+    modes: sortModesOf(normalized),
     limit: limit + 1,
     anchorKey: cursor === null ? null : cursor.sortKey,
     anchorId: cursor === null ? null : cursor.anchor
@@ -382,7 +546,8 @@ function executeListDocuments(params, context) {
   const startTime = now();
   const limit = clampListLimit(params.limit);
   const signature = sortSignatureOf(params.sort);
-  requireSortableFields(params.sort, schema);
+  requireSortableFields(params.sort, schema, context.strict === true);
+  requireValidQueryFilter(params.filters, schema, context.strict === true);
   const binding = listBindingOf(params.filters);
   let cursor = null;
   if (params.cursor !== void 0) {
@@ -430,6 +595,10 @@ function getNestedValue(obj, path) {
   }
   return current;
 }
+function hitsKeptPerGroup(maxPerGroup) {
+  if (maxPerGroup === void 0 || !Number.isFinite(maxPerGroup) || maxPerGroup < 1) return DEFAULT_MAX_PER_GROUP;
+  return Math.floor(maxPerGroup);
+}
 function applyGrouping(hits, group, getDocument) {
   if (!group.fields || group.fields.length === 0) {
     return [{ values: {}, hits }];
@@ -453,16 +622,14 @@ function applyGrouping(hits, group, getDocument) {
     }
   }
   const groups = [];
+  const keptPerGroup = hitsKeptPerGroup(group.maxPerGroup);
   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 };
+    const everyHit = entry.hits;
+    const result = { values: entry.values, hits: everyHit.slice(0, keptPerGroup) };
     if (group.reduce) {
       const folded = foldGroupReducer(
         group.reduce,
-        groupHits.map((hit) => ({ document: getDocument(hit.id), score: hit.score ?? 0 }))
+        everyHit.map((hit) => ({ document: getDocument(hit.id), score: hit.score ?? 0 }))
       );
       if (folded.reducerError !== void 0) {
         result.reducerError = folded.reducerError;
@@ -513,23 +680,27 @@ function dedupePinnedEntries(pinned) {
   }
   return deduped;
 }
-function applyPinning(hits, pinned, resolveDoc) {
+function placePinned(hits, pinned, resolveDoc) {
   const result = hits.slice();
   const deduped = dedupePinnedEntries(pinned);
   const pinnedDocIds = new Set(deduped.map((entry) => entry.docId));
+  const listedPins = /* @__PURE__ */ new Set();
   for (let i = result.length - 1; i >= 0; i--) {
     if (pinnedDocIds.has(result[i].id)) {
+      listedPins.add(result[i].id);
       result.splice(i, 1);
     }
   }
   const sorted = deduped.sort((a, b) => a.position - b.position);
+  let placedFromOutside = 0;
   for (const entry of sorted) {
     const doc = resolveDoc(entry.docId);
     if (!doc) continue;
+    if (!listedPins.has(entry.docId)) placedFromOutside++;
     const pos = Math.max(0, Math.min(entry.position, result.length));
     result.splice(pos, 0, doc);
   }
-  return result;
+  return { hits: result, placedFromOutside };
 }
 
 // src/highlighting/highlighter.ts
@@ -627,19 +798,25 @@ function highlightField(text, queryTokens, language, options) {
   });
   const matchedRanges = [];
   const prefixToken = options?.prefixToken;
+  const tolerance = options?.tolerance ?? 0;
+  const prefixLength = options?.prefixLength ?? 0;
+  const matchByFieldToken = /* @__PURE__ */ new Map();
+  const matchesQuery = (fieldToken) => {
+    const known = matchByFieldToken.get(fieldToken);
+    if (known !== void 0) return known;
+    const stemmedField = language.stemmer ? language.stemmer(fieldToken) : fieldToken;
+    const matches = stemmedQueryTokens.some(
+      (stemmedQuery) => fuzzyTermMatches(stemmedQuery, stemmedField, tolerance, prefixLength)
+    );
+    matchByFieldToken.set(fieldToken, matches);
+    return matches;
+  };
   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)) {
+    const prefixMatch = prefixToken !== void 0 && fieldToken.startsWith(prefixToken);
+    if (prefixMatch || matchesQuery(fieldToken)) {
       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);
@@ -709,7 +886,9 @@ function applyHighlights(hits, params, language, analysis, readStoredDocument) {
           preTag: params.highlight.preTag,
           postTag: params.highlight.postTag,
           maxSnippetLength: params.highlight.maxSnippetLength,
-          prefixToken
+          prefixToken,
+          tolerance: params.exact === true ? 0 : params.tolerance ?? 0,
+          prefixLength: params.prefixLength ?? DEFAULT_FUZZY_PREFIX_LENGTH
         });
       }
     }
@@ -717,120 +896,6 @@ function applyHighlights(hits, params, language, analysis, readStoredDocument) {
   }
 }
 
-// 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);
-}
-var SEARCH_MODES = /* @__PURE__ */ new Set(["fulltext", "vector", "hybrid"]);
-function requireKnownMode(params) {
-  if (params.mode === void 0 || SEARCH_MODES.has(params.mode)) return;
-  throw new NarsilError(
-    ErrorCodes.SEARCH_INVALID_MODE,
-    `A search takes the mode "fulltext", "vector", or "hybrid", while this query names "${String(params.mode)}"`,
-    { mode: String(params.mode), modes: [...SEARCH_MODES] }
-  );
-}
-function requireVectorSearchable(params, context, needsVector) {
-  if (!needsVector) return;
-  const field = params.vector?.field;
-  if (field === void 0) {
-    throw new NarsilError(
-      ErrorCodes.SEARCH_INVALID_MODE,
-      `A "${params.mode}" query needs a vector clause naming the field to search`,
-      { mode: params.mode }
-    );
-  }
-  if (vectorSearchersOf(context).has(field)) return;
-  throw new NarsilError(
-    ErrorCodes.SEARCH_INVALID_FIELD,
-    `Field "${field}" has no vector index, so a vector search cannot use it`,
-    { field, vectorFields: [...vectorSearchersOf(context).keys()] }
-  );
-}
-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");
@@ -851,19 +916,21 @@ function executeSortedQueryPage(params, context, limit, offset, sortSignature) {
   const directions = normalized.map((entry) => entry.direction);
   const flatSchema = flattenSchema(schema);
   const fieldTypes = fields.map((field) => flatSchema[field]);
+  const modes = sortModesOf(normalized);
   const options = searchOptionsFor(manager);
   const partitions = partitionsFor(manager, context.partitionIds);
   const partitionLimit = offset + limit + 1;
   const merged = [];
   const partitionFacets = [];
+  const partitionFacetConfig = params.facets !== void 0 && partitions.length > 1 ? everyValueFacetConfig(params.facets) : params.facets;
   let count = 0;
   for (const partition of partitions) {
     const matches = fulltextMatches(partition, params, language, schema, options);
-    if (params.facets !== void 0) {
+    if (partitionFacetConfig !== void 0) {
       partitionFacets.push(
         partition.computeFacets(
           matches === null ? /* @__PURE__ */ new Set() : { ordinalBitset: matches.ordinalBitset() },
-          params.facets,
+          partitionFacetConfig,
           schema
         )
       );
@@ -874,6 +941,7 @@ function executeSortedQueryPage(params, context, limit, offset, sortSignature) {
       fields,
       directions,
       fieldTypes,
+      modes,
       limit: partitionLimit,
       anchorKey,
       anchorId,
@@ -899,13 +967,42 @@ function executeSortedQueryPage(params, context, limit, offset, sortSignature) {
     hits: page.map((entry) => ({ id: entry.id, document: void 0 })),
     count,
     cursor,
-    facets: partitionFacets.length > 0 ? mergeFacets(partitionFacets) : void 0
+    facets: params.facets !== void 0 && partitionFacets.length > 0 ? mergeFacets(partitionFacets, params.facets) : void 0
   };
 }
 
 // src/search/fusion.ts
+function rankConstantOf(k) {
+  if (k === void 0 || k === null) return DEFAULT_RANK_CONSTANT;
+  if (!Number.isInteger(k) || k < MIN_RANK_CONSTANT) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      `hybrid.k must be a whole number of at least ${MIN_RANK_CONSTANT}`,
+      { k }
+    );
+  }
+  return k;
+}
+function linearAlphaOf(alpha) {
+  if (alpha === void 0 || alpha === null) return DEFAULT_LINEAR_ALPHA;
+  if (!Number.isFinite(alpha) || alpha < MIN_LINEAR_ALPHA || alpha > MAX_LINEAR_ALPHA) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      `hybrid.alpha must be a number from ${MIN_LINEAR_ALPHA} to ${MAX_LINEAR_ALPHA}`,
+      { alpha }
+    );
+  }
+  return alpha;
+}
+function resolveHybridFusion(hybrid) {
+  const strategy = hybrid?.strategy ?? "rrf";
+  if (strategy !== "rrf" && strategy !== "linear") {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, `hybrid.strategy must be "rrf" or "linear"`, { strategy });
+  }
+  return { strategy, k: rankConstantOf(hybrid?.k), alpha: linearAlphaOf(hybrid?.alpha) };
+}
 function reciprocalRankFusion(lists, options) {
-  const k = options.k > 0 ? options.k : 60;
+  const k = options.k;
   const scores = /* @__PURE__ */ new Map();
   const docData = /* @__PURE__ */ new Map();
   for (const list of lists) {
@@ -997,7 +1094,18 @@ function oversampleOf(vectorConfig) {
   }
   return oversample;
 }
-async function executeVectorSearch(params, context, limit, offset) {
+function vectorFetchDepth(limit, offset, cursorDepth) {
+  const reach = cursorDepth + offset + limit;
+  if (reach > RESULT_WINDOW) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_RESULT_WINDOW_EXCEEDED,
+      `The engine pages a vector search through the first ${RESULT_WINDOW} results, and this page ends at ${reach}. Narrow the search with a filter or a similarity floor`,
+      { limit, offset, cursorDepth, window: RESULT_WINDOW }
+    );
+  }
+  return Math.min(reach + 1, RESULT_WINDOW);
+}
+async function executeVectorSearch(params, context, limit, offset, cursorDepth = 0) {
   const { manager, config, partitionIds } = context;
   const vectorConfig = params.vector;
   if (!vectorConfig || !vectorConfig.value) {
@@ -1018,8 +1126,8 @@ async function executeVectorSearch(params, context, limit, offset) {
     filterPartitions = partitionsForVectorSearch(manager, vecIndex, partitionIds);
   }
   const queryVec = new Float32Array(vectorConfig.value);
-  const k = limit + offset + 1;
-  const results = await vecIndex.searchParallel(queryVec, k, {
+  const k = vectorFetchDepth(limit, offset, cursorDepth);
+  const outcome = await vecIndex.searchParallel(queryVec, k, {
     metric: vectorConfig.metric ?? "cosine",
     minSimilarity: vectorConfig.similarity ?? -Infinity,
     ...filterDocIds !== void 0 ? { filterDocIds } : {},
@@ -1027,8 +1135,8 @@ async function executeVectorSearch(params, context, limit, offset) {
     efSearch: vectorConfig.efSearch,
     oversample: oversampleOf(vectorConfig)
   });
-  const scored = vectorResultsToScored(results);
-  return { scored, totalMatched: scored.length };
+  const scored = vectorResultsToScored(outcome.results);
+  return { scored, totalMatched: outcome.matched, matchedExact: outcome.matchedExact };
 }
 async function textLeg(textOnlyParams, context) {
   const { manager, language, config, workerSearch, indexName } = context;
@@ -1047,9 +1155,9 @@ async function textLeg(textOnlyParams, context) {
 async function vectorLeg(vectorConfig, queryVector, context, filterDocIds, k) {
   const { manager } = context;
   const vecIndex = resolveVectorIndex(context, vectorConfig.field);
-  if (!vecIndex) return [];
+  if (!vecIndex) return { scored: [], holdsEveryMatch: true };
   const filterPartitions = filterDocIds === void 0 ? partitionsForVectorSearch(manager, vecIndex, context.partitionIds) : void 0;
-  const results = await vecIndex.searchParallel(queryVector, k, {
+  const outcome = await vecIndex.searchParallel(queryVector, k, {
     metric: vectorConfig.metric ?? "cosine",
     minSimilarity: vectorConfig.similarity ?? -Infinity,
     ...filterDocIds !== void 0 ? { filterDocIds } : {},
@@ -1057,11 +1165,15 @@ async function vectorLeg(vectorConfig, queryVector, context, filterDocIds, k) {
     efSearch: vectorConfig.efSearch,
     oversample: oversampleOf(vectorConfig)
   });
-  return vectorResultsToScored(results);
+  return {
+    scored: vectorResultsToScored(outcome.results),
+    holdsEveryMatch: outcome.matchedExact && outcome.results.length === outcome.matched
+  };
 }
-async function executeHybridSearch(params, context, limit, offset) {
+async function executeHybridSearch(params, context, limit, offset, cursorDepth = 0) {
   const { manager, config } = context;
   const { vector: vectorConfig, mode: _mode, hybrid: _hybrid, ...textOnlyParams } = params;
+  const fusion = resolveHybridFusion(params.hybrid);
   let filterDocIds;
   if (params.filters) {
     filterDocIds = collectFilterDocIds(manager, params, config.schema, context.partitionIds);
@@ -1078,31 +1190,36 @@ async function executeHybridSearch(params, context, limit, offset) {
     new Float32Array(vectorConfig.value),
     context,
     filterDocIds,
-    limit + offset + 1
+    vectorFetchDepth(limit, offset, cursorDepth)
   );
-  const [textFanOutResult, vectorScored] = await Promise.all([textLeg(textOnlyParams, context), vectorPending]);
-  const hybridConfig = params.hybrid ?? {};
-  const strategy = hybridConfig.strategy ?? "rrf";
+  const [textFanOutResult, vectorOutcome] = await Promise.all([textLeg(textOnlyParams, context), vectorPending]);
+  const vectorScored = vectorOutcome.scored;
   let fusedScored;
-  if (strategy === "rrf") {
-    const rrfK = hybridConfig.k !== void 0 && hybridConfig.k > 0 ? hybridConfig.k : 60;
-    fusedScored = reciprocalRankFusion([textFanOutResult.scored, vectorScored], { k: rrfK });
+  if (fusion.strategy === "rrf") {
+    fusedScored = reciprocalRankFusion([textFanOutResult.scored, vectorScored], { k: fusion.k });
   } else {
-    const alpha = clampAlpha(hybridConfig.alpha);
-    fusedScored = linearCombination(textFanOutResult.scored, vectorScored, { alpha });
+    fusedScored = linearCombination(textFanOutResult.scored, vectorScored, { alpha: fusion.alpha });
   }
   if (params.minScore !== void 0 && params.minScore > 0) {
     const threshold = params.minScore;
     fusedScored = fusedScored.filter((doc) => doc.score >= threshold);
   }
+  const textHoldsEveryMatch = textFanOutResult.scored.length === textFanOutResult.totalMatched;
   return {
     scored: fusedScored,
     totalMatched: fusedScored.length,
+    matchedExact: vectorOutcome.holdsEveryMatch && textHoldsEveryMatch,
     facets: textFanOutResult.facets
   };
 }
 
 // src/engine/query/index.ts
+function requireCursorDepth(cursor, signature, binding) {
+  if (cursor === void 0) return 0;
+  const decoded = decodePageCursor(cursor);
+  requireMatchingCursor(decoded, cursor, signature, true, binding);
+  return decoded.depth ?? 0;
+}
 async function executeQuery(params, context) {
   const { manager, language, config, workerSearch, indexName } = context;
   const startTime = now();
@@ -1123,11 +1240,12 @@ async function executeQuery(params, context) {
       { sort: sortFields.map((entry) => entry.field) }
     );
   }
-  requireSortableFields(params.sort, config.schema);
+  requireValidQueryOptions(params, config);
   requireVectorSearchable(params, context, isVectorOnly || isHybridMode);
   let paginated;
   let nextCursor;
   let count;
+  let countExact = true;
   let facets;
   let groups;
   if (sortSignature !== null && hasTerm && !isVectorOnly && !isHybridMode && sortsWithoutScores(params)) {
@@ -1141,9 +1259,11 @@ async function executeQuery(params, context) {
     const hasGlobalVectorIndex = requestedVectorField !== void 0 && vectorSearchersOf(context).has(requestedVectorField);
     let fanOutResult;
     if (isVectorOnly && hasGlobalVectorIndex) {
-      fanOutResult = await executeVectorSearch(params, context, limit, offset);
+      const depth = requireCursorDepth(params.searchAfter, sortSignature, context.cursorBinding);
+      fanOutResult = await executeVectorSearch(params, context, limit, offset, depth);
     } else if (isHybridMode && hasGlobalVectorIndex) {
-      fanOutResult = await executeHybridSearch(params, context, limit, offset);
+      const depth = requireCursorDepth(params.searchAfter, sortSignature, context.cursorBinding);
+      fanOutResult = await executeHybridSearch(params, context, limit, offset, depth);
     } else {
       const scoring = scoringConfigFor(params, context);
       const workerResult = workerSearch ? await workerSearch(indexName, params, broadcastStatsForWorker(params, context, scoring), context.partitionIds) : null;
@@ -1178,11 +1298,12 @@ async function executeQuery(params, context) {
     const sortFieldNames = sortFields.map((entry) => entry.field);
     const sortFlatSchema = sortFieldNames.length === 0 ? {} : flattenSchema(config.schema);
     const sortFieldTypes = sortFieldNames.map((field) => sortFlatSchema[field]);
+    const sortModes = sortModesOf(sortFields);
     const sortKeyCache = /* @__PURE__ */ new Map();
     const sortKeyOf = (docId) => {
       let key = sortKeyCache.get(docId);
       if (key === void 0) {
-        key = manager.sortValues(docId, sortFieldNames, sortFieldTypes);
+        key = manager.sortValues(docId, sortFieldNames, sortFieldTypes, sortModes);
         sortKeyCache.set(docId, key);
       }
       return key;
@@ -1193,12 +1314,15 @@ async function executeQuery(params, context) {
     if (params.group) {
       groups = applyGrouping(hits, params.group, (docId) => manager.getRef(docId));
     }
+    let pinsFromOutside = 0;
     if (params.pinned && params.searchAfter === void 0 && context.partitionIds === void 0) {
-      hits = applyPinning(hits, params.pinned, (docId) => {
+      const placement = placePinned(hits, params.pinned, (docId) => {
         const doc = manager.getRef(docId);
         if (!doc) return void 0;
         return { id: docId, score: 0, document: doc };
       });
+      hits = placement.hits;
+      pinsFromOutside = placement.placedFromOutside;
     }
     let sortContext;
     if (sortSignature !== null) {
@@ -1220,7 +1344,9 @@ async function executeQuery(params, context) {
     );
     paginated = paged.paginated;
     nextCursor = paged.nextCursor;
-    count = fanOutResult.totalMatched;
+    const holdsEveryMatch = fanOutResult.matchedExact !== false && fanOutResult.scored.length === fanOutResult.totalMatched;
+    count = fanOutResult.totalMatched + (holdsEveryMatch ? pinsFromOutside : 0);
+    countExact = fanOutResult.matchedExact !== false && (holdsEveryMatch || pinsFromOutside === 0);
     facets = fanOutResult.facets;
     if (sortSignature !== null && params.includeScores !== true) {
       for (const hit of hits) hit.score = void 0;
@@ -1256,6 +1382,7 @@ async function executeQuery(params, context) {
   return {
     hits: paginated,
     count,
+    countExact,
     elapsed,
     cursor: nextCursor,
     facets,
@@ -1267,6 +1394,7 @@ async function executePreflight(params, context) {
   const { manager, language, config, workerSearch, indexName } = context;
   const startTime = now();
   requireKnownMode(params);
+  requireValidQueryOptions(params, config);
   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;
@@ -1275,14 +1403,17 @@ async function executePreflight(params, context) {
   const requestedVectorField = params.vector?.field;
   const hasGlobalVectorIndex = requestedVectorField !== void 0 && vectorSearchersOf(context).has(requestedVectorField);
   let totalMatched;
+  let countExact = true;
   const preflightLimit = 1e3;
   const preflightOffset = 0;
   if (isVectorOnly && hasGlobalVectorIndex) {
     const result = await executeVectorSearch(params, context, preflightLimit, preflightOffset);
     totalMatched = result.totalMatched;
+    countExact = result.matchedExact !== false;
   } else if (isHybridMode && hasGlobalVectorIndex) {
     const result = await executeHybridSearch(params, context, preflightLimit, preflightOffset);
     totalMatched = result.totalMatched;
+    countExact = result.matchedExact !== false;
   } else if (countsWithoutScores(params)) {
     totalMatched = fanOutMatchCount(manager, params, language, config.schema, {
       searchOptions: searchOptionsFor(manager),
@@ -1306,7 +1437,7 @@ async function executePreflight(params, context) {
     }
   }
   const elapsed = now() - startTime;
-  return { count: totalMatched, elapsed };
+  return { count: totalMatched, countExact, elapsed };
 }
 
 // src/engine/suggest.ts
@@ -1356,4 +1487,4 @@ function pickDisplaySurface(surfaceOccurrences) {
   return best;
 }
 
-export { clampLimit, dedupePinnedEntries, executeListDocuments, executePreflight, executeQuery, executeSuggest, foldGroupReducer, listBindingOf, now, queryBindingOf, validateBM25Params, validateDocId, validateIndexName, validatePartitionConfig, validateWorkerConfig };
+export { clampLimit, dedupePinnedEntries, executeListDocuments, executePreflight, executeQuery, executeSuggest, foldGroupReducer, hitsKeptPerGroup, listBindingOf, now, queryBindingOf, resolveHybridFusion, validateBM25Params, validateDocId, validateIndexName, validatePartitionConfig, validateWorkerConfig };