@delali/narsil 0.2.4-next.55 → 0.3.0

package/dist/index.browser.mjs

@@ -14,6 +14,7 @@ var ErrorCodes = {
   INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS",
   INDEX_ORPHANED: "INDEX_ORPHANED",
   INDEX_REOPEN_CAPACITY_EXHAUSTED: "INDEX_REOPEN_CAPACITY_EXHAUSTED",
+  INSTANCE_SHUT_DOWN: "INSTANCE_SHUT_DOWN",
   PARTITION_CORRUPTED: "PARTITION_CORRUPTED",
   PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE",
   WORKER_CRASHED: "WORKER_CRASHED",
@@ -1808,6 +1809,84 @@ function getLanguage(name) {
   return lang;
 }
 
+// src/engine/config-keys.ts
+var NARSIL_CONFIG_KEYS = {
+  persistence: true,
+  invalidation: true,
+  plugins: true,
+  idGenerator: true,
+  workers: true,
+  embedding: true,
+  embeddingAdapters: true,
+  durability: true,
+  analysis: true,
+  lifecycle: true
+};
+var DURABILITY_CONFIG_KEYS = {
+  tier: true,
+  directory: true,
+  mode: true,
+  flushIntervalMs: true,
+  segmentMaxBytes: true,
+  checkpointIntervalMs: true,
+  checkpointMutationThreshold: true,
+  compactionThreshold: true
+};
+var WORKER_CONFIG_KEYS = {
+  enabled: true,
+  count: true,
+  promotionThreshold: true,
+  idleTimeoutMs: true,
+  mainCopyQueries: true,
+  bootstrapModule: true
+};
+var LIFECYCLE_CONFIG_KEYS = {
+  idleTimeoutMs: true,
+  maxOpenIndexes: true,
+  maxOpenBytes: true,
+  maxReopenWaiters: true
+};
+var ANALYSIS_CONFIG_KEYS = {
+  rebuild: true,
+  onStaleAnalysis: true
+};
+function requireKnownKeys(section, value, known) {
+  if (value === void 0 || value === null || typeof value !== "object") return;
+  for (const key of Object.keys(value)) {
+    if (Object.hasOwn(known, key)) continue;
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      `The configuration sets "${section}${key}", which is no setting that createNarsil accepts. The settings at that level are ${Object.keys(known).join(", ")}`,
+      { setting: `${section}${key}`, settings: Object.keys(known) }
+    );
+  }
+}
+function requireNamedPlugins(plugins) {
+  if (plugins === void 0) return;
+  if (!Array.isArray(plugins)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, 'The configuration sets "plugins" to something other than a list');
+  }
+  plugins.forEach((plugin, position) => {
+    const name = plugin?.name;
+    if (typeof name !== "string" || name.trim().length === 0) {
+      throw new NarsilError(
+        ErrorCodes.CONFIG_INVALID,
+        `The plugin at position ${position} carries no name, and the engine names each plugin in its errors and event payloads`,
+        { position }
+      );
+    }
+  });
+}
+function requireKnownConfig(config) {
+  if (config === void 0) return;
+  requireKnownKeys("", config, NARSIL_CONFIG_KEYS);
+  requireKnownKeys("durability.", config.durability, DURABILITY_CONFIG_KEYS);
+  requireKnownKeys("workers.", config.workers, WORKER_CONFIG_KEYS);
+  requireKnownKeys("lifecycle.", config.lifecycle, LIFECYCLE_CONFIG_KEYS);
+  requireKnownKeys("analysis.", config.analysis, ANALYSIS_CONFIG_KEYS);
+  requireNamedPlugins(config.plugins);
+}
+
 // src/core/id-generator.ts
 function generateId() {
   const bytes = new Uint8Array(16);
@@ -1843,6 +1922,9 @@ function isTextFieldType(fieldType) {
   return fieldType === "string" || fieldType === SORTABLE_TEXT_FIELD_TYPE;
 }
 var VECTOR_PATTERN = /^vector\[(\d+)]$/;
+function isGeopointOrVectorType(fieldType) {
+  return fieldType === "geopoint" || fieldType !== void 0 && VECTOR_PATTERN.test(fieldType);
+}
 var FIELD_NAME_PATTERN = /^[A-Za-z0-9_]+$/;
 var RESERVED_ROOT_FIELDS = /* @__PURE__ */ new Set(["id"]);
 var PROTOTYPE_POLLUTION_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
@@ -2129,7 +2211,7 @@ function collectExtraFields(doc, schema, prefix, extras) {
   for (const key of Object.keys(doc)) {
     if (key === "id") continue;
     const path = prefix ? `${prefix}.${key}` : key;
-    if (!(key in schema)) {
+    if (!Object.hasOwn(schema, key)) {
       extras.push(path);
       continue;
     }
@@ -2257,9 +2339,13 @@ function flattenRecursive(schema, prefix, result) {
     }
   }
 }
+var flattenedSchemas = /* @__PURE__ */ new WeakMap();
 function flattenSchema(schema) {
-  const result = {};
+  const cached = flattenedSchemas.get(schema);
+  if (cached !== void 0) return cached;
+  const result = /* @__PURE__ */ Object.create(null);
   flattenRecursive(schema, "", result);
+  flattenedSchemas.set(schema, Object.freeze(result));
   return result;
 }
 function extractVectorFieldsFromSchema(schema) {
@@ -2911,6 +2997,16 @@ function compareSortStrings(a, b) {
 var SORT_VALUE_MAX_CODE_POINTS = 512;
 
 // src/core/ordering/sort-values.ts
+var SORT_MODES = ["min", "max", "avg", "median"];
+function isSortMode(value) {
+  return value === "min" || value === "max" || value === "avg" || value === "median";
+}
+function defaultSortMode(direction) {
+  return direction === "desc" ? "max" : "min";
+}
+function sortModeOf(entry) {
+  return entry.mode ?? defaultSortMode(entry.direction);
+}
 function truncateSortString(value) {
   if (value.length <= SORT_VALUE_MAX_CODE_POINTS) return value;
   let index = 0;
@@ -2932,6 +3028,40 @@ function toComparableSortValue(value) {
   if (typeof value === "boolean") return value;
   return null;
 }
+function numericReduction(values, mode) {
+  const numbers = [];
+  for (const element of values) {
+    if (typeof element === "number" && Number.isFinite(element)) numbers.push(element);
+  }
+  if (numbers.length === 0) return null;
+  if (mode === "avg") {
+    let mean = 0;
+    for (let index = 0; index < numbers.length; index++) {
+      mean += (numbers[index] - mean) / (index + 1);
+    }
+    return mean;
+  }
+  numbers.sort((a, b) => a - b);
+  const middle = numbers.length >> 1;
+  if (numbers.length % 2 === 1) return numbers[middle];
+  return numbers[middle - 1] / 2 + numbers[middle] / 2;
+}
+function toReducedSortValue(value, mode) {
+  if (!Array.isArray(value)) return toComparableSortValue(value);
+  if (mode === "avg" || mode === "median") return numericReduction(value, mode);
+  let chosen = null;
+  for (const element of value) {
+    const comparable = toComparableSortValue(element);
+    if (comparable === null) continue;
+    if (chosen === null) {
+      chosen = comparable;
+      continue;
+    }
+    const comparison = comparePresentValues(comparable, chosen);
+    if (mode === "min" ? comparison < 0 : comparison > 0) chosen = comparable;
+  }
+  return chosen;
+}
 function readSortField(document2, path) {
   const segments = path.split(".");
   let current = document2;
@@ -3236,6 +3366,14 @@ var POSTING_LIST_COMPACTION_THRESHOLD = 0.3;
 var MAX_TERM_FREQUENCY = 65535;
 
 // src/core/fuzzy.ts
+function fuzzyTermMatches(queryTerm, indexTerm, tolerance, prefixLength) {
+  if (queryTerm === indexTerm) return true;
+  if (tolerance <= 0) return false;
+  if (prefixLength > 0 && queryTerm.length >= prefixLength && !indexTerm.startsWith(queryTerm.slice(0, prefixLength))) {
+    return false;
+  }
+  return boundedLevenshtein(queryTerm, indexTerm, tolerance).withinTolerance;
+}
 function boundedLevenshtein(a, b, tolerance) {
   if (tolerance < 0) return { distance: -1, withinTolerance: false };
   if (a === b) return { distance: 0, withinTolerance: true };
@@ -4033,6 +4171,7 @@ function getNestedValue(obj, path) {
   let current = obj;
   for (let i = 0; i < parts.length; i++) {
     if (current === null || current === void 0 || typeof current !== "object") return void 0;
+    if (!Object.hasOwn(current, parts[i])) return void 0;
     current = current[parts[i]];
   }
   return current;
@@ -4093,6 +4232,10 @@ function getAllInternalDocIds(docStore) {
 }
 
 // src/core/partition/facets.ts
+var UNDECLARED_FIELD_TYPE = "";
+function keptFacetValues(limit) {
+  return limit !== void 0 && limit > 0 ? Math.floor(limit) : void 0;
+}
 function ordinalBitsetOf(state, matched) {
   if ("ordinalBitset" in matched) return matched.ordinalBitset;
   const bitset = createBitSet(state.docStore.internalIdCapacity());
@@ -4140,7 +4283,7 @@ function countValuesFromDocuments(state, fieldPath, matched) {
 function countRangeFromDocuments(state, fieldPath, fieldType, range, matched) {
   let count = 0;
   for (const value of matchedFieldValues(state, fieldPath, matched)) {
-    if (fieldType === "number[]" && Array.isArray(value)) {
+    if ((fieldType === "number[]" || fieldType === UNDECLARED_FIELD_TYPE) && Array.isArray(value)) {
       for (const v of value) {
         if (v >= range.from && v < range.to) {
           count++;
@@ -4202,13 +4345,12 @@ function computeFacets(state, matched, config, schema) {
     return matchedBitset;
   };
   for (const [fieldPath, facetOpts] of Object.entries(config)) {
-    const fieldType = flatSchema[fieldPath];
-    if (!fieldType) continue;
-    const valueCounts = facetOpts.ranges && (fieldType === "number" || fieldType === "number[]") ? countNumericRanges(state, fieldPath, fieldType, facetOpts.ranges, bitset, matched) : countFieldValues(state, fieldPath, fieldType, bitset, matched);
+    const fieldType = flatSchema[fieldPath] ?? UNDECLARED_FIELD_TYPE;
+    const valueCounts = facetOpts.ranges && (fieldType === "number" || fieldType === "number[]" || fieldType === UNDECLARED_FIELD_TYPE) ? countNumericRanges(state, fieldPath, fieldType, facetOpts.ranges, bitset, matched) : countFieldValues(state, fieldPath, fieldType, bitset, matched);
     const ordered = Array.from(valueCounts.entries());
     const sortDir = facetOpts.sort ?? "desc";
     ordered.sort((a, b) => (sortDir === "asc" ? a[1] - b[1] : b[1] - a[1]) || compareCodePoints(a[0], b[0]));
-    const keep = facetOpts.limit && facetOpts.limit > 0 ? facetOpts.limit : ordered.length;
+    const keep = Math.min(keptFacetValues(facetOpts.limit) ?? ordered.length, ordered.length);
     const entries = ordered.slice(0, keep);
     let errorBound = 0;
     for (let index = keep; index < ordered.length; index++) {
@@ -4225,6 +4367,9 @@ function computeFacets(state, matched, config, schema) {
 
 // src/geo/constants.ts
 var DEG_TO_RAD = Math.PI / 180;
+var MIN_POLYGON_POINTS = 3;
+var ANTIMERIDIAN_SPAN_DEGREES = 180;
+var FULL_TURN_DEGREES = 360;
 var VINCENTY_MAX_ITERATIONS = 200;
 var VINCENTY_CONVERGENCE_THRESHOLD = 1e-12;
 
@@ -4243,24 +4388,66 @@ function haversineDistance(lat1, lon1, lat2, lon2) {
 }
 
 // src/geo/polygon.ts
-function isPointInPolygon(lat, lon, polygon) {
-  if (polygon.length < 3) return false;
-  let inside = false;
-  const n = polygon.length;
-  for (let i = 0, j = n - 1; i < n; j = i++) {
-    const lonI = polygon[i].lon;
-    const latI = polygon[i].lat;
-    const lonJ = polygon[j].lon;
-    const latJ = polygon[j].lat;
-    if (lonI > lon !== lonJ > lon) {
-      const slope = (latJ - latI) / (lonJ - lonI);
-      const intersectLat = latI + slope * (lon - lonI);
-      if (lat < intersectLat) {
-        inside = !inside;
-      }
-    }
+function requirePolygonRing(points) {
+  if (!Array.isArray(points) || points.length < MIN_POLYGON_POINTS) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_FILTER,
+      `A polygon encloses an area only with at least ${MIN_POLYGON_POINTS} points`,
+      { points: Array.isArray(points) ? points.length : typeof points, minimum: MIN_POLYGON_POINTS }
+    );
+  }
+  points.forEach((point, position) => {
+    const { lat, lon } = point ?? {};
+    if (typeof lat === "number" && Number.isFinite(lat) && typeof lon === "number" && Number.isFinite(lon)) return;
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_FILTER,
+      `A polygon point carries a finite "lat" and "lon", and the point at position ${position} does not`,
+      { position }
+    );
+  });
+}
+function signedArea(polygon) {
+  let area = 0;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    area += polygon[j].lon * polygon[i].lat - polygon[i].lon * polygon[j].lat;
   }
-  return inside;
+  return area;
+}
+function crossesAntimeridian(polygon) {
+  let west = Number.POSITIVE_INFINITY;
+  let east = Number.NEGATIVE_INFINITY;
+  for (const point of polygon) {
+    if (point.lon < west) west = point.lon;
+    if (point.lon > east) east = point.lon;
+  }
+  return east - west >= ANTIMERIDIAN_SPAN_DEGREES && signedArea(polygon) < 0;
+}
+function eastward(lon) {
+  return lon < 0 ? lon + FULL_TURN_DEGREES : lon;
+}
+function polygonContainment(polygon) {
+  const n = polygon.length;
+  if (n < MIN_POLYGON_POINTS) return () => false;
+  const unwrap = crossesAntimeridian(polygon);
+  const lats = new Float64Array(n);
+  const lons = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    lats[i] = polygon[i].lat;
+    lons[i] = unwrap ? eastward(polygon[i].lon) : polygon[i].lon;
+  }
+  return (lat, rawLon) => {
+    const lon = unwrap ? eastward(rawLon) : rawLon;
+    let inside = false;
+    for (let i = 0, j = n - 1; i < n; j = i++) {
+      const lonI = lons[i];
+      const lonJ = lons[j];
+      if (lonI > lon !== lonJ > lon) {
+        const intersectLat = lats[i] + (lats[j] - lats[i]) / (lonJ - lonI) * (lon - lonI);
+        if (lat < intersectLat) inside = !inside;
+      }
+    }
+    return inside;
+  };
 }
 
 // src/geo/vincenty.ts
@@ -4345,9 +4532,10 @@ function createGeoIndex() {
     },
     polygonQuery(points, inside) {
       const result = /* @__PURE__ */ new Set();
+      const contains = polygonContainment(points);
       for (let i = 0; i < entries.length; i++) {
         const entry = entries[i];
-        const withinPolygon = isPointInPolygon(entry.lat, entry.lon, points);
+        const withinPolygon = contains(entry.lat, entry.lon);
         if (inside ? withinPolygon : !withinPolygon) {
           result.add(entry.docId);
         }
@@ -5108,13 +5296,175 @@ var FIELD_FILTER_OPERATORS = [
   "polygon"
 ];
 
+// src/filters/constants.ts
+var MAX_FILTER_DEPTH = 30;
+
+// src/filters/operands.ts
+var RANGE_OPERATORS = ["gt", "lt", "gte", "lte"];
+var TEXT_OPERATORS = ["startsWith", "endsWith"];
+var EQUALITY_OPERATORS = ["eq", "ne"];
+var LIST_OPERATORS = ["in", "nin"];
+function operandKindOf(type) {
+  if (type === void 0) return void 0;
+  if (type === "number" || type === "number[]") return "number";
+  if (type === "boolean" || type === "boolean[]") return "boolean";
+  if (type === "geopoint") return "geopoint";
+  if (type.startsWith("vector[")) return "vector";
+  return "text";
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function kindOfValue(value) {
+  if (isFiniteNumber(value)) return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "string") return "text";
+  return void 0;
+}
+function invalid(message, fieldPath, operator) {
+  throw new NarsilError(ErrorCodes.SEARCH_INVALID_FILTER, message, { fieldPath, operator });
+}
+function requireFieldKind(fieldPath, operator, type, accepted) {
+  const kind = operandKindOf(type);
+  if (kind === void 0 || accepted.includes(kind)) return;
+  invalid(
+    `The engine applies "${operator}" to ${accepted.join(" or ")} fields alone, and the schema declares field "${fieldPath}" as "${type}"`,
+    fieldPath,
+    operator
+  );
+}
+function requireRadius(fieldPath, radius) {
+  const circle = radius;
+  if (circle === null || typeof circle !== "object") {
+    invalid(`"radius" on field "${fieldPath}" must be an object`, fieldPath, "radius");
+  }
+  for (const key of ["lat", "lon", "distance"]) {
+    if (!isFiniteNumber(circle[key])) {
+      invalid(`"radius.${key}" on field "${fieldPath}" must be a finite number`, fieldPath, "radius");
+    }
+  }
+  if (circle.distance < 0) {
+    invalid(
+      `"radius.distance" on field "${fieldPath}" must be zero or more, and this filter sets ${String(circle.distance)}`,
+      fieldPath,
+      "radius"
+    );
+  }
+}
+function invalidShape(message) {
+  throw new NarsilError(ErrorCodes.SEARCH_INVALID_FILTER, message);
+}
+function isObjectRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function undeclaredFieldOnStrictIndex(field, option) {
+  return new NarsilError(
+    ErrorCodes.SEARCH_INVALID_FIELD,
+    `The index is strict and its schema declares no field "${field}", so no stored document has a value in that field for this ${option}`,
+    { field, option }
+  );
+}
+function requireValidExpression(expression, rules, depth) {
+  if (depth > MAX_FILTER_DEPTH) invalidShape(`A filter expression nests at most ${MAX_FILTER_DEPTH} levels deep`);
+  if (!isObjectRecord(expression)) invalidShape("Each filter expression must be an object");
+  const { fields, and, or, not } = expression;
+  if (fields !== void 0) {
+    if (!isObjectRecord(fields)) invalidShape('"fields" in a filter expression must be an object keyed by field path');
+    for (const [fieldPath, filter] of Object.entries(fields)) {
+      if (rules.declaredOnly && !Object.hasOwn(rules.fieldTypes, fieldPath)) {
+        throw undeclaredFieldOnStrictIndex(fieldPath, "filter");
+      }
+      if (isObjectRecord(filter)) requireValidOperands(fieldPath, filter, rules.fieldTypes[fieldPath]);
+    }
+  }
+  for (const [clause, list] of [
+    ["and", and],
+    ["or", or]
+  ]) {
+    if (list === void 0) continue;
+    if (!Array.isArray(list)) invalidShape(`"${clause}" in a filter expression must be a list of filter expressions`);
+    for (const nested of list) requireValidExpression(nested, rules, depth + 1);
+  }
+  if (not !== void 0) requireValidExpression(not, rules, depth + 1);
+}
+function requireValidFilter(expression, fieldTypes, declaredOnly = false) {
+  if (expression === void 0 || expression === null) return;
+  requireValidExpression(expression, { fieldTypes, declaredOnly }, 0);
+}
+function requireValidOperands(fieldPath, filter, type) {
+  for (const operator of RANGE_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    if (!isFiniteNumber(filter[operator])) {
+      invalid(`"${operator}" on field "${fieldPath}" must be a finite number`, fieldPath, operator);
+    }
+    requireFieldKind(fieldPath, operator, type, ["number"]);
+  }
+  if (filter.between !== void 0) {
+    const bounds = filter.between;
+    if (!Array.isArray(bounds) || bounds.length !== 2 || !isFiniteNumber(bounds[0]) || !isFiniteNumber(bounds[1])) {
+      invalid(
+        `"between" on field "${fieldPath}" must be two finite numbers, the lower bound first`,
+        fieldPath,
+        "between"
+      );
+    }
+    requireFieldKind(fieldPath, "between", type, ["number"]);
+  }
+  for (const operator of TEXT_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    if (typeof filter[operator] !== "string") {
+      invalid(`"${operator}" on field "${fieldPath}" must be a string`, fieldPath, operator);
+    }
+    requireFieldKind(fieldPath, operator, type, ["text"]);
+  }
+  for (const operator of EQUALITY_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    const kind = kindOfValue(filter[operator]);
+    if (kind === void 0) {
+      invalid(
+        `"${operator}" on field "${fieldPath}" must be a string, a finite number, or a boolean`,
+        fieldPath,
+        operator
+      );
+    }
+    requireFieldKind(fieldPath, operator, type, [kind]);
+  }
+  for (const operator of LIST_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    const values = filter[operator];
+    if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) {
+      invalid(`"${operator}" on field "${fieldPath}" must be a list of strings`, fieldPath, operator);
+    }
+    requireFieldKind(fieldPath, operator, type, ["text"]);
+  }
+  if (filter.size !== void 0) {
+    const size = filter.size;
+    if (size === null || typeof size !== "object") {
+      invalid(`"size" on field "${fieldPath}" must be a comparison object`, fieldPath, "size");
+    }
+    requireValidOperands(`${fieldPath}.size`, size, "number");
+  }
+  if (filter.radius !== void 0) requireRadius(fieldPath, filter.radius);
+  if (filter.polygon !== void 0) {
+    if (!isObjectRecord(filter.polygon)) {
+      invalid(`"polygon" on field "${fieldPath}" must be an object`, fieldPath, "polygon");
+    }
+    requirePolygonRing(filter.polygon.points);
+  }
+}
+
 // src/filters/operators/shared.ts
 var METERS_PER_KM = 1e3;
 var METERS_PER_MI = 1609.344;
 function convertToMeters(distance, unit) {
   if (unit === "km") return distance * METERS_PER_KM;
   if (unit === "mi") return distance * METERS_PER_MI;
-  return distance;
+  if (unit === "m") return distance;
+  throw new NarsilError(
+    ErrorCodes.SEARCH_INVALID_FILTER,
+    `The engine measures a radius in "km", "mi", or "m", and "${String(unit)}" is none of them`,
+    { unit: String(unit) }
+  );
 }
 function matchesNumericComparison(value, filter) {
   if (filter.eq !== void 0 && value !== filter.eq) return false;
@@ -5126,6 +5476,27 @@ function matchesNumericComparison(value, filter) {
   if (filter.between !== void 0 && !(value >= filter.between[0] && value <= filter.between[1])) return false;
   return true;
 }
+function holdsValue(stored, value) {
+  return Array.isArray(stored) ? stored.includes(value) : stored === value;
+}
+function lacksValue(stored, value) {
+  if (stored === void 0 || stored === null) return false;
+  return Array.isArray(stored) ? !stored.includes(value) : stored !== value;
+}
+function isStringIn(values) {
+  return (element) => typeof element === "string" && values.has(element);
+}
+function holdsStringIn(stored, values) {
+  return Array.isArray(stored) ? stored.some(isStringIn(values)) : isStringIn(values)(stored);
+}
+function holdsNoStringIn(stored, values) {
+  if (Array.isArray(stored)) return !stored.some(isStringIn(values));
+  return typeof stored === "string" && !values.has(stored);
+}
+function holdsStringWhere(stored, test) {
+  const matches = (element) => typeof element === "string" && test(element);
+  return Array.isArray(stored) ? stored.some(matches) : matches(stored);
+}
 
 // src/filters/operators/bitset.ts
 function resolveBitset(bs) {
@@ -5159,7 +5530,7 @@ function applyEqBitset(value, allDocsBitset, capacity, getValue, fieldIndex) {
   if (fieldIndex?.type === "enum" && typeof value === "string") {
     return fieldIndex.index.getDocIdsBitset(value, capacity);
   }
-  return scanToBitset(allDocsBitset, capacity, getValue, (v) => v === value);
+  return scanToBitset(allDocsBitset, capacity, getValue, (v) => holdsValue(v, value));
 }
 function applyNeBitset(value, allDocsBitset, capacity, getValue, fieldIndex) {
   if (fieldIndex?.type === "numeric" && typeof value === "number") {
@@ -5175,7 +5546,7 @@ function applyNeBitset(value, allDocsBitset, capacity, getValue, fieldIndex) {
     const eq = fieldIndex.index.getDocIdsBitset(value, capacity);
     return bitsetAnd(all, bitsetNot(eq, capacity));
   }
-  return scanToBitset(allDocsBitset, capacity, getValue, (v) => v !== void 0 && v !== null && v !== value);
+  return scanToBitset(allDocsBitset, capacity, getValue, (v) => lacksValue(v, value));
 }
 function applyGtBitset(value, allDocsBitset, capacity, getValue, fieldIndex) {
   if (fieldIndex?.type === "numeric") {
@@ -5212,7 +5583,7 @@ function applyInBitset(values, allDocsBitset, capacity, getValue, fieldIndex) {
     return fieldIndex.index.getDocIdsInBitset(values, capacity);
   }
   const valSet = new Set(values);
-  return scanToBitset(allDocsBitset, capacity, getValue, (v) => typeof v === "string" && valSet.has(v));
+  return scanToBitset(allDocsBitset, capacity, getValue, (v) => holdsStringIn(v, valSet));
 }
 function applyNinBitset(values, allDocsBitset, capacity, getValue, fieldIndex) {
   if (fieldIndex?.type === "enum") {
@@ -5221,18 +5592,13 @@ function applyNinBitset(values, allDocsBitset, capacity, getValue, fieldIndex) {
     return bitsetAnd(all, bitsetNot(matched, capacity));
   }
   const valSet = new Set(values);
-  return scanToBitset(
-    allDocsBitset,
-    capacity,
-    getValue,
-    (v) => v !== void 0 && v !== null && typeof v === "string" && !valSet.has(v)
-  );
+  return scanToBitset(allDocsBitset, capacity, getValue, (v) => holdsNoStringIn(v, valSet));
 }
 function applyStartsWithBitset(prefix, allDocsBitset, capacity, getValue) {
-  return scanToBitset(allDocsBitset, capacity, getValue, (v) => typeof v === "string" && v.startsWith(prefix));
+  return scanToBitset(allDocsBitset, capacity, getValue, (v) => holdsStringWhere(v, (text) => text.startsWith(prefix)));
 }
 function applyEndsWithBitset(suffix, allDocsBitset, capacity, getValue) {
-  return scanToBitset(allDocsBitset, capacity, getValue, (v) => typeof v === "string" && v.endsWith(suffix));
+  return scanToBitset(allDocsBitset, capacity, getValue, (v) => holdsStringWhere(v, (text) => text.endsWith(suffix)));
 }
 function applyContainsAllBitset(values, allDocsBitset, capacity, getValue) {
   return scanToBitset(allDocsBitset, capacity, getValue, (v) => {
@@ -5296,6 +5662,7 @@ function applyGeoRadiusBitset(filter, geoIndex, capacity) {
   return bitsetFromSet(setResult, capacity);
 }
 function applyGeoPolygonBitset(filter, geoIndex, capacity) {
+  requirePolygonRing(filter.points);
   const setResult = geoIndex.polygonQuery(filter.points, filter.inside ?? true);
   return bitsetFromSet(setResult, capacity);
 }
@@ -5303,7 +5670,7 @@ function applyGeoPolygonBitset(filter, geoIndex, capacity) {
 // src/filters/evaluator.ts
 var EXPRESSION_KEYS = new Set(FILTER_EXPRESSION_KEYS);
 var OPERATOR_KEYS = new Set(FIELD_FILTER_OPERATORS);
-function requireKnownKeys(value, known, describe) {
+function requireKnownKeys2(value, known, describe) {
   for (const key of Object.keys(value)) {
     if (!known.has(key)) {
       throw new NarsilError(ErrorCodes.SEARCH_INVALID_FILTER, describe(key), { key });
@@ -5311,7 +5678,7 @@ function requireKnownKeys(value, known, describe) {
   }
 }
 function evaluateFilters(expression, context) {
-  requireKnownKeys(
+  requireKnownKeys2(
     expression,
     EXPRESSION_KEYS,
     (key) => `A filter expression takes "fields", "and", "or", and "not", and "${key}" is none of them. A per-field test such as { ${key}: { eq: ... } } belongs under "fields"`
@@ -5340,14 +5707,15 @@ function evaluateFilters(expression, context) {
   return applyAndBitset(bitsets);
 }
 function evaluateFieldFilter(fieldPath, filter, context) {
-  requireKnownKeys(
+  requireKnownKeys2(
     filter,
     OPERATOR_KEYS,
     (key) => `Field "${fieldPath}" is tested with "${key}", which is no filter operator`
   );
+  const f = filter;
+  requireValidOperands(fieldPath, f, context.fieldTypes[fieldPath]);
   const fieldIndex = context.fieldIndexes[fieldPath];
   const getValue = (internalId) => context.getFieldValue(internalId, fieldPath);
-  const f = filter;
   const bitsets = [];
   const { capacity } = context;
   let allDocsBitset = null;
@@ -5519,6 +5887,7 @@ function buildFilterContext(state, schema) {
   let cachedAllDocIds = null;
   let cachedAllDocIdsBitset = null;
   return {
+    fieldTypes: flat,
     fieldIndexes,
     getFieldValue: (internalId, fieldPath) => getFieldValueByInternalId(state.docStore, internalId, fieldPath),
     get allDocIds() {
@@ -5840,8 +6209,7 @@ function createValueStore(initialKind) {
     get kind() {
       return kind;
     },
-    set(internalId, value) {
-      const comparable = toComparableSortValue(value);
+    set(internalId, comparable) {
       if (kind === "number") {
         if (comparable === null) {
           setNumber(internalId, Number.NaN);
@@ -5911,6 +6279,12 @@ function createValueStore(initialKind) {
 }
 
 // src/core/partition/sort-columns/index.ts
+function mayHoldList(fieldType) {
+  return fieldType === void 0 || fieldType.endsWith("[]");
+}
+function columnKeyOf(field, fieldType, mode) {
+  return mayHoldList(fieldType) ? `${mode}:${field}` : `value:${field}`;
+}
 function liveInternalIds(docStore) {
   const ids = [];
   for (const internalId of docStore.allInternalIds()) ids.push(internalId);
@@ -5928,21 +6302,22 @@ function createSortColumnSet(docStore) {
     entry.dirty.clear();
     entry.dirtyStream = null;
   }
-  function backfill(field, fieldType) {
+  function backfill(key, field, fieldType, mode) {
     const store = createValueStore(kindForFieldType(fieldType));
     for (const [docId, stored] of docStore.all()) {
       const internalId = docStore.getInternalId(docId);
       if (internalId === void 0) continue;
-      store.set(internalId, readSortField(stored.fields, field));
+      store.set(internalId, toReducedSortValue(readSortField(stored.fields, field), mode));
     }
     const entry = {
       field,
+      mode,
       store,
       order: buildOrder(store, liveInternalIds(docStore), docStore.internalIdCapacity()),
       dirty: /* @__PURE__ */ new Set(),
       dirtyStream: null
     };
-    columns.set(field, entry);
+    columns.set(key, entry);
     return entry;
   }
   function buildDirtyStream(entry) {
@@ -5995,13 +6370,14 @@ function createSortColumnSet(docStore) {
     };
   }
   return {
-    holds(field) {
-      return columns.has(field);
+    holds(field, fieldType, mode) {
+      return columns.has(columnKeyOf(field, fieldType, mode));
     },
-    column(field, fieldType) {
-      let entry = columns.get(field);
+    column(field, fieldType, mode) {
+      const key = columnKeyOf(field, fieldType, mode);
+      let entry = columns.get(key);
       if (entry === void 0) {
-        entry = backfill(field, fieldType);
+        entry = backfill(key, field, fieldType, mode);
       } else if (entry.dirty.size > rebuildThreshold()) {
         rebuild2(entry);
       }
@@ -6009,7 +6385,7 @@ function createSortColumnSet(docStore) {
     },
     record(internalId, document2) {
       for (const entry of columns.values()) {
-        entry.store.set(internalId, readSortField(document2, entry.field));
+        entry.store.set(internalId, toReducedSortValue(readSortField(document2, entry.field), entry.mode));
         entry.dirty.add(internalId);
         entry.dirtyStream = null;
       }
@@ -6164,11 +6540,13 @@ function createStream(column, direction, anchorRank) {
   };
 }
 function selectSortedPage(state, request) {
-  const { fields, directions, fieldTypes, limit, anchorKey, anchorId, matches } = request;
+  const { fields, directions, fieldTypes, modes, limit, anchorKey, anchorId, matches } = request;
   if (limit <= 0 || fields.length === 0) return [];
   const set = state.sortColumns;
   if (set === null) return [];
-  const columns = fields.map((field, index) => set.column(field, fieldTypes[index]));
+  const columns = fields.map(
+    (field, index) => set.column(field, fieldTypes[index], modes[index] ?? defaultSortMode(directions[index] ?? "asc"))
+  );
   const resolver = state.docStore.resolver();
   const leading = columns[0];
   const leadingDirection = directions[0];
@@ -6210,17 +6588,18 @@ function sortedPageOf(state, request) {
   ensureColumns(state);
   return selectSortedPage(state, request);
 }
-function sortValuesOf(state, docId, fields, fieldTypes) {
+function sortValuesOf(state, docId, fields, fieldTypes, modes) {
   const set = state.sortColumns;
   const internalId = state.docStore.getInternalId(docId);
   const stored = state.docStore.get(docId);
   const key = new Array(fields.length);
   for (let i = 0; i < fields.length; i++) {
-    if (set !== null && internalId !== void 0 && set.holds(fields[i])) {
-      key[i] = set.column(fields[i], fieldTypes[i]).valueOf(internalId);
+    const mode = modes[i] ?? "min";
+    if (set !== null && internalId !== void 0 && set.holds(fields[i], fieldTypes[i], mode)) {
+      key[i] = set.column(fields[i], fieldTypes[i], mode).valueOf(internalId);
       continue;
     }
-    key[i] = stored === void 0 ? null : toComparableSortValue(readSortField(stored.fields, fields[i]));
+    key[i] = stored === void 0 ? null : toReducedSortValue(readSortField(stored.fields, fields[i]), mode);
   }
   return key;
 }
@@ -8251,8 +8630,8 @@ function createPartitionIndex(partitionId, trackPositions = true) {
     sortedPage(request) {
       return sortedPageOf(state, request);
     },
-    sortValues(docId, fields, fieldTypes) {
-      return sortValuesOf(state, docId, fields, fieldTypes);
+    sortValues(docId, fields, fieldTypes, modes) {
+      return sortValuesOf(state, docId, fields, fieldTypes, modes);
     },
     applyFilters(filters, schema) {
       return applyPartitionFilters(state, filters, schema);
@@ -8287,6 +8666,18 @@ function createPartitionIndex(partitionId, trackPositions = true) {
   return partition;
 }
 
+// src/engine/orchestration/turn.ts
+function afterCurrentTurn(callback) {
+  if (typeof setImmediate === "function") {
+    setImmediate(callback);
+    return;
+  }
+  setTimeout(callback, 0);
+}
+function yieldToEventLoop() {
+  return new Promise((resolve) => afterCurrentTurn(resolve));
+}
+
 // src/partitioning/constants.ts
 var REBALANCE_CHUNK_SIZE = 1e3;
 var DEFAULT_WRITE_AHEAD_QUEUE_MAX_SIZE = 1e4;
@@ -8361,7 +8752,7 @@ function createRebalancer() {
               documentsProcessed,
               documentsTotal
             });
-            await new Promise((resolve) => setTimeout(resolve, 0));
+            await yieldToEventLoop();
           }
         }
       }
@@ -8371,7 +8762,7 @@ function createRebalancer() {
           documentsProcessed,
           documentsTotal
         });
-        await new Promise((resolve) => setTimeout(resolve, 0));
+        await yieldToEventLoop();
       }
       onProgress?.({
         phase: "swapping",
@@ -8442,13 +8833,43 @@ function createPartitionRouter() {
 }
 
 // src/plugins/registry.ts
+var WRITE_REJECTING_HOOKS = /* @__PURE__ */ new Set(["beforeInsert", "beforeUpdate", "beforeRemove"]);
 function isThenable(value) {
   return value !== null && typeof value === "object" && typeof value.then === "function";
 }
-async function continueAsync(pending, hooks, startIndex, context) {
+function thrownText(err, plugin, hookName) {
+  if (err instanceof Error) return err.message;
+  try {
+    return String(err);
+  } catch {
+    return `The ${hookName} hook of plugin "${plugin}" rejects the write`;
+  }
+}
+function asWriteRejection(err, plugin, hookName) {
+  if (err instanceof NarsilError) return err;
+  return new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, thrownText(err, plugin, hookName), {
+    plugin,
+    hook: hookName
+  });
+}
+function invoke(hook, hookName, context) {
+  const rejectsWrites = WRITE_REJECTING_HOOKS.has(hookName);
+  let result;
+  try {
+    result = hook.run(context);
+  } catch (err) {
+    throw rejectsWrites ? asWriteRejection(err, hook.plugin, hookName) : err;
+  }
+  if (!isThenable(result)) return null;
+  if (!rejectsWrites) return result;
+  return Promise.resolve(result).catch((err) => {
+    throw asWriteRejection(err, hook.plugin, hookName);
+  });
+}
+async function continueAsync(pending, hooks, startIndex, hookName, context) {
   await pending;
   for (let i = startIndex; i < hooks.length; i++) {
-    await hooks[i](context);
+    await invoke(hooks[i], hookName, context);
   }
 }
 function createPluginRegistry() {
@@ -8465,14 +8886,14 @@ function createPluginRegistry() {
       for (const plugin of plugins) {
         const hook = plugin[hookName];
         if (typeof hook === "function") {
-          hooks.push(hook.bind(plugin));
+          hooks.push({ plugin: plugin.name, run: hook.bind(plugin) });
         }
       }
       if (hooks.length === 0) return;
       for (let i = 0; i < hooks.length; i++) {
-        const result = hooks[i](context);
-        if (isThenable(result)) {
-          return continueAsync(result, hooks, i + 1, context);
+        const pending = invoke(hooks[i], hookName, context);
+        if (pending !== null) {
+          return continueAsync(pending, hooks, i + 1, hookName, context);
         }
       }
     }
@@ -8816,8 +9237,35 @@ function heapPop(heap) {
   return top;
 }
 
+// src/search/oversample.ts
+function oversampledShardSize(size) {
+  return Math.ceil(size * 1.5) + 10;
+}
+
 // src/search/facets.ts
-function mergeFacets(partitionFacets) {
+function keptValueCount(fieldConfig) {
+  return keptFacetValues(fieldConfig?.limit);
+}
+function everyValueFacetConfig(config) {
+  const widened = {};
+  for (const [field, fieldConfig] of Object.entries(config)) {
+    widened[field] = { ...fieldConfig, limit: void 0 };
+  }
+  return widened;
+}
+function oversampledFacetConfig(config) {
+  const widened = {};
+  for (const [field, fieldConfig] of Object.entries(config)) {
+    if (fieldConfig?.ranges !== void 0 || fieldConfig?.sort === "asc") {
+      widened[field] = { ...fieldConfig, limit: void 0 };
+      continue;
+    }
+    const kept = keptValueCount(fieldConfig);
+    widened[field] = kept === void 0 ? fieldConfig : { ...fieldConfig, limit: oversampledShardSize(kept) };
+  }
+  return widened;
+}
+function mergeFacets(partitionFacets, config) {
   const merged = /* @__PURE__ */ new Map();
   const bounds = /* @__PURE__ */ new Map();
   for (const partition of partitionFacets) {
@@ -8835,11 +9283,21 @@ function mergeFacets(partitionFacets) {
   }
   const result = {};
   for (const [field, valueMap] of merged) {
+    const fieldConfig = config[field];
+    const ascending = fieldConfig?.sort === "asc";
+    const ordered = Array.from(valueMap.entries());
+    ordered.sort((a, b) => (ascending ? a[1] - b[1] : b[1] - a[1]) || compareCodePoints(a[0], b[0]));
+    const kept = Math.min(keptValueCount(fieldConfig) ?? ordered.length, ordered.length);
+    let largestLeftOut = 0;
+    for (let index = kept; index < ordered.length; index++) {
+      if (ordered[index][1] > largestLeftOut) largestLeftOut = ordered[index][1];
+    }
+    const errorBound = (bounds.get(field) ?? 0) + largestLeftOut;
     const values = {};
-    for (const [value, count] of valueMap) {
-      values[value] = count;
+    for (let index = 0; index < kept; index++) {
+      values[ordered[index][0]] = ordered[index][1];
     }
-    result[field] = { values, count: valueMap.size, errorBound: bounds.get(field) ?? 0 };
+    result[field] = { values, count: kept, errorBound };
   }
   return result;
 }
@@ -8852,6 +9310,13 @@ var MAX_SORT_FIELDS = 8;
 var MAX_SORT_FIELD_NAME_LENGTH = 255;
 var MAX_CURSOR_ANCHOR_CODE_POINTS = 512;
 var PREFIX_MAX_EXPANSIONS = 50;
+var DEFAULT_FUZZY_PREFIX_LENGTH = 2;
+var DEFAULT_MAX_PER_GROUP = 1;
+var DEFAULT_RANK_CONSTANT = 60;
+var MIN_RANK_CONSTANT = 1;
+var DEFAULT_LINEAR_ALPHA = 0.5;
+var MIN_LINEAR_ALPHA = 0;
+var MAX_LINEAR_ALPHA = 1;
 
 // src/search/cursor-codec.ts
 function encodeCursorText(text) {
@@ -8876,21 +9341,66 @@ function isFieldList(sort) {
 function normalizeSort(sort) {
   if (sort === void 0) return [];
   if (isFieldList(sort)) {
-    return sort.map((entry) => ({ field: entry.field, direction: entry.direction }));
+    return sort.map(
+      (entry) => entry.mode === void 0 ? { field: entry.field, direction: entry.direction } : { field: entry.field, direction: entry.direction, mode: entry.mode }
+    );
   }
   return Object.entries(sort).map(([field, direction]) => ({ field, direction }));
 }
-function requireSortableFields(sort, schema) {
+function sortModesOf(fields) {
+  return fields.map(sortModeOf);
+}
+function sortSignatureEntry(entry) {
+  const mode = sortModeOf(entry);
+  return mode === defaultSortMode(entry.direction) ? [entry.field, entry.direction] : [entry.field, entry.direction, mode];
+}
+function requireSortMode(entry, fieldType) {
+  if (entry.mode === void 0) return;
+  if (!isSortMode(entry.mode)) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_MODE,
+      `A sort mode is one of ${SORT_MODES.map((mode) => `"${mode}"`).join(", ")}, and the mode on "${entry.field}" is "${String(entry.mode)}"`,
+      { field: entry.field, mode: String(entry.mode) }
+    );
+  }
+  const averages = entry.mode === "avg" || entry.mode === "median";
+  if (averages && fieldType !== void 0 && fieldType !== "number" && fieldType !== "number[]") {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_FIELD,
+      `The engine applies the "${entry.mode}" mode to a number field alone, and "${entry.field}" is a ${fieldType} field`,
+      { field: entry.field, fieldType, mode: entry.mode }
+    );
+  }
+}
+function requireSortableFields(sort, schema, strict = false) {
   const fields = normalizeSort(sort);
   if (fields.length === 0) return;
   const flatSchema = flattenSchema(schema);
   for (const entry of fields) {
-    if (flatSchema[entry.field] !== "string") continue;
-    throw new NarsilError(
-      ErrorCodes.SEARCH_INVALID_FIELD,
-      `A sort names text field "${entry.field}" only where the schema declares it "${SORTABLE_TEXT_FIELD_TYPE}", because ordering text costs far more memory per document than ordering a number`,
-      { field: entry.field, fieldType: "string" }
-    );
+    const fieldType = flatSchema[entry.field];
+    if (strict && fieldType === void 0) throw undeclaredFieldOnStrictIndex(entry.field, "sort");
+    if (entry.direction !== "asc" && entry.direction !== "desc") {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_MODE,
+        `A sort direction is "asc" or "desc", and the direction on "${entry.field}" is "${String(entry.direction)}"`,
+        { field: entry.field, direction: String(entry.direction) }
+      );
+    }
+    requireSortMode(entry, fieldType);
+    if (fieldType === "string") {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_FIELD,
+        `The engine sorts by text field "${entry.field}" only where the schema declares it "${SORTABLE_TEXT_FIELD_TYPE}", because ordering text takes far more memory per document than ordering a number`,
+        { field: entry.field, fieldType }
+      );
+    }
+    if (isGeopointOrVectorType(fieldType)) {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_FIELD,
+        `The engine sorts by a number, boolean, enum, or sortable text field, and "${entry.field}" is a ${fieldType} field`,
+        { field: entry.field, fieldType }
+      );
+    }
   }
 }
 function applySorting(hits, sort, sortKeyOf) {
@@ -8909,7 +9419,7 @@ function applySorting(hits, sort, sortKeyOf) {
 }
 
 // src/search/cursor.ts
-var CURSOR_VERSION = 3;
+var CURSOR_VERSION = 4;
 function invalidCursor(cursor, reason) {
   const shown = cursor.length > 100 ? `${cursor.slice(0, 100)}...` : cursor;
   return new NarsilError(ErrorCodes.SEARCH_INVALID_CURSOR, `Failed to decode cursor: ${reason}`, { cursor: shown });
@@ -8949,7 +9459,7 @@ function sortSignatureOf(sort) {
       );
     }
   }
-  return JSON.stringify(fields.map((entry) => [entry.field, entry.direction]));
+  return JSON.stringify(fields.map(sortSignatureEntry));
 }
 function encodePageCursor(cursor) {
   const payload = { v: CURSOR_VERSION, a: cursor.anchor };
@@ -8959,6 +9469,7 @@ function encodePageCursor(cursor) {
   } else if (cursor.score !== null) {
     payload.s = cursor.score;
   }
+  if (cursor.depth !== void 0 && cursor.depth > 0) payload.d = cursor.depth;
   payload.q = cursor.binding;
   return encodeCursorText(JSON.stringify(payload));
 }
@@ -9004,7 +9515,7 @@ function decodePageCursor(cursor) {
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw invalidCursor(cursor, "expected an object");
   }
-  const { v, a, s, k, o, q } = parsed;
+  const { v, a, s, k, o, d, q } = parsed;
   if (v !== CURSOR_VERSION) throw invalidCursor(cursor, `unsupported cursor version ${String(v)}`);
   if (typeof q !== "string" || !/^[0-9a-f]{8}$/.test(q)) {
     throw invalidCursor(cursor, '"q" must be 8 lowercase hex digits');
@@ -9017,6 +9528,9 @@ function decodePageCursor(cursor) {
     throw invalidCursor(cursor, '"s" must be a finite number');
   }
   if (s !== void 0 && k !== void 0) throw invalidCursor(cursor, 'a cursor carries "s" or "k", never both');
+  if (d !== void 0 && (typeof d !== "number" || !Number.isSafeInteger(d) || d < 1)) {
+    throw invalidCursor(cursor, '"d" must be a positive integer');
+  }
   const sortKey = k === void 0 ? null : decodeSortKey(k, cursor);
   if (o !== void 0 && typeof o !== "string") throw invalidCursor(cursor, '"o" must be a string');
   if (sortKey === null !== (o === void 0)) {
@@ -9027,6 +9541,7 @@ function decodePageCursor(cursor) {
     score: typeof s === "number" ? s : null,
     sortKey,
     sortSignature: typeof o === "string" ? o : null,
+    depth: typeof d === "number" ? d : 0,
     binding: q
   };
 }
@@ -9104,18 +9619,21 @@ function applyPagination(results, limit, offset, binding, cursor, sort, pinnedId
   let nextCursor;
   const hasMore = afterOffset + limit < results.length;
   const lastResult = lastOrganicResult(sliced, pinnedIds);
+  const depth = afterOffset + sliced.length;
   if (hasMore && lastResult !== void 0) {
     nextCursor = sort !== void 0 ? encodePageCursor({
       anchor: lastResult.id,
       score: null,
       sortKey: sort.sortKeyOf(lastResult.id).map(toComparableSortValue),
       sortSignature: sort.signature,
+      depth,
       binding
     }) : encodePageCursor({
       anchor: lastResult.id,
       score: lastResult.score ?? null,
       sortKey: null,
       sortSignature: null,
+      depth,
       binding
     });
   }
@@ -9187,7 +9705,7 @@ function fulltextMatches(partition, params, language, schema, options) {
     prefixExpansion: prepared.prefixExpansion,
     fields: params.fields,
     tolerance: params.tolerance ?? 0,
-    prefixLength: params.prefixLength ?? 2,
+    prefixLength: params.prefixLength ?? DEFAULT_FUZZY_PREFIX_LENGTH,
     exact: params.exact ?? false,
     filterBitset: prepared.filterBitset
   });
@@ -9208,7 +9726,7 @@ function fulltextSearch(partition, params, language, schema, options) {
     fields: params.fields,
     boost: params.boost,
     tolerance: params.tolerance ?? 0,
-    prefixLength: params.prefixLength ?? 2,
+    prefixLength: params.prefixLength ?? DEFAULT_FUZZY_PREFIX_LENGTH,
     exact: params.exact ?? false,
     bm25Params: options?.bm25Params,
     globalStats: options?.globalStats,
@@ -9368,20 +9886,21 @@ async function fanOutQuery(manager, params, language, schema, config, searchOpti
   if (config.dispatcher) {
     outcomes = await dispatchWithDispatcher(partitions, params, language, schema, options, config.dispatcher);
     if (params.facets) {
-      facets = collectAndMergeFacets(outcomes, params, schema);
+      facets = collectAndMergeFacets(outcomes, params.facets, schema);
     }
   } else {
     outcomes = [];
     const partitionFacets = [];
+    const everyValue = params.facets ? everyValueFacetConfig(params.facets) : void 0;
     for (const partition of partitions) {
       const result = dispatchSinglePartition(partition, params, language, schema, options);
-      if (params.facets) {
-        partitionFacets.push(partition.computeFacets(facetMatchSetOf(result), params.facets, schema));
+      if (everyValue) {
+        partitionFacets.push(partition.computeFacets(facetMatchSetOf(result), everyValue, schema));
       }
       outcomes.push({ result, partition });
     }
     if (params.facets) {
-      facets = mergeFacets(partitionFacets);
+      facets = mergeFacets(partitionFacets, params.facets);
     }
   }
   const allScoredArrays = outcomes.map((o) => o.result.scored);
@@ -9419,14 +9938,13 @@ function dispatchWithDispatcher(partitions, params, language, schema, options, d
 function dispatchSinglePartition(partition, params, language, schema, options) {
   return fulltextSearch(partition, params, language, schema, options);
 }
-function collectAndMergeFacets(outcomes, params, schema) {
+function collectAndMergeFacets(outcomes, facetConfig, schema) {
+  const everyValue = everyValueFacetConfig(facetConfig);
   const partitionFacets = [];
   for (const outcome of outcomes) {
-    if (!params.facets) continue;
-    const facetResult = outcome.partition.computeFacets(facetMatchSetOf(outcome.result), params.facets, schema);
-    partitionFacets.push(facetResult);
+    partitionFacets.push(outcome.partition.computeFacets(facetMatchSetOf(outcome.result), everyValue, schema));
   }
-  return mergeFacets(partitionFacets);
+  return mergeFacets(partitionFacets, facetConfig);
 }
 
 // src/core/partition/frozen/memory.ts
@@ -9786,10 +10304,10 @@ function compositeSortedPage(subs, layout, request) {
   if (merged.length > request.limit) merged.length = request.limit;
   return merged;
 }
-function compositeSortValues(subs, docId, fields, fieldTypes) {
+function compositeSortValues(subs, docId, fields, fieldTypes, modes) {
   for (const sub of subs) {
     if (sub.docStore.has(docId)) {
-      return sortValuesOf(sub, docId, fields, fieldTypes);
+      return sortValuesOf(sub, docId, fields, fieldTypes, modes);
     }
   }
   return fields.map(() => null);
@@ -10014,6 +10532,7 @@ function createCompositePartition(partitionId, trackPositions = true, existingLi
       return compositeFilterMatches(subs(), layout(), filters, schema);
     },
     computeFacets(matched, config, schema) {
+      const everyValue = everyValueFacetConfig(config);
       if ("ordinalBitset" in matched) {
         const ordinalLayout = layout();
         return mergeFacets(
@@ -10021,19 +10540,23 @@ function createCompositePartition(partitionId, trackPositions = true, existingLi
             (sub, index) => computeFacets(
               sub,
               { ordinalBitset: subBitsetView(matched.ordinalBitset, ordinalLayout, index) },
-              config,
+              everyValue,
               schema
             )
-          )
+          ),
+          config
         );
       }
-      return mergeFacets(subs().map((sub) => computeFacets(sub, matched, config, schema)));
+      return mergeFacets(
+        subs().map((sub) => computeFacets(sub, matched, everyValue, schema)),
+        config
+      );
     },
     sortedPage(request) {
       return compositeSortedPage(subs(), layout(), request);
     },
-    sortValues(docId, fields, fieldTypes) {
-      return compositeSortValues(subs(), docId, fields, fieldTypes);
+    sortValues(docId, fields, fieldTypes, modes) {
+      return compositeSortValues(subs(), docId, fields, fieldTypes, modes);
     },
     suggestTerms(surfacePrefix, stemmedPrefix, limit) {
       return compositeSuggestTerms(subs(), surfacePrefix, stemmedPrefix, limit);
@@ -10337,10 +10860,10 @@ function createPartitionManager(indexName, config, language, router, initialPart
       if (pid === void 0) return void 0;
       return partitions[pid].getRef(docId);
     },
-    sortValues(docId, fields, fieldTypes) {
+    sortValues(docId, fields, fieldTypes, modes) {
       const pid = locateDocument(docId);
       if (pid === void 0) return fields.map(() => null);
-      return partitions[pid].sortValues(docId, fields, fieldTypes);
+      return partitions[pid].sortValues(docId, fields, fieldTypes, modes);
     },
     has(docId) {
       return locateDocument(docId) !== void 0;
@@ -14487,7 +15010,7 @@ function graphNeedsRebuild(state) {
   if (held === 0) return false;
   return removed / held > REBUILD_REMOVED_RATIO;
 }
-function yieldToEventLoop() {
+function yieldToEventLoop2() {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
 function* allLiveDocIds(state) {
@@ -14599,6 +15122,9 @@ function splitWorkerBudget(total) {
 async function spawnNodeWorker(_entryPoint, _resourceLimits) {
   return null;
 }
+async function nodeThreadId() {
+  return 0;
+}
 async function isNodeMainThread() {
   return true;
 }
@@ -14637,6 +15163,21 @@ function detectRuntime() {
   };
 }
 
+// src/workers/entry-point.ts
+var DIST_SEGMENT = "/dist/";
+function resolveWorkerEntry(moduleUrl, sourceDirectory, distEntry) {
+  const distIndex = moduleUrl.lastIndexOf(DIST_SEGMENT);
+  const entry = distIndex !== -1 ? new URL(distEntry, moduleUrl.slice(0, distIndex + DIST_SEGMENT.length)).href : sourceDirectory.test(moduleUrl) ? moduleUrl.replace(sourceDirectory, `${DIST_SEGMENT}${distEntry}`) : null;
+  return entry === moduleUrl ? null : entry;
+}
+function missingWorkerEntry(moduleUrl) {
+  return new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `The engine finds no worker entry beside its own module at "${moduleUrl}", which happens where a bundler folds @delali/narsil into an application bundle. Keep @delali/narsil outside the bundle, or set workers.enabled to false`,
+    { moduleUrl }
+  );
+}
+
 // src/workers/resource-limits.ts
 function workerResourceLimits() {
   return { maxYoungGenerationSizeMb: WORKER_YOUNG_GENERATION_MB };
@@ -14644,14 +15185,10 @@ function workerResourceLimits() {
 
 // src/vector/search-pool/spawn.ts
 function resolveWorkerEntryPoint() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("vector/search-worker.mjs", base.slice(0, distIndex + 6)).href;
-  }
-  return base.replace(/\/src\/vector\/search-pool\/[^/]+$/, "/dist/vector/search-worker.mjs");
+  return resolveWorkerEntry(import.meta.url, /\/src\/vector\/search-pool\/[^/]+$/, "vector/search-worker.mjs");
 }
 async function spawnWorker(entryPoint) {
+  if (entryPoint === null) return null;
   const runtime = detectRuntime();
   if (runtime.supportsWorkerThreads) {
     try {
@@ -15243,7 +15780,7 @@ async function insertLocally(state, graph, docIds, admit) {
     state.buffer.delete(docId);
     count += 1;
     if (count % BUILD_CHUNK_SIZE === 0) {
-      await yieldToEventLoop();
+      await yieldToEventLoop2();
     }
   }
   return !state.disposed;
@@ -15274,7 +15811,7 @@ async function releaseLocations(state, paths, locations) {
   let count = 0;
   for (const [docId, location] of locations) {
     if (count > 0 && count % DISK_ADOPTION_YIELD_INTERVAL === 0) {
-      await yieldToEventLoop();
+      await yieldToEventLoop2();
       if (state.disposed) return;
     }
     count += 1;
@@ -15409,7 +15946,7 @@ function bytesToVectors(bytes) {
   for (let i = 0; i < vectors.length; i++) vectors[i] = view.getFloat32(i * 4, true);
   return vectors;
 }
-function invalid(message, details) {
+function invalid2(message, details) {
   throw new NarsilError(ErrorCodes.PERSISTENCE_LOAD_FAILED, `Invalid vector index payload: ${message}`, details);
 }
 function isRecord(value) {
@@ -15423,20 +15960,20 @@ function isSerializedGraph(value) {
 }
 function codesOf(raw, dimension, count) {
   if (raw === null || raw === void 0) return null;
-  if (!isRecord(raw)) invalid("codes must be a map or nil");
+  if (!isRecord(raw)) invalid2("codes must be a map or nil");
   const bits = raw.bits;
-  if (bits !== 1 && bits !== 2 && bits !== 4 && bits !== 8) invalid("codes.bits must be 8, 4, 2, or 1", { bits });
+  if (bits !== 1 && bits !== 2 && bits !== 4 && bits !== 8) invalid2("codes.bits must be 8, 4, 2, or 1", { bits });
   if (!Array.isArray(raw.centroid) || raw.centroid.length !== dimension) {
-    invalid("codes.centroid must hold one number per dimension");
+    invalid2("codes.centroid must hold one number per dimension");
   }
-  if (!(raw.records instanceof Uint8Array)) invalid("codes.records must be bytes");
+  if (!(raw.records instanceof Uint8Array)) invalid2("codes.records must be bytes");
   if (raw.records.byteLength !== count * osqRecordBytes(dimension, bits)) {
-    invalid("codes.records must hold one record per vector", { count, bytes: raw.records.byteLength });
+    invalid2("codes.records must hold one record per vector", { count, bytes: raw.records.byteLength });
   }
   return { bits, centroid: raw.centroid.map(Number), records: raw.records };
 }
 function decodeVectorIndexPart(raw) {
-  if (!isRecord(raw)) invalid("payload must be a map");
+  if (!isRecord(raw)) invalid2("payload must be a map");
   if (raw.v !== VECTOR_INDEX_PAYLOAD_VERSION) {
     throw new NarsilError(
       ErrorCodes.ENVELOPE_VERSION_MISMATCH,
@@ -15444,24 +15981,24 @@ function decodeVectorIndexPart(raw) {
       { version: raw.v ?? 1 }
     );
   }
-  if (typeof raw.fieldName !== "string") invalid("fieldName must be a string");
-  if (!isNonNegativeInteger2(raw.dimension) || raw.dimension === 0) invalid("dimension must be a positive integer");
-  if (!isNonNegativeInteger2(raw.part)) invalid("part must be a non-negative integer");
+  if (typeof raw.fieldName !== "string") invalid2("fieldName must be a string");
+  if (!isNonNegativeInteger2(raw.dimension) || raw.dimension === 0) invalid2("dimension must be a positive integer");
+  if (!isNonNegativeInteger2(raw.part)) invalid2("part must be a non-negative integer");
   if (!isNonNegativeInteger2(raw.parts) || raw.parts === 0 || raw.part >= raw.parts) {
-    invalid("parts must exceed part", { part: raw.part, parts: raw.parts });
+    invalid2("parts must exceed part", { part: raw.part, parts: raw.parts });
   }
   if (!Array.isArray(raw.docIds) || !raw.docIds.every((docId) => typeof docId === "string")) {
-    invalid("docIds must be a list of strings");
+    invalid2("docIds must be a list of strings");
   }
   if (raw.docIds.length > VECTOR_INDEX_PART_VECTORS) {
-    invalid(`a part holds at most ${VECTOR_INDEX_PART_VECTORS} vectors`, { count: raw.docIds.length });
+    invalid2(`a part holds at most ${VECTOR_INDEX_PART_VECTORS} vectors`, { count: raw.docIds.length });
   }
   if (!Array.isArray(raw.graphs) || !raw.graphs.every(isSerializedGraph)) {
-    invalid("graphs must be a list of graphs, each holding a list of nodes");
+    invalid2("graphs must be a list of graphs, each holding a list of nodes");
   }
-  if (!(raw.vectors instanceof Uint8Array)) invalid("vectors must be bytes");
+  if (!(raw.vectors instanceof Uint8Array)) invalid2("vectors must be bytes");
   if (raw.vectors.byteLength !== raw.docIds.length * raw.dimension * 4) {
-    invalid("vectors must hold dimension float32 components per document", {
+    invalid2("vectors must hold dimension float32 components per document", {
       count: raw.docIds.length,
       bytes: raw.vectors.byteLength
     });
@@ -15479,7 +16016,7 @@ function decodeVectorIndexPart(raw) {
   };
 }
 function decodeVectorIndexParts(raw) {
-  if (!Array.isArray(raw)) invalid("a field must carry a list of parts");
+  if (!Array.isArray(raw)) invalid2("a field must carry a list of parts");
   return raw.map(decodeVectorIndexPart);
 }
 
@@ -15488,7 +16025,7 @@ var VECTOR_FILE_PAYLOAD_VERSION = 1;
 var VECTOR_GRAPH_PAYLOAD_VERSION = 1;
 var VECTOR_FILE_MAX_VECTORS = VECTOR_INDEX_PART_VECTORS;
 var METRICS = ["cosine", "dotProduct", "euclidean"];
-function invalid2(payload, message, details) {
+function invalid3(payload, message, details) {
   throw new NarsilError(ErrorCodes.PERSISTENCE_LOAD_FAILED, `Invalid ${payload} payload: ${message}`, details);
 }
 function isRecord2(value) {
@@ -15507,19 +16044,19 @@ function requireVersion(payload, found, expected) {
 }
 function decodeVectorFilePayload(raw) {
   const name = "vector file";
-  if (!isRecord2(raw)) invalid2(name, "payload must be a map");
+  if (!isRecord2(raw)) invalid3(name, "payload must be a map");
   requireVersion(name, raw.v, VECTOR_FILE_PAYLOAD_VERSION);
-  if (typeof raw.fieldName !== "string") invalid2(name, "fieldName must be a string");
-  if (!isIntegerUpTo(raw.dimension, 65535) || raw.dimension === 0) invalid2(name, "dimension must be a positive uint16");
+  if (typeof raw.fieldName !== "string") invalid3(name, "fieldName must be a string");
+  if (!isIntegerUpTo(raw.dimension, 65535) || raw.dimension === 0) invalid3(name, "dimension must be a positive uint16");
   if (!Array.isArray(raw.docIds) || !raw.docIds.every((docId) => typeof docId === "string")) {
-    invalid2(name, "docIds must be a list of strings");
+    invalid3(name, "docIds must be a list of strings");
   }
   if (raw.docIds.length > VECTOR_FILE_MAX_VECTORS) {
-    invalid2(name, `a file holds at most ${VECTOR_FILE_MAX_VECTORS} vectors`, { count: raw.docIds.length });
+    invalid3(name, `a file holds at most ${VECTOR_FILE_MAX_VECTORS} vectors`, { count: raw.docIds.length });
   }
-  if (!(raw.vectors instanceof Uint8Array)) invalid2(name, "vectors must be bytes");
+  if (!(raw.vectors instanceof Uint8Array)) invalid3(name, "vectors must be bytes");
   if (raw.vectors.byteLength !== raw.docIds.length * raw.dimension * 4) {
-    invalid2(name, "vectors must hold dimension float32 components per document", {
+    invalid3(name, "vectors must hold dimension float32 components per document", {
       count: raw.docIds.length,
       bytes: raw.vectors.byteLength
     });
@@ -15538,16 +16075,16 @@ function isMetric(value) {
 }
 function decodeNumberedGraph(raw) {
   const name = "vector graph";
-  if (!isRecord2(raw)) invalid2(name, "each graph must be a map");
+  if (!isRecord2(raw)) invalid3(name, "each graph must be a map");
   const entryPoint = raw.entryPoint ?? null;
   if (entryPoint !== null && !isIntegerUpTo(entryPoint, 4294967295))
-    invalid2(name, "entryPoint must be a uint32 or nil");
-  if (!isIntegerUpTo(raw.maxLayer, 255)) invalid2(name, "maxLayer must be a uint8");
-  if (!isIntegerUpTo(raw.m, 65535) || raw.m === 0) invalid2(name, "m must be a positive uint16");
-  if (!isIntegerUpTo(raw.efConstruction, 65535)) invalid2(name, "efConstruction must be a uint16");
-  if (!isMetric(raw.metric)) invalid2(name, "metric must name a supported metric", { metric: raw.metric });
-  if (!(raw.levels instanceof Uint8Array)) invalid2(name, "levels must be bytes");
-  if (!(raw.neighbours instanceof Uint8Array)) invalid2(name, "neighbours must be bytes");
+    invalid3(name, "entryPoint must be a uint32 or nil");
+  if (!isIntegerUpTo(raw.maxLayer, 255)) invalid3(name, "maxLayer must be a uint8");
+  if (!isIntegerUpTo(raw.m, 65535) || raw.m === 0) invalid3(name, "m must be a positive uint16");
+  if (!isIntegerUpTo(raw.efConstruction, 65535)) invalid3(name, "efConstruction must be a uint16");
+  if (!isMetric(raw.metric)) invalid3(name, "metric must name a supported metric", { metric: raw.metric });
+  if (!(raw.levels instanceof Uint8Array)) invalid3(name, "levels must be bytes");
+  if (!(raw.neighbours instanceof Uint8Array)) invalid3(name, "neighbours must be bytes");
   return {
     entryPoint,
     maxLayer: raw.maxLayer,
@@ -15560,10 +16097,10 @@ function decodeNumberedGraph(raw) {
 }
 function decodeVectorGraphPayload(raw) {
   const name = "vector graph";
-  if (!isRecord2(raw)) invalid2(name, "payload must be a map");
+  if (!isRecord2(raw)) invalid3(name, "payload must be a map");
   requireVersion(name, raw.v, VECTOR_GRAPH_PAYLOAD_VERSION);
-  if (typeof raw.fieldName !== "string") invalid2(name, "fieldName must be a string");
-  if (!Array.isArray(raw.graphs)) invalid2(name, "graphs must be a list");
+  if (typeof raw.fieldName !== "string") invalid3(name, "fieldName must be a string");
+  if (!Array.isArray(raw.graphs)) invalid3(name, "graphs must be a list");
   return { v: VECTOR_GRAPH_PAYLOAD_VERSION, fieldName: raw.fieldName, graphs: raw.graphs.map(decodeNumberedGraph) };
 }
 
@@ -16313,6 +16850,18 @@ function* filteredDocIds(state, filter) {
     if (docId !== void 0) yield docId;
   }
 }
+function admittedTotal(state, filter) {
+  return filter === void 0 ? liveSize(state) : filter.count;
+}
+function fetchedOutcome(state, results, minSimilarity, filter) {
+  if (minSimilarity === Number.NEGATIVE_INFINITY) {
+    return { results, matched: admittedTotal(state, filter), matchedExact: true };
+  }
+  return { results, matched: results.length, matchedExact: false };
+}
+function scannedOutcome(scan2) {
+  return { results: scan2.results, matched: scan2.matched, matchedExact: true };
+}
 function highScoreFirst(a, b) {
   return b.score - a.score || compareCodePoints(a.docId, b.docId);
 }
@@ -16332,12 +16881,15 @@ function scanThroughTheCore(state, query, k, metric, minSimilarity, scanned) {
   const distances = nativeScoresOf(state.store.handles, query, metric, scanned.ordinals);
   if (distances === null) return null;
   const heap = createBoundedMaxHeap(highScoreFirst, k);
+  let matched = 0;
   for (let i = 0; i < scanned.ordinals.length; i++) {
     if (distances[i] === Number.POSITIVE_INFINITY) continue;
     const score = toScore(distances[i], metric);
-    if (score >= minSimilarity) heap.push({ docId: scanned.docIds[i], score });
+    if (score < minSimilarity) continue;
+    matched++;
+    heap.push({ docId: scanned.docIds[i], score });
   }
-  return heap.toSortedArray().reverse();
+  return { results: heap.toSortedArray().reverse(), matched };
 }
 function bruteForceSearch(state, query, k, metric, minSimilarity, candidates) {
   const scanned = liveCandidates(state, candidates);
@@ -16346,6 +16898,7 @@ function bruteForceSearch(state, query, k, metric, minSimilarity, candidates) {
   const arenaQuery = state.store.prepareQueryArena(query);
   const queryMag = arenaQuery ? arenaQuery.magnitude : magnitude(query);
   const heap = createBoundedMaxHeap(highScoreFirst, k);
+  let matched = 0;
   for (let i = 0; i < scanned.docIds.length; i++) {
     const docId = scanned.docIds[i];
     let score;
@@ -16370,11 +16923,11 @@ function bruteForceSearch(state, query, k, metric, minSimilarity, candidates) {
         }
       }
     }
-    if (score >= minSimilarity) {
-      heap.push({ docId, score });
-    }
+    if (score < minSimilarity) continue;
+    matched++;
+    heap.push({ docId, score });
   }
-  return heap.toSortedArray().reverse();
+  return { results: heap.toSortedArray().reverse(), matched };
 }
 function mergeResults(hnswResults, bufferResults, k) {
   const seen = /* @__PURE__ */ new Set();
@@ -16420,32 +16973,38 @@ function searchWithFilter(state, query, k, options, filter) {
     );
   }
   const currentLiveSize = liveSize(state);
-  if (currentLiveSize === 0) return [];
-  if (k <= 0) return [];
+  const { metric, minSimilarity, efSearch, oversample } = options;
+  if (currentLiveSize === 0) return { results: [], matched: 0, matchedExact: true };
+  if (filter && filter.count === 0) return { results: [], matched: 0, matchedExact: true };
+  if (k <= 0) return fetchedOutcome(state, [], minSimilarity, filter);
   if (state.buffer.size > 0 && !state.building && !state.buildScheduled) {
     scheduleBuild(state);
   }
-  const { metric, minSimilarity, efSearch, oversample } = options;
-  if (filter && filter.count === 0) return [];
   if (!state.hnsw) {
     const candidates = filter ? filteredDocIds(state, filter) : allLiveDocIds(state);
-    return bruteForceSearch(state, query, k, metric, minSimilarity, candidates);
+    return scannedOutcome(bruteForceSearch(state, query, k, metric, minSimilarity, candidates));
   }
   if (filter) {
     const hnswLiveSize = state.hnsw.size;
     const selectivity = hnswLiveSize > 0 ? filter.count / hnswLiveSize : 1;
     if (selectivity < state.filterThreshold) {
-      return bruteForceSearch(state, query, k, metric, minSimilarity, filteredDocIds(state, filter));
+      const scan2 = bruteForceSearch(state, query, k, metric, minSimilarity, filteredDocIds(state, filter));
+      return scannedOutcome(scan2);
     }
   }
   const graphOptions = { filter, efSearch, oversample };
   if (state.buffer.size === 0) {
     const hnswResults2 = state.hnsw.search(query, k, metric, minSimilarity, graphOptions);
-    return hnswResults2.map((r) => ({ docId: r.docId, score: r.score }));
+    return fetchedOutcome(
+      state,
+      hnswResults2.map((r) => ({ docId: r.docId, score: r.score })),
+      minSimilarity,
+      filter
+    );
   }
   const hnswResults = state.hnsw.search(query, k, metric, minSimilarity, graphOptions).map((r) => ({ docId: r.docId, score: r.score }));
-  const bufferResults = bruteForceSearch(state, query, k, metric, minSimilarity, bufferCandidates(state, filter));
-  return mergeResults(hnswResults, bufferResults, k);
+  const buffered = bruteForceSearch(state, query, k, metric, minSimilarity, bufferCandidates(state, filter));
+  return fetchedOutcome(state, mergeResults(hnswResults, buffered.results, k), minSimilarity, filter);
 }
 
 // src/vector/vector-index/index.ts
@@ -16620,7 +17179,7 @@ function createVectorIndex(fieldName, dimension, config, workerCopies = VECTOR_W
       efSearch: options.efSearch,
       oversample: options.oversample
     });
-    if (viaWorkerCopy !== null) return viaWorkerCopy;
+    if (viaWorkerCopy !== null) return fetchedOutcome(state, viaWorkerCopy, options.minSimilarity, filter);
     if (confined && state.revision !== filterRevision) {
       filter = filterForOptions(state, options);
     }
@@ -18611,20 +19170,26 @@ function bruteForceOrdinals(state, docIdOf, query, k, metric, minSimilarity, fil
   }
   const distances = nativeScoresOf(state.store.handles, query, metric, ordinals) ?? distancesInTypeScript(state, query, metric, ordinals);
   const heap = createBoundedMaxHeap(bestFirst2, k);
+  let matched = 0;
   for (let i = 0; i < ordinals.length; i++) {
     if (distances[i] === Number.POSITIVE_INFINITY) continue;
     const score = toScore(distances[i], metric);
-    if (score >= minSimilarity) heap.push({ ord: ordinals[i], score, docId: docIds[i] });
+    if (score < minSimilarity) continue;
+    matched++;
+    heap.push({ ord: ordinals[i], score, docId: docIds[i] });
   }
-  return heap.toSortedArray().reverse();
+  return { hits: heap.toSortedArray().reverse(), matched, matchedExact: true };
 }
 function createSharedVectorSearcher(options) {
   const { fieldName, view, holdsDocument } = options;
   function filterForDocIds(allowed) {
     const filter = createOrdinalFilter(view.store.slots);
+    const graph = view.graph;
     for (const docId of allowed) {
       const ordinal = view.ordinalOf(docId);
-      if (ordinal !== void 0) addToOrdinalFilter(filter, ordinal);
+      if (ordinal === void 0) continue;
+      if (graph !== null && isTombstoned(graph, ordinal)) continue;
+      addToOrdinalFilter(filter, ordinal);
     }
     return filter;
   }
@@ -18651,7 +19216,11 @@ function createSharedVectorSearcher(options) {
     if (graph !== null && filter !== void 0 && liveSize2 > 0 && filter.count / liveSize2 < view.handles.filterThreshold) {
       return bruteForceOrdinals(graph, view.docIdOf, query, k, metric, minSimilarity, filter);
     }
-    return view.searchOrdinals(query, k, metric, minSimilarity, { filter, efSearch, oversample });
+    const hits = view.searchOrdinals(query, k, metric, minSimilarity, { filter, efSearch, oversample });
+    if (minSimilarity === Number.NEGATIVE_INFINITY) {
+      return { hits, matched: filter === void 0 ? liveSize2 : filter.count, matchedExact: true };
+    }
+    return { hits, matched: hits.length, matchedExact: false };
   }
   return {
     fieldName,
@@ -18667,15 +19236,22 @@ function createSharedVectorSearcher(options) {
         );
       }
       const filter = filterFor(searchOptions);
-      if (filter !== void 0 && filter.count === 0) return Promise.resolve([]);
-      const hits = hitsFor(query, k, searchOptions, filter);
+      if (filter !== void 0 && filter.count === 0) {
+        return Promise.resolve({ results: [], matched: 0, matchedExact: true });
+      }
+      const scanned = hitsFor(query, k, searchOptions, filter);
       const results = [];
-      for (const hit of hits) {
+      for (const hit of scanned.hits) {
         const docId = view.docIdOf(hit.ord);
         if (docId === void 0 || !holdsDocument(docId)) continue;
         results.push({ docId, score: hit.score });
       }
-      return Promise.resolve(results);
+      const holdsEveryHit = results.length === scanned.hits.length;
+      return Promise.resolve({
+        results,
+        matched: scanned.matched,
+        matchedExact: scanned.matchedExact && holdsEveryHit
+      });
     }
   };
 }
@@ -18802,7 +19378,7 @@ function closeHeldVectorCopies(held) {
   held.fields.clear();
   held.searchers.clear();
 }
-function yieldToEventLoop2() {
+function yieldToEventLoop3() {
   return new Promise((resolve) => {
     if (typeof setImmediate === "function") setImmediate(resolve);
     else setTimeout(resolve, 0);
@@ -18813,7 +19389,7 @@ async function insertIntoHeldGraph(held, fieldName, handle, ordinals) {
   if (field === void 0) return null;
   for (const ordinal of ordinals) {
     field.view.insertOrdinal(ordinal);
-    await yieldToEventLoop2();
+    await yieldToEventLoop3();
   }
   return field.view.takeOutcome();
 }
@@ -19101,7 +19677,7 @@ function emitEngineEvent(eventHandlers, event, payload) {
 }
 
 // src/engine/analysis-rebuild.ts
-function yieldToEventLoop3() {
+function yieldToEventLoop4() {
   return new Promise((resolve) => {
     setTimeout(resolve, 0);
   });
@@ -19142,7 +19718,7 @@ function createAnalysisRebuildCoordinator(config, deps) {
       for (let partitionId = 0; partitionId < manager.partitionCount; partitionId += 1) {
         manager.rebuildTextIndex(partitionId);
         entry.partitionsRebuilt = partitionId + 1;
-        await yieldToEventLoop3();
+        await yieldToEventLoop4();
       }
       stale.delete(indexName);
       await deps.persistAnalysisRevision(indexName);
@@ -19321,6 +19897,10 @@ function resolveDurabilityTier(config) {
 var DEFAULT_CHECKPOINT_INTERVAL_MS = 3e5;
 var DEFAULT_CHECKPOINT_MUTATION_THRESHOLD = 1e5;
 var DEFAULT_ASYNC_FLUSH_INTERVAL_MS = 1e3;
+var DIRECTORY_IDENTITY_CHECK_INTERVAL_MS = 1e3;
+var DIRECTORY_LOCK_ATTEMPTS = 3;
+var DIRECTORY_LOCK_SETTLE_MS = 50;
+var DIRECTORY_LOCK_PROCESS_START_TOLERANCE_MS = 1e3;
 var DEFAULT_SEGMENT_MAX_BYTES = 67108864;
 var DEFAULT_COMPACTION_THRESHOLD = 12;
 var COMPACTION_LARGEST_MERGED_DOCUMENT_COUNT = 2e5;
@@ -19346,35 +19926,192 @@ async function getPath() {
   return filesystemUnavailable2();
 }
 
-// src/persistence/durability/durable-filesystem.ts
-function validateRelativeKey(key) {
-  if (key.length === 0) {
-    throw new NarsilError(ErrorCodes.PERSISTENCE_SAVE_FAILED, "Invalid key: empty");
+// src/persistence/durability/directory-lock.ts
+var LOCK_FILE_NAME = ".narsil.lock";
+var HARD_LINK_UNSUPPORTED_CODES = /* @__PURE__ */ new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+var lockedDirectories = /* @__PURE__ */ new Set();
+function errnoOf(err) {
+  return err?.code;
+}
+function processIsRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return errnoOf(err) === "EPERM";
   }
-  if (key.includes("\0")) {
-    throw new NarsilError(ErrorCodes.PERSISTENCE_SAVE_FAILED, "Invalid key: null byte detected", { key });
+}
+function integerOrNull(text) {
+  const value = Number.parseInt(text ?? "", 10);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function parseHolder(text) {
+  const [pidText, threadText, startText, nonceText] = text.split("\n");
+  const pid = integerOrNull(pidText);
+  if (pid === null || pid <= 0) return null;
+  const nonce = nonceText?.trim() ?? "";
+  return {
+    pid,
+    threadId: integerOrNull(threadText),
+    processStartMs: integerOrNull(startText),
+    nonce: nonce.length > 0 ? nonce : null
+  };
+}
+function formatHolder(holder) {
+  return `${holder.pid}
+${holder.threadId ?? ""}
+${holder.processStartMs ?? ""}
+${holder.nonce ?? ""}
+`;
+}
+async function readHolder(fs, lockPath) {
+  try {
+    return parseHolder(await fs.readFile(lockPath, "utf8")) ?? "unreadable";
+  } catch (err) {
+    if (errnoOf(err) === "ENOENT") return "absent";
+    throw err;
   }
 }
-function wrapFsyncError(err, key) {
-  throw new NarsilError(
-    ErrorCodes.PERSISTENCE_FSYNC_FAILED,
-    `fsync failed for "${key}"; the write is not acknowledged and the node must recover from the durable log`,
-    { key, cause: err instanceof Error ? err.message : String(err) }
+async function settledHolder(fs, lockPath) {
+  const first = await readHolder(fs, lockPath);
+  if (first !== "unreadable") return first;
+  await new Promise((resolve) => setTimeout(resolve, DIRECTORY_LOCK_SETTLE_MS));
+  return readHolder(fs, lockPath);
+}
+function holderIsLive(holder, self) {
+  if (holder.pid !== self.pid) return processIsRunning(holder.pid);
+  if (holder.processStartMs === null || self.processStartMs === null) return false;
+  return Math.abs(holder.processStartMs - self.processStartMs) <= DIRECTORY_LOCK_PROCESS_START_TOLERANCE_MS;
+}
+function heldElsewhere(root, holder, lockPath) {
+  return new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `The durability directory "${root}" is in use by ${holder}, and only one engine may write a write-ahead log directory. Point this engine at another directory, or shut the other engine down first. Where no engine uses the directory, delete "${lockPath}"`,
+    { directory: root }
   );
 }
-async function openReadWriteCreating(filePath, fs) {
+function holderLabel(holder, self) {
+  if (holder.pid !== self.pid) return `process ${holder.pid}`;
+  return holder.threadId === self.threadId ? "another copy of Narsil in this thread" : "another thread of this process";
+}
+async function createLockFileExclusively(fs, lockPath, content) {
   try {
-    return await fs.open(filePath, "r+");
+    await fs.writeFile(lockPath, content, { flag: "wx" });
+    return true;
   } catch (err) {
-    if (err.code !== "ENOENT") {
-      throw err;
-    }
+    if (errnoOf(err) === "EEXIST") return false;
+    throw err;
   }
+}
+async function createLockFile(fs, lockPath, draftPath, content) {
+  await fs.writeFile(draftPath, content, { flag: "w" });
   try {
-    return await fs.open(filePath, "wx+");
+    await fs.link(draftPath, lockPath);
+    return true;
   } catch (err) {
-    if (err.code !== "EEXIST") {
-      throw err;
+    const code = errnoOf(err);
+    if (code === "EEXIST") return false;
+    if (code !== void 0 && HARD_LINK_UNSUPPORTED_CODES.has(code)) {
+      return createLockFileExclusively(fs, lockPath, content);
+    }
+    throw err;
+  } finally {
+    await fs.unlink(draftPath).catch(() => void 0);
+  }
+}
+async function acquire(fs, root, lockPath, self) {
+  const draftPath = `${lockPath}.${self.pid}.${self.threadId ?? 0}`;
+  const content = formatHolder(self);
+  for (let attempt = 0; attempt < DIRECTORY_LOCK_ATTEMPTS; attempt++) {
+    if (await createLockFile(fs, lockPath, draftPath, content)) return;
+    const holder = await settledHolder(fs, lockPath);
+    if (typeof holder === "object" && holderIsLive(holder, self)) {
+      throw heldElsewhere(root, holderLabel(holder, self), lockPath);
+    }
+    await fs.unlink(lockPath).catch((err) => {
+      if (errnoOf(err) !== "ENOENT") throw err;
+    });
+  }
+  throw heldElsewhere(root, "another process", lockPath);
+}
+async function describeSelf() {
+  return {
+    pid: process.pid,
+    threadId: await nodeThreadId(),
+    processStartMs: Math.round(Date.now() - process.uptime() * 1e3),
+    nonce: globalThis.crypto.randomUUID()
+  };
+}
+async function lockDirectory(root) {
+  const fs = await getFs();
+  const pathMod = await getPath();
+  const resolvedRoot = pathMod.resolve(root);
+  const lockPath = pathMod.join(resolvedRoot, LOCK_FILE_NAME);
+  const self = await describeSelf();
+  let directoryKey = null;
+  try {
+    await fs.mkdir(resolvedRoot, { recursive: true });
+    const stat = await fs.stat(resolvedRoot, { bigint: true });
+    const key = `${stat.dev}:${stat.ino}`;
+    if (lockedDirectories.has(key)) throw heldElsewhere(root, "another engine in this process", lockPath);
+    lockedDirectories.add(key);
+    directoryKey = key;
+    await acquire(fs, root, lockPath, self);
+  } catch (err) {
+    if (directoryKey !== null) lockedDirectories.delete(directoryKey);
+    if (err instanceof NarsilError) throw err;
+    throw new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The engine cannot lock the durability directory "${root}"`,
+      { directory: root, cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const heldKey = directoryKey;
+  let released = false;
+  async function holds() {
+    const holder = await readHolder(fs, lockPath);
+    return typeof holder === "object" && holder.nonce === self.nonce;
+  }
+  return {
+    holds,
+    async release() {
+      if (released) return;
+      released = true;
+      lockedDirectories.delete(heldKey);
+      if (await holds().catch(() => false)) await fs.unlink(lockPath).catch(() => void 0);
+    }
+  };
+}
+
+// src/persistence/durability/durable-filesystem.ts
+function validateRelativeKey(key) {
+  if (key.length === 0) {
+    throw new NarsilError(ErrorCodes.PERSISTENCE_SAVE_FAILED, "Invalid key: empty");
+  }
+  if (key.includes("\0")) {
+    throw new NarsilError(ErrorCodes.PERSISTENCE_SAVE_FAILED, "Invalid key: null byte detected", { key });
+  }
+}
+function wrapFsyncError(err, key) {
+  throw new NarsilError(
+    ErrorCodes.PERSISTENCE_FSYNC_FAILED,
+    `fsync failed for "${key}"; the write is not acknowledged and the node must recover from the durable log`,
+    { key, cause: err instanceof Error ? err.message : String(err) }
+  );
+}
+async function openReadWriteCreating(filePath, fs) {
+  try {
+    return await fs.open(filePath, "r+");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+  try {
+    return await fs.open(filePath, "wx+");
+  } catch (err) {
+    if (err.code !== "EEXIST") {
+      throw err;
     }
     return fs.open(filePath, "r+");
   }
@@ -19431,6 +20168,20 @@ function createDurableDirectory(root) {
     get root() {
       return root;
     },
+    lock() {
+      return lockDirectory(root);
+    },
+    async identity() {
+      const fs = await getFs();
+      const pathMod = await getPath();
+      try {
+        const stat = await fs.stat(pathMod.resolve(root), { bigint: true });
+        return `${stat.dev}:${stat.ino}`;
+      } catch (err) {
+        if (err.code === "ENOENT") return null;
+        throw err;
+      }
+    },
     async appendHandle(key) {
       const { path: filePath, pathMod } = await resolve(key);
       const fs = await getFs();
@@ -19662,22 +20413,20 @@ async function isOnMainThread() {
   }
   return onMainThread;
 }
-function resolveWorkerEntryPoint2() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("serialization/crc32-worker.mjs", base.slice(0, distIndex + 6)).href;
-  }
-  return base.replace(/\/src\/serialization\/[^/]+$/, "/dist/serialization/crc32-worker.mjs");
-}
 async function spawnWorker2() {
+  const entryPoint = resolveWorkerEntry(
+    import.meta.url,
+    /\/src\/serialization\/[^/]+$/,
+    "serialization/crc32-worker.mjs"
+  );
+  if (entryPoint === null) return null;
   try {
-    return await spawnNodeWorker(new URL(resolveWorkerEntryPoint2()));
+    return await spawnNodeWorker(new URL(entryPoint));
   } catch {
     return null;
   }
 }
-function yieldToEventLoop4() {
+function yieldToEventLoop5() {
   if (typeof setImmediate === "function") {
     return new Promise((resolve) => setImmediate(resolve));
   }
@@ -19689,7 +20438,7 @@ async function advanceChecksum(start, payload) {
     const end = Math.min(offset + CHECKSUM_YIELD_CHUNK_BYTES, payload.length);
     state = crc32Update(state, payload.subarray(offset, end));
     if (end < payload.length) {
-      await yieldToEventLoop4();
+      await yieldToEventLoop5();
     }
   }
   return state;
@@ -20967,7 +21716,7 @@ function attachDocuments(manager, partitionId, segment) {
   }
   manager.attachFrozenSegment(partitionId, createSharedFrozenSegment(snapshot));
 }
-function yieldToEventLoop5() {
+function yieldToEventLoop6() {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
 async function loadPartitionSegmentBySegment(directory, partition, manager) {
@@ -20977,12 +21726,12 @@ async function loadPartitionSegmentBySegment(directory, partition, manager) {
     addSegmentSchema(agreedSchema, segment.schema);
     removeWhatTheSegmentReplaces(manager, segment);
     attachDocuments(manager, partition.partitionId, segment);
-    await yieldToEventLoop5();
+    await yieldToEventLoop6();
   }
 }
 
 // src/persistence/durability/segment/manifest-vectors-decode.ts
-function invalid3(message, details) {
+function invalid4(message, details) {
   throw new NarsilError(ErrorCodes.PERSISTENCE_LOAD_FAILED, `Segment manifest ${message}`, details);
 }
 function isRecord3(value) {
@@ -20995,19 +21744,19 @@ function isKey(value) {
   return typeof value === "string" && value.length > 0 && !value.includes("\0");
 }
 function normalizeFile(raw, fieldPath, nextFileId, seenIds) {
-  if (!isRecord3(raw) || !isId(raw.id) || !isKey(raw.key)) invalid3("has an invalid vector file reference", { fieldPath });
+  if (!isRecord3(raw) || !isId(raw.id) || !isKey(raw.key)) invalid4("has an invalid vector file reference", { fieldPath });
   if (raw.id >= nextFileId || seenIds.has(raw.id)) {
-    invalid3(`lists vector file ${raw.id} of "${fieldPath}" twice or at its next file id`, { fieldPath, id: raw.id });
+    invalid4(`lists vector file ${raw.id} of "${fieldPath}" twice or at its next file id`, { fieldPath, id: raw.id });
   }
   seenIds.add(raw.id);
   const count = raw.count;
   if (typeof count !== "number" || !Number.isInteger(count) || count < 0 || count > VECTOR_FILE_MAX_VECTORS) {
-    invalid3(`gives vector file ${raw.id} of "${fieldPath}" an invalid count`, { fieldPath, id: raw.id, count });
+    invalid4(`gives vector file ${raw.id} of "${fieldPath}" an invalid count`, { fieldPath, id: raw.id, count });
   }
   const dead = raw.dead ?? null;
-  if (dead !== null && !(dead instanceof Uint8Array)) invalid3("has dead vectors that are not bytes", { fieldPath });
+  if (dead !== null && !(dead instanceof Uint8Array)) invalid4("has dead vectors that are not bytes", { fieldPath });
   if (dead !== null && dead.byteLength !== deadBytesFor(count)) {
-    invalid3(`marks the dead vectors of file ${raw.id} of "${fieldPath}" with the wrong number of bytes`, {
+    invalid4(`marks the dead vectors of file ${raw.id} of "${fieldPath}" with the wrong number of bytes`, {
       fieldPath,
       id: raw.id,
       count,
@@ -21017,17 +21766,17 @@ function normalizeFile(raw, fieldPath, nextFileId, seenIds) {
   return { id: raw.id, key: raw.key, count, dead };
 }
 function normalizeField(raw, seenFields) {
-  if (!isRecord3(raw) || typeof raw.fieldPath !== "string") invalid3("has an invalid vector reference", { vector: raw });
+  if (!isRecord3(raw) || typeof raw.fieldPath !== "string") invalid4("has an invalid vector reference", { vector: raw });
   const fieldPath = raw.fieldPath;
-  if (seenFields.has(fieldPath)) invalid3(`lists the vector field "${fieldPath}" twice`, { fieldPath });
+  if (seenFields.has(fieldPath)) invalid4(`lists the vector field "${fieldPath}" twice`, { fieldPath });
   seenFields.add(fieldPath);
-  if (!isId(raw.nextFileId)) invalid3(`gives "${fieldPath}" an invalid next file id`, { fieldPath });
-  if (!Array.isArray(raw.files)) invalid3(`gives "${fieldPath}" no list of vector files`, { fieldPath });
-  if (!isId(raw.graphGeneration)) invalid3(`gives "${fieldPath}" an invalid graph generation`, { fieldPath });
+  if (!isId(raw.nextFileId)) invalid4(`gives "${fieldPath}" an invalid next file id`, { fieldPath });
+  if (!Array.isArray(raw.files)) invalid4(`gives "${fieldPath}" no list of vector files`, { fieldPath });
+  if (!isId(raw.graphGeneration)) invalid4(`gives "${fieldPath}" an invalid graph generation`, { fieldPath });
   const graphKey = raw.graphKey ?? null;
-  if (graphKey !== null && !isKey(graphKey)) invalid3(`gives "${fieldPath}" an invalid graph key`, { fieldPath });
+  if (graphKey !== null && !isKey(graphKey)) invalid4(`gives "${fieldPath}" an invalid graph key`, { fieldPath });
   if (graphKey !== null && raw.graphGeneration === 0) {
-    invalid3(`names a graph file for "${fieldPath}" at generation 0`, { fieldPath });
+    invalid4(`names a graph file for "${fieldPath}" at generation 0`, { fieldPath });
   }
   const nextFileId = raw.nextFileId;
   const seenIds = /* @__PURE__ */ new Set();
@@ -21041,7 +21790,7 @@ function normalizeField(raw, seenFields) {
 }
 function normalizeVectorFields(raw) {
   if (raw === void 0 || raw === null) return [];
-  if (!Array.isArray(raw)) invalid3("has malformed vector references");
+  if (!Array.isArray(raw)) invalid4("has malformed vector references");
   const seenFields = /* @__PURE__ */ new Set();
   return raw.map((field) => normalizeField(field, seenFields));
 }
@@ -22443,17 +23192,15 @@ var workerBusy = false;
 var spawnedWorkerCount = 0;
 var workerIdleMs = CHECKPOINT_WORKER_IDLE_MS;
 var idleTimer = null;
-function resolveWorkerEntryPoint3() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("persistence/durability/checkpoint-worker.mjs", base.slice(0, distIndex + 6)).href;
-  }
-  return base.replace(/\/src\/persistence\/durability\/[^/]+$/, "/dist/persistence/durability/checkpoint-worker.mjs");
-}
 async function spawnWorker3() {
+  const entryPoint = resolveWorkerEntry(
+    import.meta.url,
+    /\/src\/persistence\/durability\/[^/]+$/,
+    "persistence/durability/checkpoint-worker.mjs"
+  );
+  if (entryPoint === null) return null;
   try {
-    const worker = await spawnNodeWorker(new URL(resolveWorkerEntryPoint3()));
+    const worker = await spawnNodeWorker(new URL(entryPoint));
     if (worker === null) {
       return null;
     }
@@ -22684,11 +23431,29 @@ async function garbageThatNoFieldStillReads(directory, vectorIndexes, keys) {
   return unread;
 }
 async function runDurableCheckpoint(input) {
-  let recordsLeftInLog = await writeOneBoundedCheckpoint(input);
-  while (recordsLeftInLog > 0 && input.mayContinue()) {
-    recordsLeftInLog = await writeOneBoundedCheckpoint(input);
+  try {
+    let recordsLeftInLog = await writeOneBoundedCheckpoint(input);
+    while (recordsLeftInLog > 0 && input.mayContinue()) {
+      recordsLeftInLog = await writeOneBoundedCheckpoint(input);
+    }
+  } catch (err) {
+    if (!isSystemError(err)) throw err;
+    const error = new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The engine cannot write the checkpoint of index "${input.indexName}" to the durability directory "${input.directory.root}"`,
+      {
+        indexName: input.indexName,
+        directory: input.directory.root,
+        cause: err.message
+      }
+    );
+    input.markFatal(error);
+    throw error;
   }
 }
+function isSystemError(err) {
+  return err instanceof Error && !(err instanceof NarsilError) && typeof err.code === "string";
+}
 async function writeOneBoundedCheckpoint(input) {
   const manager = input.hooks.getManager(input.indexName);
   if (manager === void 0) {
@@ -22768,6 +23533,94 @@ function recordsBeyond(indexState, targets) {
   return records;
 }
 
+// src/persistence/durability/directory-watch.ts
+function unrefInterval(tick, intervalMs) {
+  const timer = setInterval(tick, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return timer;
+}
+function createDirectoryWatch(directory, isStopped, onLost) {
+  let expected = null;
+  let timer = null;
+  let lock = null;
+  function cannotCheck(err) {
+    return new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The engine cannot check the durability directory "${directory.root}", so it cannot confirm that a write is durable`,
+      { directory: directory.root, cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  async function currentIdentity() {
+    try {
+      return await directory.identity?.() ?? null;
+    } catch (err) {
+      return cannotCheck(err);
+    }
+  }
+  async function lockTakenOver() {
+    if (lock === null) return null;
+    try {
+      if (await lock.holds()) return null;
+    } catch (err) {
+      return cannotCheck(err);
+    }
+    return new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The lock file of the durability directory "${directory.root}" records another engine, which may be writing the same log`,
+      { directory: directory.root }
+    );
+  }
+  async function verify() {
+    if (directory.identity === void 0 || isStopped()) return true;
+    const current = await currentIdentity();
+    if (current instanceof Error) {
+      onLost(current);
+      return false;
+    }
+    if (expected === null) {
+      expected = current;
+    } else if (current !== expected) {
+      onLost(
+        new NarsilError(
+          ErrorCodes.PERSISTENCE_SAVE_FAILED,
+          `The durability directory "${directory.root}" is missing or is a different directory from the one that this instance opens at start-up, so a write to it is not durable`,
+          { directory: directory.root }
+        )
+      );
+      return false;
+    }
+    const takenOver = await lockTakenOver();
+    if (takenOver === null) return true;
+    onLost(takenOver);
+    return false;
+  }
+  function stop() {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+  return {
+    async claim() {
+      if (lock === null && directory.lock !== void 0) lock = await directory.lock();
+    },
+    async release() {
+      const held = lock;
+      lock = null;
+      await held?.release();
+    },
+    verify,
+    async verifyOnce() {
+      if (expected === null && directory.identity !== void 0) await verify();
+    },
+    start() {
+      if (directory.identity === void 0 || timer !== null || isStopped()) return;
+      timer = unrefInterval(() => void verify(), DIRECTORY_IDENTITY_CHECK_INTERVAL_MS);
+    },
+    stop
+  };
+}
+
 // src/persistence/durability/manager-state.ts
 async function drainIndexStateForUnload(indexState, pendingMetadataWrite, closeWalWriter) {
   indexState.unloading = true;
@@ -23240,11 +24093,13 @@ function createDurabilityManager(config, hooks, directoryOverride) {
   let asyncFlushTimer = null;
   let shuttingDown = false;
   let fatalError = null;
+  const directoryWatch = createDirectoryWatch(directory, () => shuttingDown || fatalError !== null, markFatal);
   function markFatal(error) {
     if (fatalError !== null) {
       return;
     }
     fatalError = error;
+    directoryWatch.stop();
     if (checkpointTimer !== null) {
       clearInterval(checkpointTimer);
       checkpointTimer = null;
@@ -23308,23 +24163,13 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     if (checkpointTimer !== null || shuttingDown || fatalError !== null || checkpointIntervalMs <= 0) {
       return;
     }
-    checkpointTimer = setInterval(() => {
-      void runScheduledCheckpoints();
-    }, checkpointIntervalMs);
-    if (typeof checkpointTimer.unref === "function") {
-      checkpointTimer.unref();
-    }
+    checkpointTimer = unrefInterval(() => void runScheduledCheckpoints(), checkpointIntervalMs);
   }
   function startAsyncFlushTimer() {
     if (mode !== "async" || asyncFlushTimer !== null || shuttingDown || fatalError !== null || flushIntervalMs <= 0) {
       return;
     }
-    asyncFlushTimer = setInterval(() => {
-      void flushAllPartitions();
-    }, flushIntervalMs);
-    if (typeof asyncFlushTimer.unref === "function") {
-      asyncFlushTimer.unref();
-    }
+    asyncFlushTimer = unrefInterval(() => void flushAllPartitions(), flushIntervalMs);
   }
   async function flushAllPartitions() {
     if (fatalError !== null) {
@@ -23386,6 +24231,8 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     return run;
   }
   async function performCheckpoint(indexName, indexState, fromMemory = false) {
+    await directoryWatch.verify();
+    if (fatalError !== null) throw fatalError;
     await runDurableCheckpoint({
       directory,
       hooks,
@@ -23435,10 +24282,14 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       }
       await stallWhileCheckpointsFallBehind(indexState);
     }
-    if (recordedByIndex.size > 0) {
-      startCheckpointTimer();
-      startAsyncFlushTimer();
-    }
+    if (recordedByIndex.size === 0) return outcomes;
+    if (mode === "sync") await directoryWatch.verify();
+    const lost = mode === "sync" ? fatalError : null;
+    if (lost !== null) return outcomes.map((outcome) => outcome.ok ? { ok: false, error: lost } : outcome);
+    await directoryWatch.verifyOnce();
+    directoryWatch.start();
+    startCheckpointTimer();
+    startAsyncFlushTimer();
     return outcomes;
   }
   function recoverIndex(indexName, metadataOnly = false) {
@@ -23460,10 +24311,13 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       return true;
     },
     async recover(metadataOnly = false) {
+      await directoryWatch.claim();
       const names = await listPersistedIndexes(directory);
       for (const indexName of names) {
         await recoverIndex(indexName, metadataOnly);
       }
+      await directoryWatch.verify();
+      directoryWatch.start();
       startCheckpointTimer();
     },
     recoverIndex(indexName) {
@@ -23525,6 +24379,7 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     },
     async shutdown() {
       shuttingDown = true;
+      directoryWatch.stop();
       if (checkpointTimer !== null) {
         clearInterval(checkpointTimer);
         checkpointTimer = null;
@@ -23543,6 +24398,7 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       }
       indexes.clear();
       terminateCheckpointWorker();
+      await directoryWatch.release();
     }
   };
 }
@@ -24973,18 +25829,6 @@ function eligibleIndexNames(state) {
   return names;
 }
 
-// src/engine/orchestration/turn.ts
-function afterCurrentTurn(callback) {
-  if (typeof setImmediate === "function") {
-    setImmediate(callback);
-    return;
-  }
-  setTimeout(callback, 0);
-}
-function yieldToEventLoop6() {
-  return new Promise((resolve) => afterCurrentTurn(resolve));
-}
-
 // src/engine/orchestration/replication.ts
 async function dispatchToWorkers(state, action) {
   const pool = state.workerPool;
@@ -25142,7 +25986,7 @@ async function replicateToWorkers(state, action) {
   const loading = state.copyLoadBuffers.get(action.indexName);
   if (loading !== void 0) {
     queueForCopies(state, detached);
-    if (loading.length % LOAD_BUFFER_YIELD_INTERVAL === 0) await yieldToEventLoop6();
+    if (loading.length % LOAD_BUFFER_YIELD_INTERVAL === 0) await yieldToEventLoop();
     return;
   }
   const queue = state.replicationQueues.get(action.indexName);
@@ -25584,17 +26428,14 @@ function createWorkerExecutor(worker, config) {
 }
 
 // src/workers/factory.browser.ts
-function resolveEntryPoint() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("workers/entry.mjs", base.slice(0, distIndex + 6)).href;
-  }
-  return base.replace(/\/src\/workers\/[^/]+$/, "/dist/workers/entry.mjs");
+async function requireWorkerEntry() {
+  const entry = resolveWorkerEntry(import.meta.url, /\/src\/workers\/[^/]+$/, "workers/entry.mjs");
+  if (entry !== null) return entry;
+  throw missingWorkerEntry(import.meta.url);
 }
 async function createWorkerFactory(entryPoint) {
   const runtime = detectRuntime();
-  const resolvedEntry = resolveEntryPoint();
+  const resolvedEntry = await requireWorkerEntry();
   if (runtime.supportsWebWorkers) {
     return function webFactory(_workerId, onDeath, onGone) {
       const instance = new Worker(resolvedEntry, { type: "module" });
@@ -25784,10 +26625,13 @@ function createWorkerPool(config) {
     }
     isShutdown = true;
     const shutdownPromises = [...threadsStillRunning].map((executor) => {
+      let timeoutId;
       const timeoutPromise = new Promise((resolve) => {
-        setTimeout(resolve, 5e3);
+        timeoutId = setTimeout(resolve, SHUTDOWN_TIMEOUT_MS);
       });
-      return Promise.race([shutDownUntilTheThreadIsGone(executor), timeoutPromise]);
+      return Promise.race([shutDownUntilTheThreadIsGone(executor), timeoutPromise]).finally(
+        () => clearTimeout(timeoutId)
+      );
     });
     await Promise.allSettled(shutdownPromises);
     indexAssignment.clear();
@@ -26223,8 +27067,12 @@ async function ensurePool(state) {
 function documentCountOf(state, indexName) {
   return state.executor.getManager(indexName)?.countDocuments() ?? 0;
 }
-function copyThresholdReason(state, indexName) {
-  return `Index "${indexName}" holds ${documentCountOf(state, indexName)} documents, reaching the copy threshold of ${state.copyThreshold}`;
+function copyThresholdReason(state, indexName, incomingCount = 0) {
+  const held = documentCountOf(state, indexName);
+  if (incomingCount <= 0) {
+    return `Index "${indexName}" holds ${held} documents, reaching the copy threshold of ${state.copyThreshold}`;
+  }
+  return `Index "${indexName}" holds ${held} documents, and the batch that the engine is writing adds ${incomingCount}, for ${held + incomingCount} against the copy threshold of ${state.copyThreshold}`;
 }
 function indexReadyForCopies(state, indexName, incomingCount = 0) {
   if (!copiesAllowed(state)) return false;
@@ -26313,7 +27161,7 @@ async function scaleOutBeforeBatch(state, indexName, incomingCount) {
     return;
   }
   if (!indexReadyForCopies(state, indexName, incomingCount)) return;
-  await scaleOutIndex(state, indexName, copyThresholdReason(state, indexName));
+  await scaleOutIndex(state, indexName, copyThresholdReason(state, indexName, incomingCount));
 }
 
 // src/engine/orchestration/idle.ts
@@ -26393,7 +27241,7 @@ function partitionsPerLease(scope, leaseCount) {
   }
   return assignments;
 }
-function mergeWorkerResults(results) {
+function mergeWorkerResults(results, facetConfig) {
   const merged = kWayMerge(results.map((result) => result.scored));
   let totalMatched = 0;
   const workerFacets = [];
@@ -26404,7 +27252,7 @@ function mergeWorkerResults(results) {
   return {
     scored: merged,
     totalMatched,
-    facets: workerFacets.length > 0 ? mergeFacets(workerFacets) : void 0
+    facets: facetConfig !== void 0 && workerFacets.length > 0 ? mergeFacets(workerFacets, facetConfig) : void 0
   };
 }
 function scoresPerPartition(state, indexName, params, globalStats) {
@@ -26424,12 +27272,13 @@ function queryAction(indexName, params, globalStats, partitionIds) {
 }
 async function runSplit(leases, scope, indexName, params, globalStats) {
   const assignments = partitionsPerLease(scope, leases.length);
+  const workerParams = params.facets !== void 0 ? { ...params, facets: oversampledFacetConfig(params.facets) } : params;
   const results = await Promise.all(
     assignments.map(
-      (partitionIds, at) => leases[at].executor.execute(queryAction(indexName, params, globalStats, partitionIds)).finally(() => leases[at].release())
+      (partitionIds, at) => leases[at].executor.execute(queryAction(indexName, workerParams, globalStats, partitionIds)).finally(() => leases[at].release())
     )
   );
-  return mergeWorkerResults(results);
+  return mergeWorkerResults(results, params.facets);
 }
 function takeMainCopyTurn(state) {
   if (state.mainCopyQueries === "none" || state.mainCopyTurnTaken) return false;
@@ -26915,7 +27764,7 @@ function createEngineCore(config, hooks) {
   const rebalanceTargets = /* @__PURE__ */ new Map();
   function guardShutdown() {
     if (shutdownState.isShutdown) {
-      throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "This Narsil instance has been shut down");
+      throw new NarsilError(ErrorCodes.INSTANCE_SHUT_DOWN, "This Narsil instance has been shut down");
     }
   }
   function requireIndex(indexName) {
@@ -27082,6 +27931,81 @@ function createEngineCore(config, hooks) {
   };
 }
 
+// src/engine/lifecycle.ts
+async function startEngineCore(core, config) {
+  try {
+    if (core.durability) {
+      await core.durability.manager.recover(config?.lifecycle !== void 0);
+      checkHeapAfterRecovery(core);
+    }
+    if (core.invalidation) await core.invalidation.start();
+    if (config?.lifecycle === void 0) await core.analysisRebuild.reviewStaleIndexes();
+  } catch (err) {
+    await core.durability?.manager.shutdown().catch(() => void 0);
+    await shutdownEngine(core).catch(() => void 0);
+    throw err;
+  }
+}
+async function shutdownEngine(core) {
+  const { executor, durability, indexRegistry, eventHandlers, orchestrator } = core;
+  core.indexState.dispose();
+  for (const [name] of indexRegistry) {
+    const manager = executor.getManager(name);
+    if (manager) {
+      for (const [, vectorIndex] of manager.getVectorIndexes()) {
+        vectorIndex.dispose();
+      }
+    }
+  }
+  if (durability) {
+    await durability.manager.shutdown();
+  }
+  if (core.invalidation) {
+    await core.invalidation.shutdown();
+  }
+  const adaptersToShutdown = /* @__PURE__ */ new Set();
+  for (const [, entry] of indexRegistry) {
+    if (entry.embeddingAdapter?.shutdown) {
+      adaptersToShutdown.add(entry.embeddingAdapter);
+    }
+  }
+  for (const adapter of adaptersToShutdown) {
+    try {
+      await adapter.shutdown?.();
+    } catch {
+    }
+  }
+  await orchestrator.shutdown();
+  await executor.shutdown();
+  eventHandlers.clear();
+  indexRegistry.clear();
+}
+
+// src/engine/startup-checks.ts
+var announcedMissingWorkerEntry = false;
+function withoutWorkers(config, reason) {
+  if (!announcedMissingWorkerEntry) {
+    announcedMissingWorkerEntry = true;
+    console.warn(
+      `Narsil answers every query on this thread, because it finds no worker entry beside its own module at "${String(reason.details.moduleUrl)}", which happens where a bundler folds @delali/narsil into an application bundle. Keep @delali/narsil outside the bundle to use worker threads, or set workers.enabled to false to silence this notice.`
+    );
+  }
+  return { ...config, workers: { ...config?.workers, enabled: false } };
+}
+async function resolveRunnableConfig(config) {
+  if (!(config?.workers?.enabled ?? workersEnabledByDefault())) return config;
+  const runtime = detectRuntime();
+  if (!runtime.supportsWorkerThreads && !runtime.supportsWebWorkers) return config;
+  try {
+    await requireWorkerEntry();
+    return config;
+  } catch (err) {
+    const missingEntry = err instanceof NarsilError && err.code === ErrorCodes.CONFIG_INVALID;
+    if (!missingEntry || config?.workers?.enabled === true) throw err;
+    return withoutWorkers(config, err);
+  }
+}
+
 // src/engine/index-lifecycle.ts
 async function runLifecycleHook(core, hookName, context) {
   try {
@@ -27215,42 +28139,6 @@ function registerEngineEmbeddingAdapter(core, name, adapter) {
   }
 }
 
-// src/engine/lifecycle.ts
-async function shutdownEngine(core) {
-  const { executor, durability, indexRegistry, eventHandlers, orchestrator } = core;
-  core.indexState.dispose();
-  for (const [name] of indexRegistry) {
-    const manager = executor.getManager(name);
-    if (manager) {
-      for (const [, vectorIndex] of manager.getVectorIndexes()) {
-        vectorIndex.dispose();
-      }
-    }
-  }
-  if (durability) {
-    await durability.manager.shutdown();
-  }
-  if (core.invalidation) {
-    await core.invalidation.shutdown();
-  }
-  const adaptersToShutdown = /* @__PURE__ */ new Set();
-  for (const [, entry] of indexRegistry) {
-    if (entry.embeddingAdapter?.shutdown) {
-      adaptersToShutdown.add(entry.embeddingAdapter);
-    }
-  }
-  for (const adapter of adaptersToShutdown) {
-    try {
-      await adapter.shutdown?.();
-    } catch {
-    }
-  }
-  await orchestrator.shutdown();
-  await executor.shutdown();
-  eventHandlers.clear();
-  indexRegistry.clear();
-}
-
 // src/engine/embed.ts
 function assertDocumentCarriesMappedVectors(document2, embeddingConfig, adapterName) {
   for (const targetField of Object.keys(embeddingConfig.fields)) {
@@ -27919,6 +28807,7 @@ async function applyAdmittedDocuments(ctx, indexName, admitted, options, failed)
     }
     const applied = chunkStart + BATCH_CHUNK_SIZE;
     if (applied < admitted.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -28158,6 +29047,7 @@ async function recordMergedDocuments(ctx, indexName, built, frozen, memberIndexe
       succeededIds.add(doc.docId);
     }
     if (index + 1 < chunks.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -28369,6 +29259,7 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
     }
     if (prepared.length > 0) await applyPrepared(prepared);
     if (chunkEnd < documents.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -28566,6 +29457,18 @@ async function settleUpdate(ctx, indexName, prepared) {
 async function prepareUpdate(ctx, indexName, entry, docId, document2) {
   ctx.guardShutdown();
   validateDocId(docId);
+  const manager = ctx.requireManager(indexName);
+  if (ctx.pluginRegistry.hasHooks("beforeUpdate")) {
+    await ctx.pluginRegistry.runHook("beforeUpdate", {
+      indexName,
+      docId,
+      oldDocument: manager.get(docId) ?? {},
+      newDocument: document2
+    });
+  }
+  if (entry.config.required && entry.config.required.length > 0) {
+    validateRequiredFields(document2, entry.config.required);
+  }
   if (entry.config.embedding) {
     if (entry.embeddingAdapter) {
       await embedDocumentFields(
@@ -28582,16 +29485,9 @@ async function prepareUpdate(ctx, indexName, entry, docId, document2) {
       );
     }
   }
-  const manager = ctx.requireManager(indexName);
   const oldDocument = manager.get(docId);
   const oldPartitionDoc = manager.getRef(docId);
   const rollbackDoc = oldPartitionDoc ? structuredClone(oldPartitionDoc) : void 0;
-  await ctx.pluginRegistry.runHook("beforeUpdate", {
-    indexName,
-    docId,
-    oldDocument: oldDocument ?? {},
-    newDocument: document2
-  });
   const vecIndexes = manager.getVectorIndexes();
   const extractedVectors = /* @__PURE__ */ new Map();
   if (vecIndexes.size > 0) {
@@ -28710,6 +29606,7 @@ async function updateDocumentBatch(ctx, indexName, updates, options) {
       succeeded.push(update.docId);
     }
     if (chunkEnd < updates.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -28954,7 +29851,7 @@ async function executeRebalance(manager, indexName, targetPartitionCount, ctx) {
     await replayQueued(manager, indexName, waq, ctx);
     if (ctx.durabilityManager) {
       await ctx.durabilityManager.persistMetadata(indexName);
-      await ctx.durabilityManager.checkpoint(indexName);
+      await (ctx.durabilityManager.checkpointFromMemory?.(indexName) ?? ctx.durabilityManager.checkpoint(indexName));
       await replayQueued(manager, indexName, waq, ctx);
     }
     await ctx.orchestrator.resyncIndex(indexName, wasPromoted);
@@ -28985,7 +29882,7 @@ async function executeRebalance(manager, indexName, targetPartitionCount, ctx) {
 }
 
 // src/engine/snapshot/restore-config.ts
-function invalid4(message) {
+function invalid5(message) {
   throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, `Invalid snapshot: ${message}`);
 }
 function isPlainObject3(value) {
@@ -28996,14 +29893,14 @@ function restoredBm25(raw) {
     return void 0;
   }
   if (!isPlainObject3(raw)) {
-    invalid4("bm25 must be an object");
+    invalid5("bm25 must be an object");
   }
   const { k1, b } = raw;
   if (k1 !== void 0 && (typeof k1 !== "number" || !Number.isFinite(k1))) {
-    invalid4("bm25 k1 must be a finite number");
+    invalid5("bm25 k1 must be a finite number");
   }
   if (b !== void 0 && (typeof b !== "number" || !Number.isFinite(b))) {
-    invalid4("bm25 b must be a finite number");
+    invalid5("bm25 b must be a finite number");
   }
   return {
     ...k1 !== void 0 ? { k1 } : {},
@@ -29012,13 +29909,13 @@ function restoredBm25(raw) {
 }
 function restoredStopWords(name, list) {
   if (name !== void 0 && typeof name !== "string") {
-    invalid4("stopWords must be a name");
+    invalid5("stopWords must be a name");
   }
   if (list !== void 0 && (!Array.isArray(list) || !list.every((word) => typeof word === "string"))) {
-    invalid4("stopWordList must be a list of words");
+    invalid5("stopWordList must be a list of words");
   }
   if (typeof name === "string" && Array.isArray(list)) {
-    invalid4("stopWords and stopWordList cannot both be present");
+    invalid5("stopWords and stopWordList cannot both be present");
   }
   if (typeof name === "string") {
     return name;
@@ -29033,17 +29930,17 @@ function restoredPartitionConfig(raw) {
     return void 0;
   }
   if (!isPlainObject3(raw)) {
-    invalid4("partitionConfig must be an object");
+    invalid5("partitionConfig must be an object");
   }
   const { maxDocsPerPartition, maxPartitions, watermark } = raw;
   if (maxDocsPerPartition !== void 0 && (typeof maxDocsPerPartition !== "number" || !Number.isInteger(maxDocsPerPartition) || maxDocsPerPartition < 1)) {
-    invalid4("partitionConfig maxDocsPerPartition must be a positive integer");
+    invalid5("partitionConfig maxDocsPerPartition must be a positive integer");
   }
   if (maxPartitions !== void 0 && (typeof maxPartitions !== "number" || !Number.isInteger(maxPartitions) || maxPartitions < 1)) {
-    invalid4("partitionConfig maxPartitions must be a positive integer");
+    invalid5("partitionConfig maxPartitions must be a positive integer");
   }
   if (watermark !== void 0 && (typeof watermark !== "number" || !(watermark > 0) || watermark > 1)) {
-    invalid4("partitionConfig watermark must be above 0 and at most 1");
+    invalid5("partitionConfig watermark must be above 0 and at most 1");
   }
   return {
     ...typeof maxDocsPerPartition === "number" ? { maxDocsPerPartition } : {},
@@ -29056,7 +29953,7 @@ function restoredScoring(raw) {
     return void 0;
   }
   if (raw !== "local" && raw !== "dfs" && raw !== "broadcast") {
-    invalid4("defaultScoring must be 'local', 'dfs', or 'broadcast'");
+    invalid5("defaultScoring must be 'local', 'dfs', or 'broadcast'");
   }
   return raw;
 }
@@ -29065,7 +29962,7 @@ function restoredBoolean(raw, field) {
     return void 0;
   }
   if (typeof raw !== "boolean") {
-    invalid4(`${field} must be a boolean`);
+    invalid5(`${field} must be a boolean`);
   }
   return raw;
 }
@@ -29074,7 +29971,7 @@ function restoredRequired(raw) {
     return void 0;
   }
   if (!Array.isArray(raw) || !raw.every((field) => typeof field === "string")) {
-    invalid4("required must be a list of field paths");
+    invalid5("required must be a list of field paths");
   }
   return raw;
 }
@@ -29083,7 +29980,7 @@ function restoredVectorPromotion(raw) {
     return void 0;
   }
   if (!isPlainObject3(raw) || raw.hnswConfig !== void 0 && !isPlainObject3(raw.hnswConfig)) {
-    invalid4("vectorPromotion must be an object");
+    invalid5("vectorPromotion must be an object");
   }
   return raw;
 }
@@ -29092,20 +29989,20 @@ function restoredEmbedding(raw) {
     return void 0;
   }
   if (!isPlainObject3(raw)) {
-    invalid4("embedding must be an object");
+    invalid5("embedding must be an object");
   }
   const { fields, adapter } = raw;
   if (adapter !== void 0 && typeof adapter !== "string") {
-    invalid4("embedding adapter must be a name");
+    invalid5("embedding adapter must be a name");
   }
   if (!isPlainObject3(fields)) {
-    invalid4("embedding fields must be an object");
+    invalid5("embedding fields must be an object");
   }
   for (const value of Object.values(fields)) {
     const isPath = typeof value === "string";
     const isPathList = Array.isArray(value) && value.every((path) => typeof path === "string");
     if (!isPath && !isPathList) {
-      invalid4("embedding fields must map vector fields to source paths");
+      invalid5("embedding fields must map vector fields to source paths");
     }
   }
   return {
@@ -29115,7 +30012,7 @@ function restoredEmbedding(raw) {
 }
 function restoredConfigFields(envelope) {
   if (envelope.tokenizer !== void 0 && typeof envelope.tokenizer !== "string") {
-    invalid4("tokenizer must be a name");
+    invalid5("tokenizer must be a name");
   }
   const stopWords2 = restoredStopWords(envelope.stopWords, envelope.stopWordList);
   const bm25 = restoredBm25(envelope.bm25);
@@ -29596,13 +30493,176 @@ function listBindingOf(filters) {
   return bindingOf(values);
 }
 
-// src/engine/list-documents/index.ts
-function clampListLimit(limit) {
-  const clamped = Math.max(1, clampLimit(limit));
-  requireWithinResultWindow(clamped, 0);
-  return clamped;
+// 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 firstIdAfter(sorted, anchor) {
+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/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) {
@@ -29658,6 +30718,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
@@ -29689,7 +30750,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) {
@@ -29737,6 +30799,10 @@ function getNestedValue2(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 }];
@@ -29760,16 +30826,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;
@@ -29820,23 +30884,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
@@ -29934,19 +31002,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);
@@ -30016,7 +31090,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
         });
       }
     }
@@ -30024,120 +31100,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");
@@ -30158,19 +31120,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
         )
       );
@@ -30181,6 +31145,7 @@ function executeSortedQueryPage(params, context, limit, offset, sortSignature) {
       fields,
       directions,
       fieldTypes,
+      modes,
       limit: partitionLimit,
       anchorKey,
       anchorId,
@@ -30206,13 +31171,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) {
@@ -30304,7 +31298,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) {
@@ -30325,8 +31330,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 } : {},
@@ -30334,8 +31339,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;
@@ -30354,9 +31359,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 } : {},
@@ -30364,11 +31369,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);
@@ -30385,31 +31394,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();
@@ -30430,11 +31444,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)) {
@@ -30448,9 +31463,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;
@@ -30485,11 +31502,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;
@@ -30500,12 +31518,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) {
@@ -30527,7 +31548,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;
@@ -30563,6 +31586,7 @@ async function executeQuery(params, context) {
   return {
     hits: paginated,
     count,
+    countExact,
     elapsed,
     cursor: nextCursor,
     facets,
@@ -30574,6 +31598,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;
@@ -30582,14 +31607,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),
@@ -30613,7 +31641,7 @@ async function executePreflight(params, context) {
     }
   }
   const elapsed = now() - startTime;
-  return { count: totalMatched, elapsed };
+  return { count: totalMatched, countExact, elapsed };
 }
 
 // src/engine/resolve-vector-text.ts
@@ -30640,7 +31668,16 @@ async function resolveVectorText(params, embeddingAdapter, signal, embeddingAdap
   if (params.vector.text.length === 0) {
     throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Vector query 'text' must not be empty");
   }
-  const raw = await embeddingAdapter.embed(params.vector.text, "query", signal);
+  let raw;
+  try {
+    raw = await embeddingAdapter.embed(params.vector.text, "query", signal);
+  } catch (err) {
+    if (err instanceof NarsilError) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new NarsilError(ErrorCodes.EMBEDDING_FAILED, `The embedding adapter cannot embed the query: ${message}`, {
+      cause: message
+    });
+  }
   if (!(raw instanceof Float32Array)) {
     throw new NarsilError(
       ErrorCodes.EMBEDDING_FAILED,
@@ -30707,6 +31744,10 @@ function pickDisplaySurface(surfaceOccurrences) {
 }
 
 // src/narsil/reads.ts
+async function enterRead(core, indexName) {
+  core.guardShutdown();
+  if (core.rebalancingIndexes.has(indexName)) await yieldToEventLoop();
+}
 function scopedParams(params, options) {
   {
     return params;
@@ -30720,7 +31761,7 @@ function broadcastStatsFor(core, options) {
   return (name) => invalidation.broadcastStats(name);
 }
 async function runEngineQuery(core, indexName, params, options) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
@@ -30761,7 +31802,7 @@ async function runEngineQuery(core, indexName, params, options) {
   }
 }
 async function runEnginePreflight(core, indexName, params, options) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
@@ -30794,7 +31835,7 @@ async function runEnginePreflight(core, indexName, params, options) {
   }
 }
 async function runEngineSuggest(core, indexName, params, partitionIds) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const result = executeSuggest(
@@ -30812,13 +31853,14 @@ async function runEngineSuggest(core, indexName, params, partitionIds) {
   }
 }
 async function runEngineListDocuments(core, indexName, params, partitionIds) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
     return executeListDocuments(params, {
       manager: core.requireManager(indexName),
       schema: entry.config.schema,
+      strict: entry.config.strict,
       partitionIds
     });
   } finally {
@@ -31125,16 +32167,11 @@ function createNarsilFromCore(core, config) {
 
 // src/narsil/index.ts
 async function createNarsil(config) {
-  const core = createEngineCore(config);
-  if (core.durability) {
-    await core.durability.manager.recover(config?.lifecycle !== void 0);
-    checkHeapAfterRecovery(core);
-  }
-  if (core.invalidation) {
-    await core.invalidation.start();
-  }
-  if (config?.lifecycle === void 0) await core.analysisRebuild.reviewStaleIndexes();
-  return createNarsilFromCore(core, config);
+  requireKnownConfig(config);
+  const runnableConfig = await resolveRunnableConfig(config);
+  const core = createEngineCore(runnableConfig);
+  await startEngineCore(core, runnableConfig);
+  return createNarsilFromCore(core, runnableConfig);
 }
 
 // src/index.ts