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

package/dist/chunk-Y3L5MDRV.mjs

@@ -0,0 +1,96 @@
+import { performance } from 'perf_hooks';
+import { getHeapStatistics, setFlagsFromString } from 'v8';
+import { runInNewContext } from 'vm';
+
+// src/runtime/idle-heap-cleanup.ts
+
+// src/runtime/constants.ts
+var IDLE_HEAP_CLEANUP_CHECK_MS = 1e3;
+var IDLE_HEAP_CLEANUP_QUIET_CHECKS = 2;
+var IDLE_HEAP_CLEANUP_MAX_UTILISATION = 0.1;
+var IDLE_HEAP_CLEANUP_MAX_GROWTH_BYTES = 4 * 1024 * 1024;
+var IDLE_HEAP_CLEANUP_MIN_RECLAIMABLE_BYTES = 64 * 1024 * 1024;
+
+// src/runtime/idle-heap-cleaner.ts
+function createIdleHeapCleaner(deps) {
+  let quietChecks = 0;
+  let liveBytesAfterLastCleanup = 0;
+  let heldBytesAtLastCheck = Number.POSITIVE_INFINITY;
+  return {
+    check() {
+      const busy = deps.utilisationSinceLastCheck() > IDLE_HEAP_CLEANUP_MAX_UTILISATION;
+      const before = deps.readHeap();
+      if (before === null) return false;
+      const heapGrew = before.heldBytes > heldBytesAtLastCheck + IDLE_HEAP_CLEANUP_MAX_GROWTH_BYTES;
+      heldBytesAtLastCheck = before.heldBytes;
+      if (busy || heapGrew) {
+        quietChecks = 0;
+        return false;
+      }
+      quietChecks += 1;
+      if (quietChecks < IDLE_HEAP_CLEANUP_QUIET_CHECKS) return false;
+      if (before.heldBytes - liveBytesAfterLastCleanup < IDLE_HEAP_CLEANUP_MIN_RECLAIMABLE_BYTES) return false;
+      if (!deps.collectAndReturnPages()) return false;
+      const after = deps.readHeap();
+      liveBytesAfterLastCleanup = after?.liveBytes ?? before.liveBytes;
+      heldBytesAtLastCheck = after?.heldBytes ?? before.heldBytes;
+      quietChecks = 0;
+      return true;
+    }
+  };
+}
+
+// src/runtime/idle-heap-cleanup.ts
+var collectorOfThisThread = null;
+function acquireCollector() {
+  if (collectorOfThisThread !== null) return collectorOfThisThread;
+  try {
+    setFlagsFromString("--expose-gc");
+    const collect = runInNewContext("gc");
+    setFlagsFromString("--no-expose-gc");
+    if (typeof collect !== "function") return null;
+    collectorOfThisThread = collect;
+    return collectorOfThisThread;
+  } catch {
+    return null;
+  }
+}
+function collectAndReturnPages() {
+  const collect = acquireCollector();
+  if (collect === null) return false;
+  try {
+    collect({ type: "major", execution: "sync", flavor: "last-resort" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readHeap() {
+  try {
+    const stats = getHeapStatistics();
+    return { heldBytes: stats.total_physical_size, liveBytes: stats.used_heap_size };
+  } catch {
+    return null;
+  }
+}
+function startIdleHeapCleanup() {
+  if (typeof performance.eventLoopUtilization !== "function") return () => void 0;
+  let lastReading = performance.eventLoopUtilization();
+  const cleaner = createIdleHeapCleaner({
+    utilisationSinceLastCheck() {
+      const reading = performance.eventLoopUtilization();
+      const { utilization } = performance.eventLoopUtilization(reading, lastReading);
+      lastReading = reading;
+      return utilization;
+    },
+    readHeap,
+    collectAndReturnPages
+  });
+  const timer = setInterval(() => {
+    cleaner.check();
+  }, IDLE_HEAP_CLEANUP_CHECK_MS);
+  timer.unref();
+  return () => clearInterval(timer);
+}
+
+export { startIdleHeapCleanup };

package/dist/{chunk-ZHUQKZBE.mjs → chunk-YPYULM5E.mjs}

@@ -1,5 +1,7 @@
-import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, DEFAULT_LIMIT, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, DEFAULT_OFFSET } from './chunk-XE6XR2OE.mjs';
-import { clampRowCount, sortSignatureOf, requireSortableFields, decodePageCursor, requireMatchingCursor, resolveProjection, encodePageCursor, requireWithinResultWindow, normalizeSort, fanOutQuery, flattenSchema, applySorting, applyPagination, countsWithoutScores, fanOutMatchCount, tokenize, fnv1aBytes, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, partitionsIn } from './chunk-CMVG2UEF.mjs';
+import { MAX_INDEX_NAME_LENGTH, INDEX_NAME_PATTERN, MAX_DOC_ID_LENGTH, DEFAULT_LIMIT, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, DEFAULT_OFFSET } from './chunk-3GWP2TO6.mjs';
+import { clampRowCount, sortSignatureOf, requireSortableFields, decodePageCursor, requireMatchingCursor, resolveProjection, encodePageCursor, requireWithinResultWindow, normalizeSort, fanOutQuery, applySorting, applyPagination, countsWithoutScores, fanOutMatchCount, tokenize, fnv1aBytes, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, partitionsIn } from './chunk-WM7IS45M.mjs';
+import { flattenSchema } from './chunk-ZT5BRDFW.mjs';
+import { MIN_OVERSAMPLE } from './chunk-ZJ4CSAB2.mjs';
 import { compareCodePoints, compareComparableKeys } from './chunk-2GWVQWGA.mjs';
 import { NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
 
@@ -938,6 +940,18 @@ function minMaxNormalize(docs) {
 }
 
 // src/engine/query/vector.ts
+function oversampleOf(vectorConfig) {
+  const oversample = vectorConfig.oversample;
+  if (oversample === void 0) return void 0;
+  if (typeof oversample !== "number" || !Number.isFinite(oversample) || oversample < MIN_OVERSAMPLE) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      `vector.oversample must be a finite number of at least ${MIN_OVERSAMPLE}`,
+      { oversample }
+    );
+  }
+  return oversample;
+}
 async function executeVectorSearch(params, context, limit, offset) {
   const { manager, config, partitionIds } = context;
   const vectorConfig = params.vector;
@@ -965,7 +979,8 @@ async function executeVectorSearch(params, context, limit, offset) {
     minSimilarity: vectorConfig.similarity ?? -Infinity,
     ...filterDocIds !== void 0 ? { filterDocIds } : {},
     ...filterPartitions !== void 0 ? { filterPartitions } : {},
-    efSearch: vectorConfig.efSearch
+    efSearch: vectorConfig.efSearch,
+    oversample: oversampleOf(vectorConfig)
   });
   const scored = vectorResultsToScored(results);
   return { scored, totalMatched: scored.length };
@@ -994,7 +1009,8 @@ async function vectorLeg(vectorConfig, queryVector, context, filterDocIds, k) {
     minSimilarity: vectorConfig.similarity ?? -Infinity,
     ...filterDocIds !== void 0 ? { filterDocIds } : {},
     ...filterPartitions !== void 0 ? { filterPartitions } : {},
-    efSearch: vectorConfig.efSearch
+    efSearch: vectorConfig.efSearch,
+    oversample: oversampleOf(vectorConfig)
   });
   return vectorResultsToScored(results);
 }

package/dist/chunk-ZJ4CSAB2.mjs

@@ -0,0 +1,13 @@
+// src/vector/osq/constants.ts
+var OSQ_GRID = { 1: 0.798, 2: 1.493, 4: 2.514, 8: 3.922 };
+var OSQ_STEPS = { 1: 1, 2: 3, 4: 15, 8: 255 };
+var OSQ_QUERY_BITS = { 1: 4, 2: 4, 4: 4, 8: 8 };
+var OSQ_LAMBDA = 0.1;
+var OSQ_REFINE_ROUNDS = 5;
+var OSQ_REFINE_TOLERANCE = 1e-8;
+var DEFAULT_OVERSAMPLE_BY_BITS = { 1: 3, 2: 3, 4: 2, 8: 2 };
+var DEFAULT_OSQ4_NARROW_OVERSAMPLE = 5;
+var OSQ4_NARROW_DIMENSION_LIMIT = 1024;
+var MIN_OVERSAMPLE = 1;
+
+export { DEFAULT_OSQ4_NARROW_OVERSAMPLE, DEFAULT_OVERSAMPLE_BY_BITS, MIN_OVERSAMPLE, OSQ4_NARROW_DIMENSION_LIMIT, OSQ_GRID, OSQ_LAMBDA, OSQ_QUERY_BITS, OSQ_REFINE_ROUNDS, OSQ_REFINE_TOLERANCE, OSQ_STEPS };

package/dist/chunk-ZT5BRDFW.mjs

@@ -0,0 +1,513 @@
+import { MAX_M } from './chunk-WFKIGEBY.mjs';
+import { NarsilError, ErrorCodes } from './chunk-P4ELXVJQ.mjs';
+
+// src/schema/constants.ts
+var MAX_NESTING_DEPTH = 4;
+var MAX_DOCUMENT_NESTING_DEPTH = 32;
+
+// src/schema/validator/shared.ts
+var SORTABLE_TEXT_FIELD_TYPE = "string:sortable";
+var SCALAR_FIELD_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  SORTABLE_TEXT_FIELD_TYPE,
+  "number",
+  "boolean",
+  "enum",
+  "geopoint",
+  "string[]",
+  "number[]",
+  "boolean[]",
+  "enum[]"
+]);
+function isTextFieldType(fieldType) {
+  return fieldType === "string" || fieldType === SORTABLE_TEXT_FIELD_TYPE;
+}
+var VECTOR_PATTERN = /^vector\[(\d+)]$/;
+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"]);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/schema/validator/schema.ts
+function validateSchemaFields(schema, depth, prefix) {
+  if (depth > MAX_NESTING_DEPTH) {
+    throw new NarsilError(
+      ErrorCodes.SCHEMA_DEPTH_EXCEEDED,
+      `Schema nesting exceeds the maximum depth of ${MAX_NESTING_DEPTH} at "${prefix}"`,
+      { path: prefix, maxDepth: MAX_NESTING_DEPTH }
+    );
+  }
+  for (const [field, type] of Object.entries(schema)) {
+    const path = prefix ? `${prefix}.${field}` : field;
+    if (PROTOTYPE_POLLUTION_KEYS.has(field)) {
+      throw new NarsilError(ErrorCodes.SCHEMA_INVALID_TYPE, `Field name "${field}" is not allowed in a schema`, {
+        field,
+        path
+      });
+    }
+    if (!FIELD_NAME_PATTERN.test(field)) {
+      throw new NarsilError(
+        ErrorCodes.SCHEMA_INVALID_TYPE,
+        `Field name "${field}" contains characters that are not allowed; use letters, digits, and underscores only`,
+        { field, path }
+      );
+    }
+    if (depth === 1 && RESERVED_ROOT_FIELDS.has(field)) {
+      throw new NarsilError(
+        ErrorCodes.SCHEMA_INVALID_TYPE,
+        `Field "${field}" is reserved and cannot be defined in a schema`,
+        { field, path }
+      );
+    }
+    if (isPlainObject(type)) {
+      validateSchemaFields(type, depth + 1, path);
+      continue;
+    }
+    if (typeof type !== "string") {
+      throw new NarsilError(
+        ErrorCodes.SCHEMA_INVALID_TYPE,
+        `Field "${path}" has an invalid type definition: ${String(type)}`,
+        {
+          field: path,
+          type: String(type)
+        }
+      );
+    }
+    if (SCALAR_FIELD_TYPES.has(type)) continue;
+    const vectorMatch = VECTOR_PATTERN.exec(type);
+    if (vectorMatch) {
+      const dimension = Number.parseInt(vectorMatch[1], 10);
+      if (dimension <= 0) {
+        throw new NarsilError(
+          ErrorCodes.SCHEMA_INVALID_VECTOR_DIMENSION,
+          `Vector field "${path}" must have a positive dimension, got ${dimension}`,
+          { field: path, dimension }
+        );
+      }
+      continue;
+    }
+    throw new NarsilError(ErrorCodes.SCHEMA_INVALID_TYPE, `Field "${path}" has an unsupported type: "${type}"`, {
+      field: path,
+      type
+    });
+  }
+}
+function validateSchema(schema) {
+  if (!isPlainObject(schema)) {
+    throw new NarsilError(ErrorCodes.SCHEMA_INVALID_TYPE, "Schema must be a plain object", {
+      received: typeof schema
+    });
+  }
+  if (Object.keys(schema).length === 0) {
+    throw new NarsilError(ErrorCodes.SCHEMA_INVALID_TYPE, "Schema must define at least one field");
+  }
+  validateSchemaFields(schema, 1, "");
+}
+function flattenRecursive(schema, prefix, result) {
+  for (const [field, type] of Object.entries(schema)) {
+    const path = prefix ? `${prefix}.${field}` : field;
+    if (isPlainObject(type)) {
+      flattenRecursive(type, path, result);
+    } else {
+      result[path] = type;
+    }
+  }
+}
+function flattenSchema(schema) {
+  const result = {};
+  flattenRecursive(schema, "", result);
+  return result;
+}
+function extractVectorFieldsFromSchema(schema) {
+  const flat = flattenSchema(schema);
+  const result = /* @__PURE__ */ new Map();
+  for (const [fieldPath, fieldType] of Object.entries(flat)) {
+    const match = VECTOR_PATTERN.exec(fieldType);
+    if (match) {
+      result.set(fieldPath, Number.parseInt(match[1], 10));
+    }
+  }
+  return result;
+}
+
+// src/schema/validator/field-values.ts
+function validateGeopoint(path, value) {
+  if (!isPlainObject(value)) {
+    throw new NarsilError(
+      ErrorCodes.SCHEMA_INVALID_GEOPOINT,
+      `Field "${path}" expected a geopoint object with lat and lon`,
+      {
+        field: path,
+        received: Array.isArray(value) ? "array" : typeof value
+      }
+    );
+  }
+  if (typeof value.lat !== "number" || typeof value.lon !== "number" || Number.isNaN(value.lat) || Number.isNaN(value.lon)) {
+    throw new NarsilError(ErrorCodes.SCHEMA_INVALID_GEOPOINT, `Field "${path}" geopoint requires numeric lat and lon`, {
+      field: path,
+      lat: Number.isNaN(value.lat) ? "NaN" : typeof value.lat,
+      lon: Number.isNaN(value.lon) ? "NaN" : typeof value.lon
+    });
+  }
+  if (value.lat < -90 || value.lat > 90) {
+    throw new NarsilError(
+      ErrorCodes.SCHEMA_INVALID_GEOPOINT,
+      `Field "${path}" geopoint lat must be between -90 and 90`,
+      {
+        field: path,
+        lat: value.lat
+      }
+    );
+  }
+  if (value.lon < -180 || value.lon > 180) {
+    throw new NarsilError(
+      ErrorCodes.SCHEMA_INVALID_GEOPOINT,
+      `Field "${path}" geopoint lon must be between -180 and 180`,
+      {
+        field: path,
+        lon: value.lon
+      }
+    );
+  }
+}
+function validateVector(path, value, expectedDimension) {
+  const isArray = Array.isArray(value);
+  const isFloat32 = value instanceof Float32Array;
+  if (!isArray && !isFloat32) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Field "${path}" expected a vector (Array or Float32Array)`,
+      { field: path, received: typeof value }
+    );
+  }
+  const arr = value;
+  if (arr.length !== expectedDimension) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Field "${path}" expected vector of dimension ${expectedDimension}, got ${arr.length}`,
+      { field: path, expected: expectedDimension, received: arr.length }
+    );
+  }
+  for (let i = 0; i < arr.length; i++) {
+    if (typeof arr[i] !== "number" || Number.isNaN(arr[i])) {
+      throw new NarsilError(
+        ErrorCodes.DOC_VALIDATION_FAILED,
+        `Field "${path}" vector element at index ${i} is not a valid number`,
+        { field: path, index: i, value: arr[i] }
+      );
+    }
+  }
+}
+function validateTypedArray(path, value, elementType) {
+  if (!Array.isArray(value)) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, `Field "${path}" expected an array`, {
+      field: path,
+      received: typeof value
+    });
+  }
+  for (let i = 0; i < value.length; i++) {
+    const el = value[i];
+    if (typeof el !== elementType) {
+      throw new NarsilError(
+        ErrorCodes.DOC_VALIDATION_FAILED,
+        `Field "${path}" array element at index ${i} expected ${elementType}, got ${typeof el}`,
+        { field: path, index: i, expected: elementType, received: typeof el }
+      );
+    }
+    if (elementType === "number" && Number.isNaN(el)) {
+      throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, `Field "${path}" array element at index ${i} is NaN`, {
+        field: path,
+        index: i
+      });
+    }
+  }
+}
+function validateFieldValue(path, value, type) {
+  switch (type) {
+    case "string":
+    case SORTABLE_TEXT_FIELD_TYPE:
+      if (typeof value !== "string") {
+        throw new NarsilError(
+          ErrorCodes.DOC_VALIDATION_FAILED,
+          `Field "${path}" expected string, got ${typeof value}`,
+          {
+            field: path,
+            expected: "string",
+            received: typeof value
+          }
+        );
+      }
+      return;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, `Field "${path}" expected a valid number`, {
+          field: path,
+          expected: "number",
+          received: Number.isNaN(value) ? "NaN" : typeof value
+        });
+      }
+      return;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        throw new NarsilError(
+          ErrorCodes.DOC_VALIDATION_FAILED,
+          `Field "${path}" expected boolean, got ${typeof value}`,
+          {
+            field: path,
+            expected: "boolean",
+            received: typeof value
+          }
+        );
+      }
+      return;
+    case "enum":
+      if (typeof value !== "string") {
+        throw new NarsilError(
+          ErrorCodes.DOC_VALIDATION_FAILED,
+          `Field "${path}" expected enum (string), got ${typeof value}`,
+          {
+            field: path,
+            expected: "enum",
+            received: typeof value
+          }
+        );
+      }
+      return;
+    case "geopoint":
+      validateGeopoint(path, value);
+      return;
+    case "string[]":
+      validateTypedArray(path, value, "string");
+      return;
+    case "number[]":
+      validateTypedArray(path, value, "number");
+      return;
+    case "boolean[]":
+      validateTypedArray(path, value, "boolean");
+      return;
+    case "enum[]":
+      validateTypedArray(path, value, "string");
+      return;
+    default: {
+      const vectorMatch = VECTOR_PATTERN.exec(type);
+      if (vectorMatch) {
+        validateVector(path, value, Number.parseInt(vectorMatch[1], 10));
+      }
+    }
+  }
+}
+
+// src/schema/validator/storable.ts
+var RESERVED_OBJECT_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function reject(path, reason) {
+  throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, `Field "${path === "" ? "(document)" : path}" ${reason}`, {
+    field: path
+  });
+}
+function isPlainObject2(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function walkStorable(value, path, depth, ancestors, skip) {
+  if (value === null || value === void 0) return;
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean") return;
+  if (kind === "number") return;
+  if (kind === "bigint" || kind === "symbol" || kind === "function") {
+    reject(path, `holds a ${kind}, which cannot be stored or recovered`);
+  }
+  const container = value;
+  if (container instanceof Date || container instanceof Uint8Array) return;
+  const isArray = Array.isArray(container);
+  if (!isArray && !isPlainObject2(container)) {
+    reject(
+      path,
+      "holds a value that does not survive storage; use plain objects, arrays, strings, numbers, booleans, dates, or Uint8Array bytes"
+    );
+  }
+  if (depth >= MAX_DOCUMENT_NESTING_DEPTH) {
+    reject(path, `nests deeper than ${MAX_DOCUMENT_NESTING_DEPTH} levels`);
+  }
+  if (ancestors.has(container)) {
+    reject(path, "refers back to one of its own ancestors");
+  }
+  ancestors.add(container);
+  if (isArray) {
+    const items = container;
+    for (let i = 0; i < items.length; i++) {
+      walkStorable(items[i], `${path}[${i}]`, depth + 1, ancestors, skip);
+    }
+  } else {
+    const record = container;
+    for (const key of Object.keys(record)) {
+      const keyPath = path === "" ? key : `${path}.${key}`;
+      if (RESERVED_OBJECT_KEYS.has(key)) {
+        reject(keyPath, "uses a reserved object key");
+      }
+      if (skip.has(keyPath)) continue;
+      walkStorable(record[key], keyPath, depth + 1, ancestors, skip);
+    }
+  }
+  ancestors.delete(container);
+}
+function assertStorableDocument(document, skipFieldPaths) {
+  walkStorable(document, "", 0, /* @__PURE__ */ new Set(), skipFieldPaths ?? /* @__PURE__ */ new Set());
+}
+
+// src/schema/validator/document.ts
+var vectorPathCache = /* @__PURE__ */ new WeakMap();
+function vectorFieldPaths(schema) {
+  let paths = vectorPathCache.get(schema);
+  if (paths !== void 0) return paths;
+  paths = /* @__PURE__ */ new Set();
+  const collect = (level, prefix) => {
+    for (const [field, type] of Object.entries(level)) {
+      const path = prefix === "" ? field : `${prefix}.${field}`;
+      if (typeof type === "string" && VECTOR_PATTERN.test(type)) {
+        paths?.add(path);
+      } else if (isPlainObject(type)) {
+        collect(type, path);
+      }
+    }
+  };
+  collect(schema, "");
+  vectorPathCache.set(schema, paths);
+  return paths;
+}
+function validateDocumentFields(doc, schema, prefix) {
+  for (const [field, type] of Object.entries(schema)) {
+    const path = prefix ? `${prefix}.${field}` : field;
+    const value = doc[field];
+    if (value === void 0 || value === null) continue;
+    if (isPlainObject(type)) {
+      if (!isPlainObject(value)) {
+        throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, `Field "${path}" expected an object`, {
+          field: path,
+          received: Array.isArray(value) ? "array" : typeof value
+        });
+      }
+      validateDocumentFields(value, type, path);
+      continue;
+    }
+    validateFieldValue(path, value, type);
+  }
+}
+function validateDocument(document, schema) {
+  if (!isPlainObject(document)) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document must be a plain object", {
+      received: typeof document
+    });
+  }
+  assertStorableDocument(document, vectorFieldPaths(schema));
+  validateDocumentFields(document, schema, "");
+}
+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)) {
+      extras.push(path);
+      continue;
+    }
+    const schemaType = schema[key];
+    if (isPlainObject(schemaType) && isPlainObject(doc[key])) {
+      collectExtraFields(doc[key], schemaType, path, extras);
+    }
+  }
+}
+function validateDocumentStrict(document, schema) {
+  const extras = [];
+  collectExtraFields(document, schema, "", extras);
+  if (extras.length > 0) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Document contains fields not defined in schema: ${extras.join(", ")}`,
+      { extraFields: extras }
+    );
+  }
+}
+function resolveNestedValue(document, path) {
+  if (!path.includes(".")) return document[path];
+  const segments = path.split(".");
+  let current = document;
+  for (const segment of segments) {
+    if (current === null || current === void 0 || typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function validateRequiredFields(document, required) {
+  if (required.length === 0) return;
+  for (const field of required) {
+    const value = resolveNestedValue(document, field);
+    if (value === void 0 || value === null) {
+      throw new NarsilError(ErrorCodes.DOC_MISSING_REQUIRED_FIELD, `Document is missing required field "${field}"`, {
+        field
+      });
+    }
+  }
+}
+
+// src/schema/validator/vector-promotion.ts
+var QUANTIZATION_MODES = /* @__PURE__ */ new Set(["osq8", "osq4", "osq2", "osq1", "none"]);
+var STORAGE_MODES = /* @__PURE__ */ new Set(["memory", "disk"]);
+function fail(message, details) {
+  throw new NarsilError(ErrorCodes.CONFIG_INVALID, message, details);
+}
+function isPositiveInteger(value) {
+  return Number.isInteger(value) && value >= 1;
+}
+function isQuantizationMode(value) {
+  return typeof value === "string" && QUANTIZATION_MODES.has(value);
+}
+function isStorageMode(value) {
+  return typeof value === "string" && STORAGE_MODES.has(value);
+}
+function validateVectorStorage(config, filesystemDurability) {
+  if (config?.storage === "disk" && !filesystemDurability) {
+    fail("vectorPromotion.storage 'disk' needs filesystem durability, because a checkpoint file holds the vectors", {
+      storage: config.storage
+    });
+  }
+}
+function validateVectorPromotion(config) {
+  if (config === void 0) return;
+  if (config.threshold !== void 0 && !isPositiveInteger(config.threshold)) {
+    fail("vectorPromotion.threshold must be a positive integer", { threshold: config.threshold });
+  }
+  const quantization = config.quantization;
+  if (quantization !== void 0 && !isQuantizationMode(quantization)) {
+    fail("vectorPromotion.quantization must be 'osq8', 'osq4', 'osq2', 'osq1', or 'none'", { quantization });
+  }
+  const storage = config.storage;
+  if (storage !== void 0 && !isStorageMode(storage)) {
+    fail("vectorPromotion.storage must be 'memory' or 'disk'", { storage });
+  }
+  const hnsw = config.hnswConfig;
+  if (hnsw === void 0) return;
+  if (hnsw.m !== void 0 && (!isPositiveInteger(hnsw.m) || hnsw.m > MAX_M)) {
+    fail(`vectorPromotion.hnswConfig.m must be a positive integer no greater than ${MAX_M}`, { m: hnsw.m });
+  }
+  if (hnsw.efConstruction !== void 0 && !isPositiveInteger(hnsw.efConstruction)) {
+    fail("vectorPromotion.hnswConfig.efConstruction must be a positive integer", {
+      efConstruction: hnsw.efConstruction
+    });
+  }
+  const metric = hnsw.metric;
+  if (metric !== void 0 && metric !== "cosine" && metric !== "dotProduct" && metric !== "euclidean") {
+    fail("vectorPromotion.hnswConfig.metric must be 'cosine', 'dotProduct', or 'euclidean'", { metric });
+  }
+}
+
+// src/search/constants.ts
+var RESULT_WINDOW = 1e4;
+var DEFAULT_PAGE_SIZE = 10;
+var MAX_CURSOR_LENGTH = 40960;
+var MAX_SORT_FIELDS = 8;
+var MAX_SORT_FIELD_NAME_LENGTH = 255;
+var MAX_CURSOR_ANCHOR_CODE_POINTS = 512;
+var PREFIX_MAX_EXPANSIONS = 50;
+
+export { DEFAULT_PAGE_SIZE, MAX_CURSOR_ANCHOR_CODE_POINTS, MAX_CURSOR_LENGTH, MAX_NESTING_DEPTH, MAX_SORT_FIELDS, MAX_SORT_FIELD_NAME_LENGTH, PREFIX_MAX_EXPANSIONS, PROTOTYPE_POLLUTION_KEYS, RESULT_WINDOW, SORTABLE_TEXT_FIELD_TYPE, VECTOR_PATTERN, extractVectorFieldsFromSchema, flattenSchema, isQuantizationMode, isStorageMode, isTextFieldType, validateDocument, validateDocumentStrict, validateRequiredFields, validateSchema, validateVectorPromotion, validateVectorStorage };

package/dist/{client-CBOVHdjp.d.ts → client-BMJWVxOP.d.ts}

@@ -1,6 +1,6 @@
-import { P as PartitionConfig, A as AnyDocument, b as InsertOptions, W as WriteOptions } from './schema-BqRx9t4E.js';
-import { V as VectorMaintenanceResult, M as MemoryStats, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult } from './memory-Bzd5xcEW.js';
-import { e as TaskRecord, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-Bn4R1NPN.js';
+import { P as PartitionConfig, A as AnyDocument, a as InsertOptions, W as WriteOptions } from './schema-OSWaaZzx.js';
+import { V as VectorMaintenanceResult, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult } from './memory-OmgkX_Z2.js';
+import { e as TaskRecord, M as MemoryStatsResponse, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-DiF1c9v2.js';
 
 /**
  * This is the `fetch` implementation the client sends every request through.
@@ -197,13 +197,13 @@ interface AdminOperations {
     rebuildAnalysis(indexName: string, options?: RequestOptions): Promise<TaskRecord>;
     /**
      * Reports the server process's heap usage, its estimate of what the indexes
-     * hold, and each worker's heap.
+     * hold, each worker's heap, and how many worker threads receive requests.
      *
      * @param options - This sets the signal, the deadline, and the headers for
      * this request.
      * @returns The figures are what you size a host from.
      */
-    getMemoryStats(options?: RequestOptions): Promise<MemoryStats>;
+    getMemoryStats(options?: RequestOptions): Promise<MemoryStatsResponse>;
 }
 
 /**