@delali/narsil 0.1.6 → 0.1.7

package/dist/index.mjs

@@ -1,12 +1,872 @@
-import { createDirectExecutor, createPartitionRouter, getLanguage, validateSchema, deserializePayloadV2, tokenize, fanOutQuery, createPartitionIndex, detectRuntime, fnv1a, kWayMerge } from './chunk-TFWBALU4.mjs';
-export { getLanguage, registerLanguage } from './chunk-TFWBALU4.mjs';
-export { isSimdAvailable } from './chunk-GVN2W4VA.mjs';
-import './chunk-WYC635GI.mjs';
-import { NarsilError, ErrorCodes } from './chunk-7GKPWGCN.mjs';
-export { ErrorCodes, NarsilError } from './chunk-7GKPWGCN.mjs';
+import { createDirectExecutor, createPartitionRouter, validateSchema, getLanguage, deserializePayloadV2, extractVectorFieldsFromSchema, tokenize, fanOutQuery, validateRequiredFields, flattenSchema, getNestedValue, detectRuntime, fnv1a, kWayMerge, createPartitionIndex } from './chunk-KHL4RPC3.mjs';
+export { clearNormalizationCache, configureNormalizationCache, getLanguage, getNormalizationCacheSize, registerLanguage, resetNormalizationCache } from './chunk-KHL4RPC3.mjs';
+export { isSimdAvailable } from './chunk-VVORJOXR.mjs';
+import './chunk-I24SGLFS.mjs';
+import { ErrorCodes, NarsilError } from './chunk-R2C2EQGO.mjs';
+export { ErrorCodes, NarsilError } from './chunk-R2C2EQGO.mjs';
 import { generateId, isValidWorkerResponse, createRequestId } from './chunk-HRABJLPB.mjs';
 import { decode } from '@msgpack/msgpack';
 
+// src/engine/embed.ts
+function validateVector(vector, targetField, expectedDimensions) {
+  if (!(vector instanceof Float32Array)) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_FAILED,
+      `Adapter returned ${typeof vector} for field "${targetField}", expected Float32Array`,
+      { field: targetField, returnedType: typeof vector }
+    );
+  }
+  if (vector.length !== expectedDimensions) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_DIMENSION_MISMATCH,
+      `Adapter returned ${vector.length}-dimensional vector for field "${targetField}", expected ${expectedDimensions}`,
+      { field: targetField, expected: expectedDimensions, actual: vector.length }
+    );
+  }
+  for (let i = 0; i < vector.length; i++) {
+    if (Number.isNaN(vector[i])) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_FAILED,
+        `Adapter returned vector with NaN at index ${i} for field "${targetField}"`,
+        { field: targetField, index: i }
+      );
+    }
+  }
+  return vector;
+}
+function resolveFieldValue(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 setFieldValue(document, path, value) {
+  if (!path.includes(".")) {
+    document[path] = value;
+    return;
+  }
+  const segments = path.split(".");
+  let current = document;
+  for (let i = 0; i < segments.length - 1; i++) {
+    let next = current[segments[i]];
+    if (next === null || next === void 0 || typeof next !== "object") {
+      next = {};
+      current[segments[i]] = next;
+    }
+    current = next;
+  }
+  current[segments[segments.length - 1]] = value;
+}
+function deleteFieldValue(document, path) {
+  if (!path.includes(".")) {
+    delete document[path];
+    return;
+  }
+  const segments = path.split(".");
+  let current = document;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const next = current[segments[i]];
+    if (next === null || next === void 0 || typeof next !== "object") return;
+    current = next;
+  }
+  delete current[segments[segments.length - 1]];
+}
+function collectSourceText(document, sourceFields, targetField, documentIndex) {
+  const sources = Array.isArray(sourceFields) ? sourceFields : [sourceFields];
+  const parts = [];
+  for (const source of sources) {
+    const value = resolveFieldValue(document, source);
+    if (value === void 0 || value === null || value === "") continue;
+    if (typeof value !== "string") {
+      throw new NarsilError(
+        ErrorCodes.DOC_VALIDATION_FAILED,
+        `Embedding source field "${source}" must be a string, got ${typeof value}`,
+        { field: source, targetField }
+      );
+    }
+    parts.push(value);
+  }
+  if (parts.length === 0) {
+    const details = { field: targetField };
+    if (documentIndex !== void 0) {
+      details.documentIndex = documentIndex;
+    }
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_NO_SOURCE,
+      `All source fields for embedding target "${targetField}" are missing or empty`,
+      details
+    );
+  }
+  return parts.join("\n");
+}
+function wrapAdapterError(err, targetField) {
+  if (err instanceof NarsilError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new NarsilError(ErrorCodes.EMBEDDING_FAILED, `Embedding failed for field "${targetField}": ${message}`, {
+    field: targetField,
+    cause: message
+  });
+}
+async function embedDocumentFields(document, embeddingConfig, adapter, signal) {
+  const embeddedFields = /* @__PURE__ */ new Set();
+  try {
+    for (const [targetField, sourceFields] of Object.entries(embeddingConfig.fields)) {
+      const existing = resolveFieldValue(document, targetField);
+      if (existing !== void 0 && existing !== null) continue;
+      const text = collectSourceText(document, sourceFields, targetField);
+      let vector;
+      try {
+        const raw = await adapter.embed(text, "document", signal);
+        vector = validateVector(raw, targetField, adapter.dimensions);
+      } catch (err) {
+        throw wrapAdapterError(err, targetField);
+      }
+      setFieldValue(document, targetField, vector);
+      embeddedFields.add(targetField);
+    }
+  } catch (err) {
+    for (const field of embeddedFields) {
+      deleteFieldValue(document, field);
+    }
+    throw err;
+  }
+  return embeddedFields;
+}
+var SOURCE_FAILURE_CODES = /* @__PURE__ */ new Set([ErrorCodes.EMBEDDING_NO_SOURCE, ErrorCodes.DOC_VALIDATION_FAILED]);
+function isDocumentSourceError(err) {
+  return err instanceof NarsilError && SOURCE_FAILURE_CODES.has(err.code);
+}
+async function embedBatchDocumentFields(documents, embeddingConfig, adapter, signal) {
+  const embedded = /* @__PURE__ */ new Map();
+  const failed = /* @__PURE__ */ new Map();
+  try {
+    for (const [targetField, sourceFields] of Object.entries(embeddingConfig.fields)) {
+      const needsEmbedding = [];
+      for (let i = 0; i < documents.length; i++) {
+        if (failed.has(i)) continue;
+        const doc = documents[i];
+        const existing = resolveFieldValue(doc, targetField);
+        if (existing !== void 0 && existing !== null) continue;
+        try {
+          const text = collectSourceText(doc, sourceFields, targetField, i);
+          needsEmbedding.push({ docIndex: i, text });
+        } catch (err) {
+          if (isDocumentSourceError(err)) {
+            failed.set(i, err);
+          } else {
+            throw err;
+          }
+        }
+      }
+      if (needsEmbedding.length === 0) continue;
+      const texts = needsEmbedding.map((entry) => entry.text);
+      let vectors;
+      try {
+        if (adapter.embedBatch) {
+          vectors = await adapter.embedBatch(texts, "document", signal);
+        } else {
+          vectors = [];
+          const concurrency = 8;
+          for (let start = 0; start < texts.length; start += concurrency) {
+            const chunk = texts.slice(start, start + concurrency);
+            const chunkResults = await Promise.all(chunk.map((t) => adapter.embed(t, "document", signal)));
+            vectors.push(...chunkResults);
+          }
+        }
+      } catch (err) {
+        throw wrapAdapterError(err, targetField);
+      }
+      if (vectors.length !== needsEmbedding.length) {
+        throw new NarsilError(
+          ErrorCodes.EMBEDDING_FAILED,
+          `Adapter returned ${vectors.length} vectors for ${needsEmbedding.length} inputs on field "${targetField}"`,
+          { field: targetField, expected: needsEmbedding.length, actual: vectors.length }
+        );
+      }
+      for (let j = 0; j < needsEmbedding.length; j++) {
+        const { docIndex } = needsEmbedding[j];
+        const validated = validateVector(vectors[j], targetField, adapter.dimensions);
+        setFieldValue(documents[docIndex], targetField, validated);
+        let fieldSet = embedded.get(docIndex);
+        if (!fieldSet) {
+          fieldSet = /* @__PURE__ */ new Set();
+          embedded.set(docIndex, fieldSet);
+        }
+        fieldSet.add(targetField);
+      }
+    }
+  } catch (err) {
+    for (const [docIndex, fields] of embedded) {
+      for (const field of fields) {
+        deleteFieldValue(documents[docIndex], field);
+      }
+    }
+    throw err;
+  }
+  return { embedded, failed };
+}
+
+// src/engine/validation.ts
+var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var MAX_INDEX_NAME_LENGTH = 256;
+var MAX_DOC_ID_LENGTH = 512;
+var BATCH_CHUNK_SIZE = 1e3;
+var MAX_LIMIT = 1e4;
+var MAX_OFFSET = 1e5;
+var DEFAULT_LIMIT = 10;
+var DEFAULT_OFFSET = 0;
+function now() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+function validateIndexName(name) {
+  if (!name || name.length === 0) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "Index name must not be empty", { indexName: name });
+  }
+  if (name.length > MAX_INDEX_NAME_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.INDEX_NOT_FOUND,
+      `Index name must not exceed ${MAX_INDEX_NAME_LENGTH} characters`,
+      {
+        indexName: name,
+        length: name.length
+      }
+    );
+  }
+  if (!INDEX_NAME_PATTERN.test(name)) {
+    throw new NarsilError(
+      ErrorCodes.INDEX_NOT_FOUND,
+      `Index name "${name}" contains invalid characters; use alphanumeric, dots, hyphens, and underscores only`,
+      { indexName: name }
+    );
+  }
+  if (name.includes("..")) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index name "${name}" must not contain ".."`, { indexName: name });
+  }
+}
+function validateDocId(docId) {
+  if (!docId || docId.length === 0) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not be empty", { docId });
+  }
+  if (docId.length > MAX_DOC_ID_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Document ID must not exceed ${MAX_DOC_ID_LENGTH} characters`,
+      {
+        docId,
+        length: docId.length
+      }
+    );
+  }
+  if (docId.includes("\0")) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not contain null bytes", { docId });
+  }
+}
+function clampLimit(limit) {
+  if (limit === void 0) return DEFAULT_LIMIT;
+  return Math.max(0, Math.min(limit, MAX_LIMIT));
+}
+function clampOffset(offset) {
+  if (offset === void 0) return DEFAULT_OFFSET;
+  return Math.max(0, Math.min(offset, MAX_OFFSET));
+}
+
+// src/engine/vector-coordinator.ts
+function extractVectorFromDoc(document, fieldPath) {
+  const value = getNestedValue(document, fieldPath);
+  if (value === void 0 || value === null) return null;
+  if (value instanceof Float32Array) return value;
+  if (!Array.isArray(value)) return null;
+  const arr = new Float32Array(value.length);
+  for (let i = 0; i < value.length; i++) {
+    const n = value[i];
+    if (typeof n !== "number" || !Number.isFinite(n)) return null;
+    arr[i] = n;
+  }
+  return arr;
+}
+function deleteNestedValue(obj, path) {
+  if (!path.includes(".")) {
+    delete obj[path];
+    return;
+  }
+  const segments = path.split(".");
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const next = current[segments[i]];
+    if (next === null || next === void 0 || typeof next !== "object") return;
+    current = next;
+  }
+  delete current[segments[segments.length - 1]];
+}
+function vectorsEqual(a, b) {
+  if (!a) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function validateVectorDimensions(vectors, vecIndexes) {
+  for (const [fieldPath, vector] of vectors) {
+    const vecIndex = vecIndexes.get(fieldPath);
+    if (!vecIndex) continue;
+    if (vector.length !== vecIndex.dimension) {
+      throw new NarsilError(
+        ErrorCodes.VECTOR_DIMENSION_MISMATCH,
+        `Vector dimension mismatch for field "${fieldPath}": expected ${vecIndex.dimension}, got ${vector.length}`,
+        { field: fieldPath, expected: vecIndex.dimension, received: vector.length }
+      );
+    }
+  }
+}
+function prepareDocumentVectors(document, vectorFieldPaths, vecIndexes) {
+  if (vecIndexes.size === 0) {
+    return { partitionDoc: document, extractedVectors: /* @__PURE__ */ new Map() };
+  }
+  const extractedVectors = /* @__PURE__ */ new Map();
+  for (const fieldPath of vectorFieldPaths) {
+    const vec = extractVectorFromDoc(document, fieldPath);
+    if (vec) {
+      extractedVectors.set(fieldPath, vec);
+    }
+  }
+  if (extractedVectors.size === 0) {
+    return { partitionDoc: document, extractedVectors };
+  }
+  const partitionDoc = shallowCopyExcluding(document, extractedVectors.keys());
+  return { partitionDoc, extractedVectors };
+}
+function shallowCopyExcluding(document, fieldPaths) {
+  const topLevelExcludes = /* @__PURE__ */ new Set();
+  const nestedPaths = [];
+  for (const path of fieldPaths) {
+    if (!path.includes(".")) {
+      topLevelExcludes.add(path);
+    } else {
+      nestedPaths.push(path);
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(document)) {
+    if (topLevelExcludes.has(key)) continue;
+    result[key] = document[key];
+  }
+  for (const path of nestedPaths) {
+    const segments = path.split(".");
+    const topKey = segments[0];
+    if (!(topKey in result) || result[topKey] === null || typeof result[topKey] !== "object") continue;
+    const source = document[topKey];
+    let target = { ...source };
+    result[topKey] = target;
+    for (let i = 1; i < segments.length - 1; i++) {
+      const seg = segments[i];
+      const next = target[seg];
+      if (next === null || next === void 0 || typeof next !== "object") break;
+      const copy = { ...next };
+      target[seg] = copy;
+      target = copy;
+    }
+    delete target[segments[segments.length - 1]];
+  }
+  return result;
+}
+function insertDocumentVectors(docId, vectors, vecIndexes) {
+  const insertedFields = [];
+  try {
+    for (const [fieldPath, vector] of vectors) {
+      const vecIndex = vecIndexes.get(fieldPath);
+      if (!vecIndex) continue;
+      vecIndex.insert(docId, vector);
+      insertedFields.push(fieldPath);
+    }
+  } catch (err) {
+    for (const fieldPath of insertedFields) {
+      const vecIndex = vecIndexes.get(fieldPath);
+      if (vecIndex) {
+        vecIndex.remove(docId);
+      }
+    }
+    throw err;
+  }
+  return insertedFields;
+}
+function removeDocumentVectors(docId, vecIndexes) {
+  for (const [, vecIndex] of vecIndexes) {
+    vecIndex.remove(docId);
+  }
+}
+function updateDocumentVectors(docId, vectors, vecIndexes) {
+  const updatedFields = [];
+  try {
+    for (const [fieldPath, newVec] of vectors) {
+      const vecIndex = vecIndexes.get(fieldPath);
+      if (!vecIndex) continue;
+      if (newVec === null) {
+        if (vecIndex.has(docId)) {
+          const oldVec2 = vecIndex.getVector(docId);
+          vecIndex.remove(docId);
+          updatedFields.push({ fieldPath, oldVec: oldVec2 });
+        }
+        continue;
+      }
+      const oldVec = vecIndex.getVector(docId);
+      if (vectorsEqual(oldVec, newVec)) continue;
+      vecIndex.remove(docId);
+      try {
+        vecIndex.insert(docId, newVec);
+        updatedFields.push({ fieldPath, oldVec });
+      } catch (err) {
+        if (oldVec) {
+          vecIndex.insert(docId, oldVec);
+        }
+        throw err;
+      }
+    }
+  } catch (err) {
+    for (const { fieldPath, oldVec } of updatedFields) {
+      const vecIndex = vecIndexes.get(fieldPath);
+      if (!vecIndex) continue;
+      vecIndex.remove(docId);
+      if (oldVec) {
+        vecIndex.insert(docId, oldVec);
+      }
+    }
+    throw err;
+  }
+}
+
+// src/engine/mutations.ts
+async function insertDocument(ctx, indexName, document, docId, options) {
+  ctx.guardShutdown();
+  const entry = ctx.requireIndex(indexName);
+  const resolvedDocId = docId ?? ctx.idGenerator();
+  validateDocId(resolvedDocId);
+  if (ctx.bufferIfRebalancing(indexName, { action: "insert", docId: resolvedDocId, document, indexName })) {
+    return resolvedDocId;
+  }
+  await ctx.pluginRegistry.runHook("beforeInsert", { indexName, docId: resolvedDocId, document });
+  if (entry.config.required && entry.config.required.length > 0) {
+    validateRequiredFields(document, entry.config.required);
+  }
+  if (entry.embeddingAdapter && entry.config.embedding) {
+    await embedDocumentFields(
+      document,
+      entry.config.embedding,
+      entry.embeddingAdapter,
+      ctx.abortController.signal
+    );
+  }
+  const insertManager = ctx.requireManager(indexName);
+  const insertVecIndexes = insertManager.getVectorIndexes();
+  const { partitionDoc, extractedVectors } = prepareDocumentVectors(
+    document,
+    entry.vectorFieldPaths,
+    insertVecIndexes
+  );
+  if (extractedVectors.size > 0) {
+    validateVectorDimensions(extractedVectors, insertVecIndexes);
+  }
+  await ctx.executor.execute({
+    type: "insert",
+    indexName,
+    docId: resolvedDocId,
+    document: partitionDoc,
+    requestId: resolvedDocId,
+    skipClone: extractedVectors.size > 0 ? true : options?.skipClone
+  });
+  try {
+    insertDocumentVectors(resolvedDocId, extractedVectors, insertVecIndexes);
+  } catch (err) {
+    try {
+      await ctx.executor.execute({ type: "remove", indexName, docId: resolvedDocId, requestId: resolvedDocId });
+    } catch (rollbackErr) {
+      console.warn(
+        `Rollback failed for doc "${resolvedDocId}" during insert atomicity:`,
+        rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)
+      );
+    }
+    throw err;
+  }
+  try {
+    await ctx.pluginRegistry.runHook("afterInsert", { indexName, docId: resolvedDocId, document });
+  } catch (err) {
+    console.warn("afterInsert plugin hook error:", err instanceof Error ? err.message : String(err));
+  }
+  ctx.flushManager?.markDirty(indexName, 0);
+  await ctx.orchestrator.replicateToWorkers({
+    type: "insert",
+    indexName,
+    docId: resolvedDocId,
+    document,
+    requestId: `replicate-insert-${resolvedDocId}`,
+    skipClone: options?.skipClone
+  });
+  for (const fieldPath of extractedVectors.keys()) {
+    const vecIndex = insertVecIndexes.get(fieldPath);
+    if (vecIndex) {
+      vecIndex.scheduleBuild();
+    }
+  }
+  await ctx.orchestrator.checkPromotion();
+  return resolvedDocId;
+}
+async function insertDocumentBatch(ctx, indexName, documents, options) {
+  ctx.guardShutdown();
+  const entry = ctx.requireIndex(indexName);
+  const succeeded = [];
+  const succeededDocs = [];
+  const failed = [];
+  const hasBeforeHook = ctx.pluginRegistry.hasHooks("beforeInsert");
+  const hasAfterHook = ctx.pluginRegistry.hasHooks("afterInsert");
+  const hasRequired = entry.config.required && entry.config.required.length > 0;
+  const hasEmbedding = entry.embeddingAdapter && entry.config.embedding;
+  const batchManager = ctx.requireManager(indexName);
+  const batchVecIndexes = batchManager.getVectorIndexes();
+  const batchVectorFieldPaths = batchVecIndexes.size > 0 ? entry.vectorFieldPaths : /* @__PURE__ */ new Set();
+  const touchedVectorFields = /* @__PURE__ */ new Set();
+  for (let chunkStart = 0; chunkStart < documents.length; chunkStart += BATCH_CHUNK_SIZE) {
+    if (ctx.abortController.signal.aborted) break;
+    const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, documents.length);
+    const chunkFailedIndexes = /* @__PURE__ */ new Set();
+    if (hasRequired) {
+      for (let i = chunkStart; i < chunkEnd; i++) {
+        try {
+          validateRequiredFields(documents[i], entry.config.required);
+        } catch (err) {
+          chunkFailedIndexes.add(i);
+          failed.push({
+            docId: "",
+            error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, String(err))
+          });
+        }
+      }
+    }
+    if (hasEmbedding) {
+      const embeddableSlice = [];
+      const embeddableOriginalIndexes = [];
+      for (let i = chunkStart; i < chunkEnd; i++) {
+        if (chunkFailedIndexes.has(i)) continue;
+        embeddableSlice.push(documents[i]);
+        embeddableOriginalIndexes.push(i);
+      }
+      if (embeddableSlice.length > 0) {
+        try {
+          const embedResult = await embedBatchDocumentFields(
+            embeddableSlice,
+            entry.config.embedding,
+            entry.embeddingAdapter,
+            ctx.abortController.signal
+          );
+          for (const [sliceIndex, error] of embedResult.failed) {
+            const originalIdx = embeddableOriginalIndexes[sliceIndex];
+            chunkFailedIndexes.add(originalIdx);
+            failed.push({ docId: "", error });
+          }
+        } catch (err) {
+          const embeddingError = err instanceof NarsilError ? err : new NarsilError(ErrorCodes.EMBEDDING_FAILED, String(err));
+          for (const originalIdx of embeddableOriginalIndexes) {
+            chunkFailedIndexes.add(originalIdx);
+            failed.push({ docId: "", error: embeddingError });
+          }
+        }
+      }
+    }
+    for (let i = chunkStart; i < chunkEnd; i++) {
+      if (ctx.abortController.signal.aborted) break;
+      if (chunkFailedIndexes.has(i)) continue;
+      const batchDocId = ctx.idGenerator();
+      try {
+        validateDocId(batchDocId);
+        if (hasBeforeHook) {
+          await ctx.pluginRegistry.runHook("beforeInsert", { indexName, docId: batchDocId, document: documents[i] });
+        }
+        const { partitionDoc, extractedVectors } = prepareDocumentVectors(
+          documents[i],
+          batchVectorFieldPaths,
+          batchVecIndexes
+        );
+        if (extractedVectors.size > 0) {
+          validateVectorDimensions(extractedVectors, batchVecIndexes);
+        }
+        const result = ctx.executor.execute({
+          type: "insert",
+          indexName,
+          docId: batchDocId,
+          document: partitionDoc,
+          requestId: batchDocId,
+          skipClone: extractedVectors.size > 0 ? true : options?.skipClone
+        });
+        if (result && typeof result.then === "function") {
+          await result;
+        }
+        try {
+          insertDocumentVectors(batchDocId, extractedVectors, batchVecIndexes);
+        } catch (vecErr) {
+          try {
+            await ctx.executor.execute({ type: "remove", indexName, docId: batchDocId, requestId: batchDocId });
+          } catch (rollbackErr) {
+            console.warn(
+              `Rollback failed for doc "${batchDocId}" during batch insert atomicity:`,
+              rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)
+            );
+          }
+          throw vecErr;
+        }
+        for (const fieldPath of extractedVectors.keys()) {
+          touchedVectorFields.add(fieldPath);
+        }
+        if (hasAfterHook) {
+          try {
+            await ctx.pluginRegistry.runHook("afterInsert", { indexName, docId: batchDocId, document: documents[i] });
+          } catch (err) {
+            console.warn("afterInsert plugin hook error:", err instanceof Error ? err.message : String(err));
+          }
+        }
+        succeeded.push(batchDocId);
+        succeededDocs.push(documents[i]);
+      } catch (err) {
+        failed.push({
+          docId: batchDocId,
+          error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, String(err))
+        });
+      }
+    }
+    if (chunkEnd < documents.length) {
+      await new Promise((r) => setTimeout(r, 0));
+    }
+  }
+  ctx.flushManager?.markDirty(indexName, 0);
+  for (let i = 0; i < succeeded.length; i++) {
+    await ctx.orchestrator.replicateToWorkers({
+      type: "insert",
+      indexName,
+      docId: succeeded[i],
+      document: succeededDocs[i],
+      requestId: `replicate-insert-${succeeded[i]}`,
+      skipClone: options?.skipClone
+    });
+  }
+  for (const fieldPath of touchedVectorFields) {
+    const vecIndex = batchVecIndexes.get(fieldPath);
+    if (vecIndex) {
+      vecIndex.scheduleBuild();
+    }
+  }
+  await ctx.orchestrator.checkPromotion();
+  return { succeeded, failed };
+}
+async function removeDocument(ctx, indexName, docId) {
+  ctx.guardShutdown();
+  ctx.requireIndex(indexName);
+  validateDocId(docId);
+  if (ctx.bufferIfRebalancing(indexName, { action: "remove", docId, indexName })) {
+    return;
+  }
+  await ctx.pluginRegistry.runHook("beforeRemove", { indexName, docId });
+  await ctx.executor.execute({ type: "remove", indexName, docId, requestId: docId });
+  const removeManager = ctx.requireManager(indexName);
+  const removeVecIndexes = removeManager.getVectorIndexes();
+  removeDocumentVectors(docId, removeVecIndexes);
+  try {
+    await ctx.pluginRegistry.runHook("afterRemove", { indexName, docId });
+  } catch (err) {
+    console.warn("afterRemove plugin hook error:", err instanceof Error ? err.message : String(err));
+  }
+  ctx.flushManager?.markDirty(indexName, 0);
+  await ctx.orchestrator.replicateToWorkers({
+    type: "remove",
+    indexName,
+    docId,
+    requestId: `replicate-remove-${docId}`
+  });
+}
+async function removeDocumentBatch(ctx, indexName, docIds) {
+  ctx.guardShutdown();
+  ctx.requireIndex(indexName);
+  const succeeded = [];
+  const failed = [];
+  const manager = ctx.requireManager(indexName);
+  manager.beginBatchRemove();
+  try {
+    for (let chunkStart = 0; chunkStart < docIds.length; chunkStart += BATCH_CHUNK_SIZE) {
+      const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, docIds.length);
+      for (let i = chunkStart; i < chunkEnd; i++) {
+        try {
+          await removeDocument(ctx, indexName, docIds[i]);
+          succeeded.push(docIds[i]);
+        } catch (err) {
+          failed.push({
+            docId: docIds[i],
+            error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_NOT_FOUND, String(err))
+          });
+        }
+      }
+      if (chunkEnd < docIds.length) {
+        await new Promise((r) => setTimeout(r, 0));
+      }
+    }
+  } finally {
+    manager.endBatchRemove();
+  }
+  return { succeeded, failed };
+}
+async function updateDocument(ctx, indexName, docId, document) {
+  ctx.guardShutdown();
+  const entry = ctx.requireIndex(indexName);
+  validateDocId(docId);
+  if (ctx.bufferIfRebalancing(indexName, { action: "update", docId, document, indexName })) {
+    return;
+  }
+  if (entry.embeddingAdapter && entry.config.embedding) {
+    await embedDocumentFields(
+      document,
+      entry.config.embedding,
+      entry.embeddingAdapter,
+      ctx.abortController.signal
+    );
+  }
+  const updateManager = ctx.requireManager(indexName);
+  const oldDocument = updateManager.get(docId);
+  const oldPartitionDoc = updateManager.getRef(docId);
+  const rollbackDoc = oldPartitionDoc ? structuredClone(oldPartitionDoc) : void 0;
+  await ctx.pluginRegistry.runHook("beforeUpdate", {
+    indexName,
+    docId,
+    oldDocument: oldDocument ?? {},
+    newDocument: document
+  });
+  const updateVecIndexes = updateManager.getVectorIndexes();
+  const updateExtractedVectors = /* @__PURE__ */ new Map();
+  if (updateVecIndexes.size > 0) {
+    const dimensionCheckVectors = /* @__PURE__ */ new Map();
+    for (const fieldPath of entry.vectorFieldPaths) {
+      const newVec = extractVectorFromDocForUpdate(document, fieldPath);
+      updateExtractedVectors.set(fieldPath, newVec);
+      if (newVec) {
+        dimensionCheckVectors.set(fieldPath, newVec);
+      }
+    }
+    if (dimensionCheckVectors.size > 0) {
+      validateVectorDimensions(dimensionCheckVectors, updateVecIndexes);
+    }
+  }
+  const { partitionDoc } = prepareUpdatePartitionDoc(document, updateExtractedVectors);
+  await ctx.executor.execute({
+    type: "update",
+    indexName,
+    docId,
+    document: partitionDoc,
+    requestId: docId
+  });
+  try {
+    updateDocumentVectors(docId, updateExtractedVectors, updateVecIndexes);
+  } catch (err) {
+    if (rollbackDoc) {
+      try {
+        await ctx.executor.execute({
+          type: "update",
+          indexName,
+          docId,
+          document: rollbackDoc,
+          requestId: docId
+        });
+      } catch (rollbackErr) {
+        console.warn(
+          `Rollback failed for doc "${docId}" during update atomicity:`,
+          rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)
+        );
+      }
+    }
+    throw err;
+  }
+  try {
+    await ctx.pluginRegistry.runHook("afterUpdate", {
+      indexName,
+      docId,
+      oldDocument: oldDocument ?? {},
+      newDocument: document
+    });
+  } catch (err) {
+    console.warn("afterUpdate plugin hook error:", err instanceof Error ? err.message : String(err));
+  }
+  ctx.flushManager?.markDirty(indexName, 0);
+  await ctx.orchestrator.replicateToWorkers({
+    type: "update",
+    indexName,
+    docId,
+    document,
+    requestId: `replicate-update-${docId}`
+  });
+  for (const [fieldPath, vec] of updateExtractedVectors) {
+    if (vec === null) continue;
+    const vecIndex = updateVecIndexes.get(fieldPath);
+    if (vecIndex) {
+      vecIndex.scheduleBuild();
+    }
+  }
+}
+async function updateDocumentBatch(ctx, indexName, updates) {
+  ctx.guardShutdown();
+  const entry = ctx.requireIndex(indexName);
+  const succeeded = [];
+  const failed = [];
+  const updateBatchManager = ctx.requireManager(indexName);
+  const updateBatchVecIndexes = updateBatchManager.getVectorIndexes();
+  const touchedVectorFields = /* @__PURE__ */ new Set();
+  for (let chunkStart = 0; chunkStart < updates.length; chunkStart += BATCH_CHUNK_SIZE) {
+    const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, updates.length);
+    for (let i = chunkStart; i < chunkEnd; i++) {
+      try {
+        await updateDocument(ctx, indexName, updates[i].docId, updates[i].document);
+        succeeded.push(updates[i].docId);
+        if (updateBatchVecIndexes.size > 0) {
+          for (const fieldPath of entry.vectorFieldPaths) {
+            const vec = extractVectorFromDocForUpdate(updates[i].document, fieldPath);
+            if (vec !== null) {
+              touchedVectorFields.add(fieldPath);
+            }
+          }
+        }
+      } catch (err) {
+        failed.push({
+          docId: updates[i].docId,
+          error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_NOT_FOUND, String(err))
+        });
+      }
+    }
+    if (chunkEnd < updates.length) {
+      await new Promise((r) => setTimeout(r, 0));
+    }
+  }
+  for (const fieldPath of touchedVectorFields) {
+    const vecIndex = updateBatchVecIndexes.get(fieldPath);
+    if (vecIndex) {
+      vecIndex.scheduleBuild();
+    }
+  }
+  return { succeeded, failed };
+}
+function extractVectorFromDocForUpdate(document, fieldPath) {
+  return extractVectorFromDoc(document, fieldPath);
+}
+function prepareUpdatePartitionDoc(document, extractedVectors) {
+  if (extractedVectors.size === 0) {
+    return { partitionDoc: document };
+  }
+  const partitionDoc = structuredClone(document);
+  for (const fieldPath of extractedVectors.keys()) {
+    deleteNestedValue(partitionDoc, fieldPath);
+  }
+  return { partitionDoc };
+}
+
 // src/workers/worker-executor.ts
 var DEFAULT_BACKPRESSURE_LIMIT = 100;
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
@@ -544,8 +1404,89 @@ function highlightField(text, queryTokens, language, options) {
   return { snippet: result, positions: mergedPositions };
 }
 
+// src/search/fusion.ts
+function reciprocalRankFusion(lists, options) {
+  const k = options.k > 0 ? options.k : 60;
+  const scores = /* @__PURE__ */ new Map();
+  const docData = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const doc = list[rank];
+      const rrfContribution = 1 / (k + rank + 1);
+      scores.set(doc.docId, (scores.get(doc.docId) ?? 0) + rrfContribution);
+      if (!docData.has(doc.docId)) {
+        docData.set(doc.docId, doc);
+      }
+    }
+  }
+  const result = [];
+  for (const [docId, score] of scores) {
+    const original = docData.get(docId);
+    if (!original) continue;
+    result.push({
+      docId,
+      score,
+      termFrequencies: original.termFrequencies,
+      fieldLengths: original.fieldLengths,
+      idf: original.idf
+    });
+  }
+  result.sort((a, b) => b.score - a.score || a.docId.localeCompare(b.docId));
+  return result;
+}
+function linearCombination(textResults, vectorResults, options) {
+  const { alpha } = options;
+  const normalizedText = minMaxNormalize(textResults);
+  const normalizedVector = minMaxNormalize(vectorResults);
+  const textScoreMap = /* @__PURE__ */ new Map();
+  for (const doc of normalizedText) {
+    textScoreMap.set(doc.docId, doc.score);
+  }
+  const textDocMap = /* @__PURE__ */ new Map();
+  for (const doc of textResults) {
+    textDocMap.set(doc.docId, doc);
+  }
+  const vectorScoreMap = /* @__PURE__ */ new Map();
+  for (const doc of normalizedVector) {
+    vectorScoreMap.set(doc.docId, doc.score);
+  }
+  const allDocIds = /* @__PURE__ */ new Set();
+  for (const doc of textResults) allDocIds.add(doc.docId);
+  for (const doc of vectorResults) allDocIds.add(doc.docId);
+  const result = [];
+  for (const docId of allDocIds) {
+    const tScore = textScoreMap.get(docId) ?? 0;
+    const vScore = vectorScoreMap.get(docId) ?? 0;
+    const combined = alpha * vScore + (1 - alpha) * tScore;
+    const original = textDocMap.get(docId);
+    result.push({
+      docId,
+      score: combined,
+      termFrequencies: original?.termFrequencies ?? {},
+      fieldLengths: original?.fieldLengths ?? {},
+      idf: original?.idf ?? {}
+    });
+  }
+  result.sort((a, b) => b.score - a.score || a.docId.localeCompare(b.docId));
+  return result;
+}
+function minMaxNormalize(docs) {
+  if (docs.length === 0) return [];
+  let min = docs[0].score;
+  let max = docs[0].score;
+  for (let i = 1; i < docs.length; i++) {
+    if (docs[i].score < min) min = docs[i].score;
+    if (docs[i].score > max) max = docs[i].score;
+  }
+  const range = max - min;
+  if (range === 0) {
+    return docs.map((d) => ({ docId: d.docId, score: 1 }));
+  }
+  return docs.map((d) => ({ docId: d.docId, score: (d.score - min) / range }));
+}
+
 // src/search/grouping.ts
-function getNestedValue(obj, path) {
+function getNestedValue2(obj, path) {
   const segments = path.split(".");
   let current = obj;
   for (const segment of segments) {
@@ -569,7 +1510,7 @@ function applyGrouping(hits, group, getDocument) {
     const fieldValues = [];
     const valuesRecord = {};
     for (const field of group.fields) {
-      const value = doc ? getNestedValue(doc, field) : void 0;
+      const value = doc ? getNestedValue2(doc, field) : void 0;
       fieldValues.push(value);
       valuesRecord[field] = value;
     }
@@ -735,7 +1676,7 @@ function applyPinning(hits, pinned, resolveDoc) {
 }
 
 // src/search/sorting.ts
-function getNestedValue2(obj, path) {
+function getNestedValue3(obj, path) {
   const segments = path.split(".");
   let current = obj;
   for (const segment of segments) {
@@ -763,7 +1704,7 @@ function applySorting(hits, sort, getDocument) {
       );
       continue;
     }
-    const values = sortFields.map(([field]) => getNestedValue2(doc, field));
+    const values = sortFields.map(([field]) => getNestedValue3(doc, field));
     valueCache.set(hit.id, values);
   }
   const sorted = hits.slice();
@@ -801,98 +1742,172 @@ function applySorting(hits, sort, getDocument) {
   return sorted;
 }
 
-// src/engine/validation.ts
-var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-var MAX_INDEX_NAME_LENGTH = 256;
-var MAX_DOC_ID_LENGTH = 512;
-var BATCH_CHUNK_SIZE = 1e3;
-var MAX_LIMIT = 1e4;
-var MAX_OFFSET = 1e5;
-var DEFAULT_LIMIT = 10;
-var DEFAULT_OFFSET = 0;
-function now() {
-  if (typeof performance !== "undefined" && typeof performance.now === "function") {
-    return performance.now();
-  }
-  return Date.now();
-}
-function validateIndexName(name) {
-  if (!name || name.length === 0) {
-    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "Index name must not be empty", { indexName: name });
-  }
-  if (name.length > MAX_INDEX_NAME_LENGTH) {
-    throw new NarsilError(
-      ErrorCodes.INDEX_NOT_FOUND,
-      `Index name must not exceed ${MAX_INDEX_NAME_LENGTH} characters`,
-      {
-        indexName: name,
-        length: name.length
-      }
-    );
-  }
-  if (!INDEX_NAME_PATTERN.test(name)) {
-    throw new NarsilError(
-      ErrorCodes.INDEX_NOT_FOUND,
-      `Index name "${name}" contains invalid characters; use alphanumeric, dots, hyphens, and underscores only`,
-      { indexName: name }
-    );
-  }
-  if (name.includes("..")) {
-    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index name "${name}" must not contain ".."`, { indexName: name });
-  }
-}
-function validateDocId(docId) {
-  if (!docId || docId.length === 0) {
-    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not be empty", { docId });
-  }
-  if (docId.length > MAX_DOC_ID_LENGTH) {
-    throw new NarsilError(
-      ErrorCodes.DOC_VALIDATION_FAILED,
-      `Document ID must not exceed ${MAX_DOC_ID_LENGTH} characters`,
-      {
-        docId,
-        length: docId.length
-      }
-    );
-  }
-  if (docId.includes("\0")) {
-    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not contain null bytes", { docId });
-  }
-}
-function clampLimit(limit) {
-  if (limit === void 0) return DEFAULT_LIMIT;
-  return Math.max(0, Math.min(limit, MAX_LIMIT));
-}
-function clampOffset(offset) {
-  if (offset === void 0) return DEFAULT_OFFSET;
-  return Math.max(0, Math.min(offset, MAX_OFFSET));
-}
-
 // src/engine/query.ts
-async function executeQuery(params, context) {
-  const { manager, language, config, workerSearch, indexName } = context;
-  const startTime = now();
-  const limit = clampLimit(params.limit);
-  const offset = clampOffset(params.offset);
-  let fanOutResult;
-  const workerResult = workerSearch ? await workerSearch(indexName, params) : null;
-  if (workerResult) {
-    fanOutResult = workerResult;
+function collectFilterDocIds(manager, params, schema) {
+  const filterDocIds = /* @__PURE__ */ new Set();
+  if (!params.filters) return filterDocIds;
+  for (const partition of manager.getAllPartitions()) {
+    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 resolveVectorIndex(manager, fieldName) {
+  return manager.getVectorIndexes().get(fieldName);
+}
+function executeVectorSearch(params, manager, config, limit, offset) {
+  const vectorConfig = params.vector;
+  if (!vectorConfig || !vectorConfig.value) {
+    return { scored: [], totalMatched: 0 };
+  }
+  const vecIndex = resolveVectorIndex(manager, vectorConfig.field);
+  if (!vecIndex) {
+    return { scored: [], totalMatched: 0 };
+  }
+  let filterDocIds;
+  if (params.filters) {
+    filterDocIds = collectFilterDocIds(manager, params, config.schema);
+    if (filterDocIds.size === 0) {
+      return { scored: [], totalMatched: 0 };
+    }
+  }
+  const queryVec = new Float32Array(vectorConfig.value);
+  const k = limit + offset + 1;
+  const results = vecIndex.search(queryVec, k, {
+    metric: vectorConfig.metric ?? "cosine",
+    minSimilarity: vectorConfig.similarity ?? 0,
+    filterDocIds,
+    efSearch: vectorConfig.efSearch
+  });
+  const scored = vectorResultsToScored(results);
+  return { scored, totalMatched: scored.length };
+}
+async function executeHybridSearch(params, manager, language, config, workerSearch, indexName, limit, offset) {
+  const { vector: _vector, mode: _mode, hybrid: _hybrid, ...textOnlyParams } = params;
+  let filterDocIds;
+  if (params.filters) {
+    filterDocIds = collectFilterDocIds(manager, params, config.schema);
+    if (filterDocIds.size === 0) {
+      return { scored: [], totalMatched: 0 };
+    }
+  }
+  let textFanOutResult;
+  const textWorkerResult = workerSearch ? await workerSearch(indexName, textOnlyParams) : null;
+  if (textWorkerResult) {
+    textFanOutResult = textWorkerResult;
   } else {
     const searchOptions = {
       bm25Params: config.bm25,
       stopWords: config.stopWords,
       customTokenizer: config.tokenizer
     };
-    fanOutResult = await fanOutQuery(
+    textFanOutResult = await fanOutQuery(
       manager,
-      params,
+      textOnlyParams,
       language,
       config.schema,
       { scoringMode: params.scoring ?? config.defaultScoring ?? "local" },
       searchOptions
     );
   }
+  const vectorConfig = params.vector;
+  if (!vectorConfig || !vectorConfig.value) {
+    return {
+      scored: textFanOutResult.scored,
+      totalMatched: textFanOutResult.totalMatched,
+      facets: textFanOutResult.facets
+    };
+  }
+  let vectorScored = [];
+  const vecIndex = resolveVectorIndex(manager, vectorConfig.field);
+  if (vecIndex) {
+    const queryVec = new Float32Array(vectorConfig.value);
+    const vectorK = limit + offset + 1;
+    const vectorResults = vecIndex.search(queryVec, vectorK, {
+      metric: vectorConfig.metric ?? "cosine",
+      minSimilarity: vectorConfig.similarity ?? 0,
+      filterDocIds,
+      efSearch: vectorConfig.efSearch
+    });
+    vectorScored = vectorResultsToScored(vectorResults);
+  }
+  const hybridConfig = params.hybrid ?? {};
+  const strategy = hybridConfig.strategy ?? "rrf";
+  let fusedScored;
+  if (strategy === "rrf") {
+    const rrfK = hybridConfig.k !== void 0 && hybridConfig.k > 0 ? hybridConfig.k : 60;
+    fusedScored = reciprocalRankFusion([textFanOutResult.scored, vectorScored], { k: rrfK });
+  } else {
+    const alpha = clampAlpha(hybridConfig.alpha);
+    fusedScored = linearCombination(textFanOutResult.scored, vectorScored, { alpha });
+  }
+  if (params.minScore !== void 0 && params.minScore > 0) {
+    const threshold = params.minScore;
+    fusedScored = fusedScored.filter((doc) => doc.score >= threshold);
+  }
+  if (filterDocIds) {
+    fusedScored = fusedScored.filter((doc) => filterDocIds.has(doc.docId));
+  }
+  return {
+    scored: fusedScored,
+    totalMatched: fusedScored.length,
+    facets: textFanOutResult.facets
+  };
+}
+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;
+}
+async function executeQuery(params, context) {
+  const { manager, language, config, workerSearch, indexName } = context;
+  const startTime = now();
+  const limit = clampLimit(params.limit);
+  const offset = clampOffset(params.offset);
+  const hasTerm = params.term !== void 0 && params.term.trim().length > 0;
+  const hasVector = params.vector !== void 0 && params.vector.value !== void 0;
+  const isHybridMode = params.mode === "hybrid" || hasTerm && hasVector;
+  const isVectorOnly = (params.mode === "vector" || hasVector && !hasTerm) && !isHybridMode;
+  const requestedVectorField = params.vector?.field;
+  const hasGlobalVectorIndex = requestedVectorField !== void 0 && manager.getVectorIndexes().has(requestedVectorField);
+  let fanOutResult;
+  if (isVectorOnly && hasGlobalVectorIndex) {
+    fanOutResult = executeVectorSearch(params, manager, config, limit, offset);
+  } else if (isHybridMode && hasGlobalVectorIndex) {
+    fanOutResult = await executeHybridSearch(params, manager, language, config, workerSearch, indexName, limit, offset);
+  } else {
+    const workerResult = workerSearch ? await workerSearch(indexName, params) : null;
+    if (workerResult) {
+      fanOutResult = workerResult;
+    } else {
+      const searchOptions = {
+        bm25Params: config.bm25,
+        stopWords: config.stopWords,
+        customTokenizer: config.tokenizer
+      };
+      fanOutResult = await fanOutQuery(
+        manager,
+        params,
+        language,
+        config.schema,
+        { scoringMode: params.scoring ?? config.defaultScoring ?? "local" },
+        searchOptions
+      );
+    }
+  }
   const needsFullHits = params.sort !== void 0 || params.group !== void 0 || params.pinned !== void 0 || params.searchAfter !== void 0;
   let hits;
   if (needsFullHits) {
@@ -915,94 +1930,546 @@ async function executeQuery(params, context) {
       };
     }
   }
-  if (params.sort) {
-    hits = applySorting(hits, params.sort, (docId) => manager.getRef(docId));
+  if (params.sort) {
+    hits = applySorting(hits, params.sort, (docId) => manager.getRef(docId));
+  }
+  let groups;
+  if (params.group) {
+    groups = applyGrouping(hits, params.group, (docId) => manager.getRef(docId));
+  }
+  if (params.pinned) {
+    hits = applyPinning(hits, params.pinned, (docId) => {
+      const doc = manager.getRef(docId);
+      if (!doc) return void 0;
+      return { id: docId, score: 0, document: doc };
+    });
+  }
+  const { paginated, nextCursor } = applyPagination(hits, limit, offset, params.searchAfter);
+  for (const hit of paginated) {
+    hit.document = manager.get(hit.id) ?? {};
+  }
+  if (groups) {
+    for (const group of groups) {
+      for (const hit of group.hits) {
+        hit.document = manager.get(hit.id) ?? {};
+      }
+    }
+  }
+  if (params.highlight) {
+    applyHighlights(paginated, params, language, config);
+  }
+  const elapsed = now() - startTime;
+  return {
+    hits: paginated,
+    count: fanOutResult.totalMatched,
+    elapsed,
+    cursor: nextCursor,
+    facets: fanOutResult.facets,
+    groups
+  };
+}
+async function executePreflight(params, context) {
+  const { manager, language, config, workerSearch, indexName } = context;
+  const startTime = now();
+  const hasTerm = params.term !== void 0 && params.term.trim().length > 0;
+  const hasVector = params.vector !== void 0 && params.vector.value !== void 0;
+  const isHybridMode = params.mode === "hybrid" || hasTerm && hasVector;
+  const isVectorOnly = (params.mode === "vector" || hasVector && !hasTerm) && !isHybridMode;
+  const requestedVectorField = params.vector?.field;
+  const hasGlobalVectorIndex = requestedVectorField !== void 0 && manager.getVectorIndexes().has(requestedVectorField);
+  let totalMatched;
+  const preflightLimit = 1e3;
+  const preflightOffset = 0;
+  if (isVectorOnly && hasGlobalVectorIndex) {
+    const result = executeVectorSearch(params, manager, config, preflightLimit, preflightOffset);
+    totalMatched = result.totalMatched;
+  } else if (isHybridMode && hasGlobalVectorIndex) {
+    const result = await executeHybridSearch(
+      params,
+      manager,
+      language,
+      config,
+      workerSearch,
+      indexName,
+      preflightLimit,
+      preflightOffset
+    );
+    totalMatched = result.totalMatched;
+  } else {
+    const workerResult = workerSearch ? await workerSearch(indexName, params) : null;
+    if (workerResult) {
+      totalMatched = workerResult.totalMatched;
+    } else {
+      const searchOptions = {
+        bm25Params: config.bm25,
+        stopWords: config.stopWords,
+        customTokenizer: config.tokenizer
+      };
+      const fanOutResult = await fanOutQuery(
+        manager,
+        params,
+        language,
+        config.schema,
+        { scoringMode: params.scoring ?? config.defaultScoring ?? "local" },
+        searchOptions
+      );
+      totalMatched = fanOutResult.totalMatched;
+    }
+  }
+  const elapsed = now() - startTime;
+  return { count: totalMatched, elapsed };
+}
+function applyHighlights(hits, params, language, config) {
+  if (!params.highlight) return;
+  const queryTokenResult = tokenize(params.term ?? "", language, {
+    stem: true,
+    removeStopWords: true,
+    customTokenizer: config.tokenizer,
+    stopWordOverride: config.stopWords
+  });
+  for (const hit of hits) {
+    const highlights = {};
+    for (const field of params.highlight.fields) {
+      const doc = hit.document;
+      const fieldValue = doc[field];
+      if (typeof fieldValue === "string") {
+        highlights[field] = highlightField(fieldValue, queryTokenResult.tokens, language, {
+          preTag: params.highlight.preTag,
+          postTag: params.highlight.postTag,
+          maxSnippetLength: params.highlight.maxSnippetLength
+        });
+      }
+    }
+    hit.highlights = highlights;
+  }
+}
+
+// src/partitioning/write-ahead-queue.ts
+function createWriteAheadQueue(maxSize = 1e4) {
+  const entries = [];
+  let nextSequence = 1;
+  return {
+    push(entry) {
+      if (entries.length >= maxSize) {
+        throw new NarsilError(
+          ErrorCodes.PARTITION_REBALANCING_BACKPRESSURE,
+          `Write-ahead queue is full (${maxSize} entries). Retry after rebalancing completes.`,
+          { maxSize, currentSize: entries.length }
+        );
+      }
+      const seq = nextSequence++;
+      entries.push({ ...entry, sequenceNumber: seq });
+      return seq;
+    },
+    drain() {
+      const result = entries.splice(0);
+      result.sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+      return result;
+    },
+    clear() {
+      entries.length = 0;
+    },
+    get size() {
+      return entries.length;
+    },
+    get isFull() {
+      return entries.length >= maxSize;
+    }
+  };
+}
+
+// src/engine/rebalance-executor.ts
+async function executeRebalance(manager, indexName, targetPartitionCount, ctx) {
+  if (targetPartitionCount <= 0 || !Number.isInteger(targetPartitionCount)) {
+    throw new NarsilError(
+      ErrorCodes.PARTITION_CAPACITY_EXCEEDED,
+      `Target partition count must be a positive integer, got ${targetPartitionCount}`,
+      { targetPartitionCount }
+    );
+  }
+  if (ctx.rebalancingIndexes.has(indexName)) {
+    throw new NarsilError(
+      ErrorCodes.PARTITION_REBALANCING_BACKPRESSURE,
+      `Index "${indexName}" is already being rebalanced`
+    );
+  }
+  if (targetPartitionCount === manager.partitionCount) {
+    return;
+  }
+  const waq = createWriteAheadQueue();
+  ctx.waqMap.set(indexName, waq);
+  ctx.rebalancingIndexes.add(indexName);
+  try {
+    const oldCount = manager.partitionCount;
+    await ctx.rebalancer.rebalance(manager, targetPartitionCount, ctx.router, (progress) => {
+      if (progress.phase === "complete") {
+        const handlers = ctx.eventHandlers.get("partitionRebalance");
+        if (handlers) {
+          for (const handler of handlers) {
+            handler({ indexName, oldCount, newCount: targetPartitionCount });
+          }
+        }
+      }
+    });
+    const entries = waq.drain();
+    const appliedSeqs = ctx.lastAppliedSeqMap.get(indexName) ?? /* @__PURE__ */ new Map();
+    const rebalanceEntry = ctx.requireIndex(indexName);
+    const rebalanceVecIndexes = manager.getVectorIndexes();
+    const rebalanceVectorFieldPaths = rebalanceVecIndexes.size > 0 ? rebalanceEntry.vectorFieldPaths : /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      const partitionLastSeq = appliedSeqs.get(0) ?? 0;
+      if (entry.sequenceNumber <= partitionLastSeq) continue;
+      try {
+        if (entry.action === "insert" && entry.document) {
+          const { partitionDoc, extractedVectors } = prepareDocumentVectors(
+            entry.document,
+            rebalanceVectorFieldPaths,
+            rebalanceVecIndexes
+          );
+          manager.insert(entry.docId, partitionDoc);
+          if (extractedVectors.size > 0) {
+            insertDocumentVectors(entry.docId, extractedVectors, rebalanceVecIndexes);
+          }
+        } else if (entry.action === "remove") {
+          manager.remove(entry.docId);
+          removeDocumentVectors(entry.docId, rebalanceVecIndexes);
+        } else if (entry.action === "update" && entry.document) {
+          const replayUpdateVectors = /* @__PURE__ */ new Map();
+          for (const fieldPath of rebalanceVectorFieldPaths) {
+            const newVec = extractVectorFromDoc(entry.document, fieldPath);
+            replayUpdateVectors.set(fieldPath, newVec);
+          }
+          const replayUpdateDoc = replayUpdateVectors.size > 0 ? structuredClone(entry.document) : entry.document;
+          if (replayUpdateVectors.size > 0) {
+            for (const fieldPath of replayUpdateVectors.keys()) {
+              deleteNestedValue(replayUpdateDoc, fieldPath);
+            }
+          }
+          manager.update(entry.docId, replayUpdateDoc);
+          for (const [fieldPath, newVec] of replayUpdateVectors) {
+            const vecIndex = rebalanceVecIndexes.get(fieldPath);
+            if (!vecIndex) continue;
+            if (newVec === null) {
+              if (vecIndex.has(entry.docId)) {
+                vecIndex.remove(entry.docId);
+              }
+            } else {
+              const oldVec = vecIndex.getVector(entry.docId);
+              if (!vectorsEqual(oldVec, newVec)) {
+                vecIndex.remove(entry.docId);
+                vecIndex.insert(entry.docId, newVec);
+              }
+            }
+          }
+        }
+      } catch (replayErr) {
+        const isDuplicate = replayErr instanceof NarsilError && replayErr.code === ErrorCodes.DOC_ALREADY_EXISTS;
+        const isMissing = replayErr instanceof NarsilError && replayErr.code === ErrorCodes.DOC_NOT_FOUND;
+        if (!isDuplicate && !isMissing) {
+          console.warn(`WAQ replay failed for ${entry.action} on doc "${entry.docId}":`, replayErr);
+        }
+      }
+      appliedSeqs.set(0, entry.sequenceNumber);
+    }
+    ctx.lastAppliedSeqMap.set(indexName, appliedSeqs);
+  } finally {
+    ctx.rebalancingIndexes.delete(indexName);
+    ctx.waqMap.delete(indexName);
+  }
+}
+
+// src/engine/resolve-vector-text.ts
+async function resolveVectorText(params, embeddingAdapter, signal) {
+  if (!params.vector) return params;
+  if (params.vector.text === void 0 && params.vector.value === void 0) return params;
+  if (params.vector.value !== void 0 && params.vector.text === void 0) return params;
+  if (params.vector.text !== void 0 && params.vector.value !== void 0) {
+    throw new NarsilError(ErrorCodes.EMBEDDING_CONFIG_INVALID, "Vector query cannot have both 'text' and 'value'");
+  }
+  if (!embeddingAdapter) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      "Vector query with 'text' requires an embedding adapter on the index or instance"
+    );
+  }
+  if (typeof params.vector.text !== "string") {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Vector query 'text' must be a string, got ${typeof params.vector.text}`
+    );
+  }
+  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);
+  if (!(raw instanceof Float32Array)) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_FAILED,
+      `Adapter returned ${typeof raw} for query embedding, expected Float32Array`
+    );
+  }
+  if (raw.length !== embeddingAdapter.dimensions) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_DIMENSION_MISMATCH,
+      `Adapter returned ${raw.length}-dimensional vector for query, expected ${embeddingAdapter.dimensions}`,
+      { expected: embeddingAdapter.dimensions, actual: raw.length }
+    );
+  }
+  const resolved = { ...params.vector, value: Array.from(raw) };
+  delete resolved.text;
+  return { ...params, vector: resolved };
+}
+var VALID_HNSW_METRICS = /* @__PURE__ */ new Set(["cosine", "dotProduct", "euclidean"]);
+function validateHnswMetric(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string" && VALID_HNSW_METRICS.has(value)) {
+    return value;
+  }
+  return void 0;
+}
+function wireToPartition(raw) {
+  const documents = {};
+  for (const [docId, doc] of Object.entries(raw.documents ?? {})) {
+    documents[docId] = {
+      fields: doc.fields,
+      fieldLengths: doc.field_lengths ?? {}
+    };
+  }
+  const invertedIndex = {};
+  for (const [token, list] of Object.entries(raw.inverted_index ?? {})) {
+    invertedIndex[token] = {
+      docFrequency: list.doc_freq,
+      postings: (list.postings ?? []).map((p) => ({
+        docId: p.doc_id,
+        termFrequency: p.term_freq,
+        field: p.field,
+        positions: p.positions ?? []
+      }))
+    };
+  }
+  const numeric = {};
+  for (const [field, entries] of Object.entries(raw.field_indexes?.numeric ?? {})) {
+    numeric[field] = entries.map((e) => ({ value: e.value, docId: e.doc_id }));
+  }
+  const boolean = {};
+  for (const [field, idx] of Object.entries(raw.field_indexes?.boolean ?? {})) {
+    boolean[field] = { trueDocs: idx.true_docs ?? [], falseDocs: idx.false_docs ?? [] };
+  }
+  const geopoint = {};
+  for (const [field, entries] of Object.entries(raw.field_indexes?.geopoint ?? {})) {
+    geopoint[field] = entries.map((e) => ({ lat: e.lat, lon: e.lon, docId: e.doc_id }));
+  }
+  const vectorData = {};
+  for (const [field, data] of Object.entries(raw.vector_data ?? {})) {
+    vectorData[field] = {
+      dimension: data.dimension,
+      vectors: (data.vectors ?? []).map((v) => ({ docId: v.doc_id, vector: v.vector })),
+      hnswGraph: data.hnsw_graph ? {
+        entryPoint: data.hnsw_graph.entry_point,
+        maxLayer: data.hnsw_graph.max_layer,
+        m: data.hnsw_graph.m,
+        efConstruction: data.hnsw_graph.ef_construction,
+        metric: validateHnswMetric(data.hnsw_graph.metric),
+        nodes: data.hnsw_graph.nodes
+      } : null,
+      sq8: data.sq8 ? {
+        alpha: data.sq8.alpha,
+        offset: data.sq8.offset,
+        quantizedVectors: data.sq8.quantized_vectors,
+        vectorSums: data.sq8.vector_sums,
+        vectorSumSqs: data.sq8.vector_sum_sqs
+      } : null
+    };
+  }
+  return {
+    indexName: raw.index_name,
+    partitionId: raw.partition_id,
+    totalPartitions: raw.total_partitions,
+    language: raw.language ?? "english",
+    schema: raw.schema ?? {},
+    docCount: raw.doc_count ?? 0,
+    avgDocLength: raw.avg_doc_length ?? 0,
+    documents,
+    invertedIndex,
+    fieldIndexes: {
+      numeric,
+      boolean,
+      enum: raw.field_indexes?.enum ?? {},
+      geopoint
+    },
+    vectorData,
+    statistics: {
+      totalDocuments: raw.statistics?.total_documents ?? 0,
+      totalFieldLengths: raw.statistics?.total_field_lengths ?? {},
+      averageFieldLengths: raw.statistics?.average_field_lengths ?? {},
+      docFrequencies: raw.statistics?.doc_frequencies ?? {}
+    }
+  };
+}
+function deserializePayloadV1(data) {
+  const raw = decode(data);
+  return wireToPartition(raw);
+}
+
+// src/engine/snapshot.ts
+async function createSnapshot(manager, entry) {
+  const partitionBuffers = [];
+  for (let i = 0; i < manager.partitionCount; i++) {
+    partitionBuffers.push(manager.serializePartitionToBytes(i));
+  }
+  const snapshotVecIndexes = manager.getVectorIndexes();
+  const vectorPayloads = {};
+  for (const [fieldPath, vecIndex] of snapshotVecIndexes) {
+    vectorPayloads[fieldPath] = vecIndex.serialize();
+  }
+  const { encode: encode2 } = await import('@msgpack/msgpack');
+  return encode2({
+    version: 2,
+    schema: entry.config.schema,
+    language: entry.language.name,
+    partitions: partitionBuffers,
+    vectorIndexes: vectorPayloads
+  });
+}
+async function restoreFromSnapshot(indexName, data, executor, indexRegistry, getVectorFieldPaths2, dropIndex, requireManager) {
+  if (!(data instanceof Uint8Array)) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Snapshot data must be a Uint8Array");
+  }
+  const { decode: decode2 } = await import('@msgpack/msgpack');
+  const envelope = decode2(data);
+  if (envelope.version !== 1 && envelope.version !== 2) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Unsupported snapshot version: ${envelope.version}. Expected version 1 or 2`,
+      { version: envelope.version }
+    );
   }
-  let groups;
-  if (params.group) {
-    groups = applyGrouping(hits, params.group, (docId) => manager.getRef(docId));
+  if (!envelope.schema || typeof envelope.schema !== "object") {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Invalid snapshot: missing or invalid schema");
   }
-  if (params.pinned) {
-    hits = applyPinning(hits, params.pinned, (docId) => {
-      const doc = manager.getRef(docId);
-      if (!doc) return void 0;
-      return { id: docId, score: 0, document: doc };
-    });
+  if (!envelope.language || typeof envelope.language !== "string") {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Invalid snapshot: missing or invalid language");
   }
-  const { paginated, nextCursor } = applyPagination(hits, limit, offset, params.searchAfter);
-  for (const hit of paginated) {
-    hit.document = manager.get(hit.id) ?? {};
+  if (!Array.isArray(envelope.partitions)) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Invalid snapshot: missing partitions");
   }
-  if (groups) {
-    for (const group of groups) {
-      for (const hit of group.hits) {
-        hit.document = manager.get(hit.id) ?? {};
+  const language = getLanguage(envelope.language);
+  const schema = envelope.schema;
+  validateSchema(schema);
+  if (indexRegistry.has(indexName)) {
+    await dropIndex(indexName);
+  }
+  const indexConfig = { schema, language: envelope.language };
+  executor.createIndex(indexName, indexConfig, language);
+  const vectorFieldPaths = getVectorFieldPaths2(schema);
+  indexRegistry.set(indexName, { config: indexConfig, language, embeddingAdapter: null, vectorFieldPaths });
+  try {
+    const manager = requireManager(indexName);
+    while (manager.partitionCount < envelope.partitions.length) {
+      manager.addPartition();
+    }
+    const deserializePartitionPayload = envelope.version === 2 ? deserializePayloadV2 : deserializePayloadV1;
+    for (let i = 0; i < envelope.partitions.length; i++) {
+      const partition = deserializePartitionPayload(envelope.partitions[i]);
+      manager.deserializePartition(i, partition);
+    }
+    if (envelope.vectorIndexes) {
+      const restoreVecIndexes = manager.getVectorIndexes();
+      for (const [fieldPath, payload] of Object.entries(envelope.vectorIndexes)) {
+        const vecIndex = restoreVecIndexes.get(fieldPath);
+        if (vecIndex) {
+          vecIndex.deserialize(payload);
+        }
       }
     }
+  } catch (err) {
+    try {
+      executor.dropIndex(indexName);
+      indexRegistry.delete(indexName);
+    } catch (_) {
+    }
+    throw err;
   }
-  if (params.highlight) {
-    applyHighlights(paginated, params, language, config);
+}
+
+// src/engine/suggest.ts
+function executeSuggest(manager, language, params) {
+  const t0 = performance.now();
+  const limit = Math.max(1, Math.min(params.limit ?? 10, 100));
+  const rawPrefix = params.prefix.trim();
+  if (rawPrefix.length === 0) {
+    return { terms: [], elapsed: performance.now() - t0 };
+  }
+  const unstemmed = tokenize(rawPrefix, language, { stem: false, removeStopWords: false });
+  const lastToken = unstemmed.tokens.length > 0 ? unstemmed.tokens[unstemmed.tokens.length - 1].token : rawPrefix.toLowerCase();
+  if (lastToken.length === 0) {
+    return { terms: [], elapsed: performance.now() - t0 };
+  }
+  const stemmed = language.stemmer ? language.stemmer(lastToken) : lastToken;
+  const prefixes = stemmed !== lastToken ? [lastToken, stemmed] : [lastToken];
+  const partitions = manager.getAllPartitions();
+  const merged = /* @__PURE__ */ new Map();
+  const perPartitionLimit = limit * 2;
+  for (const partition of partitions) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const prefix of prefixes) {
+      const suggestions = partition.suggestTerms(prefix, perPartitionLimit);
+      for (const s of suggestions) {
+        if (seen.has(s.term)) continue;
+        seen.add(s.term);
+        merged.set(s.term, (merged.get(s.term) ?? 0) + s.documentFrequency);
+      }
+    }
+  }
+  const terms = Array.from(merged.entries()).map(([term, documentFrequency]) => ({ term, documentFrequency })).sort((a, b) => b.documentFrequency - a.documentFrequency);
+  if (terms.length > limit) terms.length = limit;
+  return { terms, elapsed: performance.now() - t0 };
+}
+
+// src/engine/vector-maintenance.ts
+function resolveVectorIndexes(manager, indexName, fieldName) {
+  const all = manager.getVectorIndexes();
+  if (fieldName === void 0) return all;
+  const idx = all.get(fieldName);
+  if (!idx) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Vector field "${fieldName}" not found in index "${indexName}"`, {
+      indexName,
+      fieldName
+    });
   }
-  const elapsed = now() - startTime;
-  return {
-    hits: paginated,
-    count: fanOutResult.totalMatched,
-    elapsed,
-    cursor: nextCursor,
-    facets: fanOutResult.facets,
-    groups
-  };
+  const single = /* @__PURE__ */ new Map();
+  single.set(fieldName, idx);
+  return single;
 }
-async function executePreflight(params, context) {
-  const { manager, language, config, workerSearch, indexName } = context;
-  const startTime = now();
-  let totalMatched;
-  const workerResult = workerSearch ? await workerSearch(indexName, params) : null;
-  if (workerResult) {
-    totalMatched = workerResult.totalMatched;
-  } else {
-    const searchOptions = {
-      bm25Params: config.bm25,
-      stopWords: config.stopWords,
-      customTokenizer: config.tokenizer
-    };
-    const fanOutResult = await fanOutQuery(
-      manager,
-      params,
-      language,
-      config.schema,
-      { scoringMode: params.scoring ?? config.defaultScoring ?? "local" },
-      searchOptions
-    );
-    totalMatched = fanOutResult.totalMatched;
+function compactVectors(manager, indexName, fieldName) {
+  const indexes = resolveVectorIndexes(manager, indexName, fieldName);
+  for (const [, idx] of indexes) {
+    idx.compact();
   }
-  const elapsed = now() - startTime;
-  return { count: totalMatched, elapsed };
 }
-function applyHighlights(hits, params, language, config) {
-  if (!params.highlight) return;
-  const queryTokenResult = tokenize(params.term ?? "", language, {
-    stem: true,
-    removeStopWords: true,
-    customTokenizer: config.tokenizer,
-    stopWordOverride: config.stopWords
-  });
-  for (const hit of hits) {
-    const highlights = {};
-    for (const field of params.highlight.fields) {
-      const doc = hit.document;
-      const fieldValue = doc[field];
-      if (typeof fieldValue === "string") {
-        highlights[field] = highlightField(fieldValue, queryTokenResult.tokens, language, {
-          preTag: params.highlight.preTag,
-          postTag: params.highlight.postTag,
-          maxSnippetLength: params.highlight.maxSnippetLength
-        });
-      }
-    }
-    hit.highlights = highlights;
+async function optimizeVectors(manager, indexName, fieldName) {
+  const indexes = resolveVectorIndexes(manager, indexName, fieldName);
+  for (const [, idx] of indexes) {
+    await idx.optimize();
   }
 }
+function getVectorMaintenanceStatus(manager) {
+  const indexes = manager.getVectorIndexes();
+  const results = [];
+  for (const [field, idx] of indexes) {
+    const status = idx.maintenanceStatus();
+    results.push({
+      fieldName: field,
+      tombstoneRatio: status.tombstoneRatio,
+      graphCount: status.graphCount,
+      bufferSize: status.bufferSize,
+      building: status.building,
+      estimatedCompactMs: status.estimatedCompactMs,
+      estimatedOptimizeMs: status.estimatedOptimizeMs
+    });
+  }
+  return results;
+}
 
 // src/partitioning/rebalancer.ts
 var CHUNK_SIZE = 1e3;
@@ -1094,40 +2561,6 @@ function createRebalancer() {
   };
 }
 
-// src/partitioning/write-ahead-queue.ts
-function createWriteAheadQueue(maxSize = 1e4) {
-  const entries = [];
-  let nextSequence = 1;
-  return {
-    push(entry) {
-      if (entries.length >= maxSize) {
-        throw new NarsilError(
-          ErrorCodes.PARTITION_REBALANCING_BACKPRESSURE,
-          `Write-ahead queue is full (${maxSize} entries). Retry after rebalancing completes.`,
-          { maxSize, currentSize: entries.length }
-        );
-      }
-      const seq = nextSequence++;
-      entries.push({ ...entry, sequenceNumber: seq });
-      return seq;
-    },
-    drain() {
-      const result = entries.splice(0);
-      result.sort((a, b) => a.sequenceNumber - b.sequenceNumber);
-      return result;
-    },
-    clear() {
-      entries.length = 0;
-    },
-    get size() {
-      return entries.length;
-    },
-    get isFull() {
-      return entries.length >= maxSize;
-    }
-  };
-}
-
 // src/persistence/flush-manager.ts
 var DEFAULT_INTERVAL = 5e3;
 var DEFAULT_MUTATION_THRESHOLD = 1e3;
@@ -1234,141 +2667,148 @@ function createFlushManager(config, getPartitionData, getInstanceId) {
     }
     startTimer();
   }
-  async function shutdown() {
-    isShuttingDown = true;
-    if (flushTimerId !== null) {
-      clearInterval(flushTimerId);
-      flushTimerId = null;
-    }
-    await flush();
-  }
-  return {
-    markDirty,
-    flush,
-    shutdown
-  };
-}
-
-// src/plugins/registry.ts
-function isThenable(value) {
-  return value !== null && typeof value === "object" && typeof value.then === "function";
-}
-async function continueAsync(pending, hooks, startIndex, context) {
-  await pending;
-  for (let i = startIndex; i < hooks.length; i++) {
-    await hooks[i](context);
-  }
-}
-function createPluginRegistry() {
-  const plugins = [];
-  return {
-    register(plugin) {
-      plugins.push(plugin);
-    },
-    hasHooks(hookName) {
-      return plugins.some((p) => typeof p[hookName] === "function");
-    },
-    runHook(hookName, context) {
-      const hooks = [];
-      for (const plugin of plugins) {
-        const hook = plugin[hookName];
-        if (typeof hook === "function") {
-          hooks.push(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);
-        }
-      }
-    }
-  };
-}
-var VALID_HNSW_METRICS = /* @__PURE__ */ new Set(["cosine", "dotProduct", "euclidean"]);
-function validateHnswMetric(value) {
-  if (value === void 0 || value === null) return void 0;
-  if (typeof value === "string" && VALID_HNSW_METRICS.has(value)) {
-    return value;
-  }
-  return void 0;
-}
-function wireToPartition(raw) {
-  const documents = {};
-  for (const [docId, doc] of Object.entries(raw.documents ?? {})) {
-    documents[docId] = {
-      fields: doc.fields,
-      fieldLengths: doc.field_lengths ?? {}
-    };
-  }
-  const invertedIndex = {};
-  for (const [token, list] of Object.entries(raw.inverted_index ?? {})) {
-    invertedIndex[token] = {
-      docFrequency: list.doc_freq,
-      postings: (list.postings ?? []).map((p) => ({
-        docId: p.doc_id,
-        termFrequency: p.term_freq,
-        field: p.field,
-        positions: p.positions ?? []
-      }))
-    };
-  }
-  const numeric = {};
-  for (const [field, entries] of Object.entries(raw.field_indexes?.numeric ?? {})) {
-    numeric[field] = entries.map((e) => ({ value: e.value, docId: e.doc_id }));
-  }
-  const boolean = {};
-  for (const [field, idx] of Object.entries(raw.field_indexes?.boolean ?? {})) {
-    boolean[field] = { trueDocs: idx.true_docs ?? [], falseDocs: idx.false_docs ?? [] };
-  }
-  const geopoint = {};
-  for (const [field, entries] of Object.entries(raw.field_indexes?.geopoint ?? {})) {
-    geopoint[field] = entries.map((e) => ({ lat: e.lat, lon: e.lon, docId: e.doc_id }));
-  }
-  const vectorData = {};
-  for (const [field, data] of Object.entries(raw.vector_data ?? {})) {
-    vectorData[field] = {
-      dimension: data.dimension,
-      vectors: (data.vectors ?? []).map((v) => ({ docId: v.doc_id, vector: v.vector })),
-      hnswGraph: data.hnsw_graph ? {
-        entryPoint: data.hnsw_graph.entry_point,
-        maxLayer: data.hnsw_graph.max_layer,
-        m: data.hnsw_graph.m,
-        efConstruction: data.hnsw_graph.ef_construction,
-        metric: validateHnswMetric(data.hnsw_graph.metric),
-        nodes: data.hnsw_graph.nodes
-      } : null
-    };
-  }
+  async function shutdown() {
+    isShuttingDown = true;
+    if (flushTimerId !== null) {
+      clearInterval(flushTimerId);
+      flushTimerId = null;
+    }
+    await flush();
+  }
   return {
-    indexName: raw.index_name,
-    partitionId: raw.partition_id,
-    totalPartitions: raw.total_partitions,
-    language: raw.language ?? "english",
-    schema: raw.schema ?? {},
-    docCount: raw.doc_count ?? 0,
-    avgDocLength: raw.avg_doc_length ?? 0,
-    documents,
-    invertedIndex,
-    fieldIndexes: {
-      numeric,
-      boolean,
-      enum: raw.field_indexes?.enum ?? {},
-      geopoint
+    markDirty,
+    flush,
+    shutdown
+  };
+}
+
+// src/plugins/registry.ts
+function isThenable(value) {
+  return value !== null && typeof value === "object" && typeof value.then === "function";
+}
+async function continueAsync(pending, hooks, startIndex, context) {
+  await pending;
+  for (let i = startIndex; i < hooks.length; i++) {
+    await hooks[i](context);
+  }
+}
+function createPluginRegistry() {
+  const plugins = [];
+  return {
+    register(plugin) {
+      plugins.push(plugin);
     },
-    vectorData,
-    statistics: {
-      totalDocuments: raw.statistics?.total_documents ?? 0,
-      totalFieldLengths: raw.statistics?.total_field_lengths ?? {},
-      averageFieldLengths: raw.statistics?.average_field_lengths ?? {},
-      docFrequencies: raw.statistics?.doc_frequencies ?? {}
+    hasHooks(hookName) {
+      return plugins.some((p) => typeof p[hookName] === "function");
+    },
+    runHook(hookName, context) {
+      const hooks = [];
+      for (const plugin of plugins) {
+        const hook = plugin[hookName];
+        if (typeof hook === "function") {
+          hooks.push(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);
+        }
+      }
     }
   };
 }
-function deserializePayloadV1(data) {
-  const raw = decode(data);
-  return wireToPartition(raw);
+
+// src/schema/embedding-validator.ts
+var VECTOR_DIMENSION_PATTERN = /^vector\[(\d+)]$/;
+function validateEmbeddingConfig(embeddingConfig, schema, instanceAdapter) {
+  const fieldEntries = Object.keys(embeddingConfig.fields);
+  if (fieldEntries.length === 0) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      "Embedding config must define at least one field mapping"
+    );
+  }
+  const resolvedAdapter = embeddingConfig.adapter ?? instanceAdapter;
+  if (!resolvedAdapter) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      "Embedding config requires an adapter (set on the index or the instance)"
+    );
+  }
+  if (typeof resolvedAdapter.dimensions !== "number" || !Number.isInteger(resolvedAdapter.dimensions) || resolvedAdapter.dimensions <= 0) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      `Adapter dimensions must be a positive integer, got ${resolvedAdapter.dimensions}`
+    );
+  }
+  const flatFields = flattenSchema(schema);
+  for (const [targetField, sourceFields] of Object.entries(embeddingConfig.fields)) {
+    const targetType = flatFields[targetField];
+    if (targetType === void 0) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        `Embedding target field "${targetField}" does not exist in the schema`,
+        { field: targetField }
+      );
+    }
+    const vectorMatch = VECTOR_DIMENSION_PATTERN.exec(targetType);
+    if (!vectorMatch) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        `Embedding target field "${targetField}" must be a vector type, got "${targetType}"`,
+        { field: targetField, type: targetType }
+      );
+    }
+    const schemaDimension = Number.parseInt(vectorMatch[1], 10);
+    if (schemaDimension !== resolvedAdapter.dimensions) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_DIMENSION_MISMATCH,
+        `Embedding target field "${targetField}" has dimension ${schemaDimension} but the adapter produces ${resolvedAdapter.dimensions}-dimensional vectors`,
+        { field: targetField, expected: schemaDimension, actual: resolvedAdapter.dimensions }
+      );
+    }
+    const sources = Array.isArray(sourceFields) ? sourceFields : [sourceFields];
+    if (sources.length === 0) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        `Embedding target field "${targetField}" must have at least one source field`,
+        { field: targetField }
+      );
+    }
+    for (const source of sources) {
+      const sourceType = flatFields[source];
+      if (sourceType === void 0) {
+        throw new NarsilError(
+          ErrorCodes.EMBEDDING_CONFIG_INVALID,
+          `Embedding source field "${source}" does not exist in the schema`,
+          { field: source, targetField }
+        );
+      }
+      if (sourceType !== "string") {
+        throw new NarsilError(
+          ErrorCodes.EMBEDDING_CONFIG_INVALID,
+          `Embedding source field "${source}" must be a string type, got "${sourceType}"`,
+          { field: source, type: sourceType, targetField }
+        );
+      }
+    }
+  }
+  return resolvedAdapter;
+}
+function validateRequiredFieldsInSchema(required, schema) {
+  if (required.length === 0) return;
+  const flatFields = flattenSchema(schema);
+  for (const field of required) {
+    if (flatFields[field] === void 0) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        `Required field "${field}" does not exist in the schema`,
+        { field }
+      );
+    }
+  }
 }
 
 // src/workers/promoter.ts
@@ -1410,6 +2850,9 @@ function createExecutionPromoter(config) {
 }
 
 // src/narsil.ts
+function getVectorFieldPaths(schema) {
+  return new Set(extractVectorFieldsFromSchema(schema).keys());
+}
 async function createNarsil(config) {
   const executor = createDirectExecutor();
   const promoter = createExecutionPromoter({
@@ -1418,9 +2861,7 @@ async function createNarsil(config) {
   });
   const pluginRegistry = createPluginRegistry();
   if (config?.plugins) {
-    for (const plugin of config.plugins) {
-      pluginRegistry.register(plugin);
-    }
+    for (const plugin of config.plugins) pluginRegistry.register(plugin);
   }
   let flushManager = null;
   if (config?.persistence) {
@@ -1447,13 +2888,12 @@ async function createNarsil(config) {
   const indexRegistry = /* @__PURE__ */ new Map();
   const eventHandlers = /* @__PURE__ */ new Map();
   let isShutdown = false;
+  const abortController = new AbortController();
   const orchestrator = createWorkerOrchestrator(config, executor, promoter, indexRegistry, {
     onPromotion(workerCount, reason) {
       const handlers = eventHandlers.get("workerPromote");
       if (handlers) {
-        for (const handler of handlers) {
-          handler({ workerCount, reason });
-        }
+        for (const handler of handlers) handler({ workerCount, reason });
       }
     }
   });
@@ -1478,7 +2918,8 @@ async function createNarsil(config) {
     if (!rebalancingIndexes.has(indexName)) return false;
     const waq = waqMap.get(indexName);
     if (!waq) return false;
-    waq.push(entry);
+    const clonedEntry = entry.document ? { ...entry, document: structuredClone(entry.document) } : entry;
+    waq.push(clonedEntry);
     return true;
   }
   function requireManager(indexName) {
@@ -1488,6 +2929,27 @@ async function createNarsil(config) {
     }
     return manager;
   }
+  const mutationCtx = {
+    executor,
+    pluginRegistry,
+    flushManager,
+    orchestrator,
+    idGenerator,
+    abortController,
+    guardShutdown,
+    requireIndex,
+    requireManager,
+    bufferIfRebalancing
+  };
+  const rebalanceCtx = {
+    rebalancer,
+    router: rebalanceRouter,
+    waqMap,
+    rebalancingIndexes,
+    lastAppliedSeqMap,
+    eventHandlers,
+    requireIndex
+  };
   const narsil = {
     async createIndex(name, indexConfig) {
       guardShutdown();
@@ -1496,9 +2958,22 @@ async function createNarsil(config) {
         throw new NarsilError(ErrorCodes.INDEX_ALREADY_EXISTS, `Index "${name}" already exists`, { indexName: name });
       }
       validateSchema(indexConfig.schema);
+      let resolvedEmbeddingAdapter = null;
+      if (indexConfig.embedding) {
+        resolvedEmbeddingAdapter = validateEmbeddingConfig(indexConfig.embedding, indexConfig.schema, config?.embedding);
+      }
+      if (indexConfig.required && indexConfig.required.length > 0) {
+        validateRequiredFieldsInSchema(indexConfig.required, indexConfig.schema);
+      }
       const language = getLanguage(indexConfig.language ?? "english");
       executor.createIndex(name, indexConfig, language);
-      indexRegistry.set(name, { config: indexConfig, language });
+      const vectorFieldPaths = getVectorFieldPaths(indexConfig.schema);
+      indexRegistry.set(name, {
+        config: indexConfig,
+        language,
+        embeddingAdapter: resolvedEmbeddingAdapter,
+        vectorFieldPaths
+      });
       await pluginRegistry.runHook("onIndexCreate", { indexName: name, config: indexConfig });
     },
     async dropIndex(name) {
@@ -1525,12 +3000,12 @@ async function createNarsil(config) {
       guardShutdown();
       const entry = requireIndex(indexName);
       const manager = executor.getManager(indexName);
-      const estimatedMemory = manager?.estimateMemoryBytes() ?? 0;
+      const mem = manager?.estimateMemoryBytes() ?? 0;
       return {
         documentCount: manager?.countDocuments() ?? 0,
         partitionCount: manager?.partitionCount ?? 0,
-        memoryBytes: estimatedMemory,
-        indexSizeBytes: estimatedMemory,
+        memoryBytes: mem,
+        indexSizeBytes: mem,
         language: entry.language.name,
         schema: entry.config.schema
       };
@@ -1538,197 +3013,25 @@ async function createNarsil(config) {
     getPartitionStats(indexName) {
       guardShutdown();
       requireIndex(indexName);
-      const manager = executor.getManager(indexName);
-      return manager?.getPartitionStats() ?? [];
+      return executor.getManager(indexName)?.getPartitionStats() ?? [];
     },
-    async insert(indexName, document, docId, options) {
-      guardShutdown();
-      requireIndex(indexName);
-      const resolvedDocId = docId ?? idGenerator();
-      validateDocId(resolvedDocId);
-      if (bufferIfRebalancing(indexName, { action: "insert", docId: resolvedDocId, document, indexName })) {
-        return resolvedDocId;
-      }
-      await pluginRegistry.runHook("beforeInsert", { indexName, docId: resolvedDocId, document });
-      await executor.execute({
-        type: "insert",
-        indexName,
-        docId: resolvedDocId,
-        document,
-        requestId: resolvedDocId,
-        skipClone: options?.skipClone
-      });
-      try {
-        await pluginRegistry.runHook("afterInsert", { indexName, docId: resolvedDocId, document });
-      } catch (err) {
-        console.warn("afterInsert plugin hook error:", err);
-      }
-      flushManager?.markDirty(indexName, 0);
-      await orchestrator.replicateToWorkers({
-        type: "insert",
-        indexName,
-        docId: resolvedDocId,
-        document,
-        requestId: `replicate-insert-${resolvedDocId}`,
-        skipClone: options?.skipClone
-      });
-      await orchestrator.checkPromotion();
-      return resolvedDocId;
+    insert(indexName, document, docId, options) {
+      return insertDocument(mutationCtx, indexName, document, docId, options);
     },
-    async insertBatch(indexName, documents, options) {
-      guardShutdown();
-      requireIndex(indexName);
-      const succeeded = [];
-      const failed = [];
-      const hasBeforeHook = pluginRegistry.hasHooks("beforeInsert");
-      const hasAfterHook = pluginRegistry.hasHooks("afterInsert");
-      for (let chunkStart = 0; chunkStart < documents.length; chunkStart += BATCH_CHUNK_SIZE) {
-        const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, documents.length);
-        for (let i = chunkStart; i < chunkEnd; i++) {
-          const docId = idGenerator();
-          try {
-            validateDocId(docId);
-            if (hasBeforeHook) {
-              await pluginRegistry.runHook("beforeInsert", { indexName, docId, document: documents[i] });
-            }
-            const result = executor.execute({
-              type: "insert",
-              indexName,
-              docId,
-              document: documents[i],
-              requestId: docId,
-              skipClone: options?.skipClone
-            });
-            if (result && typeof result.then === "function") {
-              await result;
-            }
-            if (hasAfterHook) {
-              try {
-                await pluginRegistry.runHook("afterInsert", { indexName, docId, document: documents[i] });
-              } catch (err) {
-                console.warn("afterInsert plugin hook error:", err);
-              }
-            }
-            succeeded.push(docId);
-          } catch (err) {
-            failed.push({
-              docId,
-              error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, String(err))
-            });
-          }
-        }
-        if (chunkEnd < documents.length) {
-          await new Promise((r) => setTimeout(r, 0));
-        }
-      }
-      flushManager?.markDirty(indexName, 0);
-      await orchestrator.checkPromotion();
-      return { succeeded, failed };
+    insertBatch(indexName, documents, options) {
+      return insertDocumentBatch(mutationCtx, indexName, documents, options);
     },
-    async remove(indexName, docId) {
-      guardShutdown();
-      requireIndex(indexName);
-      validateDocId(docId);
-      if (bufferIfRebalancing(indexName, { action: "remove", docId, indexName })) {
-        return;
-      }
-      await pluginRegistry.runHook("beforeRemove", { indexName, docId });
-      await executor.execute({ type: "remove", indexName, docId, requestId: docId });
-      try {
-        await pluginRegistry.runHook("afterRemove", { indexName, docId });
-      } catch (err) {
-        console.warn("afterRemove plugin hook error:", err);
-      }
-      flushManager?.markDirty(indexName, 0);
-      await orchestrator.replicateToWorkers({
-        type: "remove",
-        indexName,
-        docId,
-        requestId: `replicate-remove-${docId}`
-      });
+    remove(indexName, docId) {
+      return removeDocument(mutationCtx, indexName, docId);
     },
-    async removeBatch(indexName, docIds) {
-      guardShutdown();
-      requireIndex(indexName);
-      const succeeded = [];
-      const failed = [];
-      for (let chunkStart = 0; chunkStart < docIds.length; chunkStart += BATCH_CHUNK_SIZE) {
-        const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, docIds.length);
-        for (let i = chunkStart; i < chunkEnd; i++) {
-          try {
-            await narsil.remove(indexName, docIds[i]);
-            succeeded.push(docIds[i]);
-          } catch (err) {
-            failed.push({
-              docId: docIds[i],
-              error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_NOT_FOUND, String(err))
-            });
-          }
-        }
-        if (chunkEnd < docIds.length) {
-          await new Promise((r) => setTimeout(r, 0));
-        }
-      }
-      return { succeeded, failed };
+    removeBatch(indexName, docIds) {
+      return removeDocumentBatch(mutationCtx, indexName, docIds);
     },
-    async update(indexName, docId, document) {
-      guardShutdown();
-      requireIndex(indexName);
-      validateDocId(docId);
-      if (bufferIfRebalancing(indexName, { action: "update", docId, document, indexName })) {
-        return;
-      }
-      const manager = executor.getManager(indexName);
-      const oldDocument = manager?.get(docId);
-      await pluginRegistry.runHook("beforeUpdate", {
-        indexName,
-        docId,
-        oldDocument: oldDocument ?? {},
-        newDocument: document
-      });
-      await executor.execute({ type: "update", indexName, docId, document, requestId: docId });
-      try {
-        await pluginRegistry.runHook("afterUpdate", {
-          indexName,
-          docId,
-          oldDocument: oldDocument ?? {},
-          newDocument: document
-        });
-      } catch (err) {
-        console.warn("afterUpdate plugin hook error:", err);
-      }
-      flushManager?.markDirty(indexName, 0);
-      await orchestrator.replicateToWorkers({
-        type: "update",
-        indexName,
-        docId,
-        document,
-        requestId: `replicate-update-${docId}`
-      });
+    update(indexName, docId, document) {
+      return updateDocument(mutationCtx, indexName, docId, document);
     },
-    async updateBatch(indexName, updates) {
-      guardShutdown();
-      requireIndex(indexName);
-      const succeeded = [];
-      const failed = [];
-      for (let chunkStart = 0; chunkStart < updates.length; chunkStart += BATCH_CHUNK_SIZE) {
-        const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, updates.length);
-        for (let i = chunkStart; i < chunkEnd; i++) {
-          try {
-            await narsil.update(indexName, updates[i].docId, updates[i].document);
-            succeeded.push(updates[i].docId);
-          } catch (err) {
-            failed.push({
-              docId: updates[i].docId,
-              error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_NOT_FOUND, String(err))
-            });
-          }
-        }
-        if (chunkEnd < updates.length) {
-          await new Promise((r) => setTimeout(r, 0));
-        }
-      }
-      return { succeeded, failed };
+    updateBatch(indexName, updates) {
+      return updateDocumentBatch(mutationCtx, indexName, updates);
     },
     async get(indexName, docId) {
       guardShutdown();
@@ -1741,9 +3044,7 @@ async function createNarsil(config) {
       const result = /* @__PURE__ */ new Map();
       for (const docId of docIds) {
         const doc = await narsil.get(indexName, docId);
-        if (doc !== void 0) {
-          result.set(docId, doc);
-        }
+        if (doc !== void 0) result.set(docId, doc);
       }
       return result;
     },
@@ -1761,9 +3062,10 @@ async function createNarsil(config) {
       guardShutdown();
       const entry = requireIndex(indexName);
       const manager = requireManager(indexName);
-      await pluginRegistry.runHook("beforeSearch", { indexName, params });
+      const resolvedParams = await resolveVectorText(params, entry.embeddingAdapter, abortController.signal);
+      await pluginRegistry.runHook("beforeSearch", { indexName, params: resolvedParams });
       const workerSearch = orchestrator.isPromoted() ? orchestrator.searchViaWorker.bind(orchestrator) : void 0;
-      const result = await executeQuery(params, {
+      const result = await executeQuery(resolvedParams, {
         manager,
         language: entry.language,
         config: entry.config,
@@ -1773,7 +3075,7 @@ async function createNarsil(config) {
       try {
         await pluginRegistry.runHook("afterSearch", {
           indexName,
-          params,
+          params: resolvedParams,
           results: result
         });
       } catch (err) {
@@ -1785,8 +3087,9 @@ async function createNarsil(config) {
       guardShutdown();
       const entry = requireIndex(indexName);
       const manager = requireManager(indexName);
+      const resolvedParams = await resolveVectorText(params, entry.embeddingAdapter, abortController.signal);
       const workerSearch = orchestrator.isPromoted() ? orchestrator.searchViaWorker.bind(orchestrator) : void 0;
-      return executePreflight(params, {
+      return executePreflight(resolvedParams, {
         manager,
         language: entry.language,
         config: entry.config,
@@ -1796,105 +3099,23 @@ async function createNarsil(config) {
     },
     async suggest(indexName, params) {
       guardShutdown();
-      const entry = requireIndex(indexName);
-      const manager = requireManager(indexName);
-      const t0 = performance.now();
-      const limit = Math.max(1, Math.min(params.limit ?? 10, 100));
-      const rawPrefix = params.prefix.trim();
-      if (rawPrefix.length === 0) {
-        return { terms: [], elapsed: performance.now() - t0 };
-      }
-      const unstemmed = tokenize(rawPrefix, entry.language, { stem: false, removeStopWords: false });
-      const lastToken = unstemmed.tokens.length > 0 ? unstemmed.tokens[unstemmed.tokens.length - 1].token : rawPrefix.toLowerCase();
-      if (lastToken.length === 0) {
-        return { terms: [], elapsed: performance.now() - t0 };
-      }
-      const stemmed = entry.language.stemmer ? entry.language.stemmer(lastToken) : lastToken;
-      const prefixes = stemmed !== lastToken ? [lastToken, stemmed] : [lastToken];
-      const partitions = manager.getAllPartitions();
-      const merged = /* @__PURE__ */ new Map();
-      const perPartitionLimit = limit * 2;
-      for (const partition of partitions) {
-        const seen = /* @__PURE__ */ new Set();
-        for (const prefix of prefixes) {
-          const suggestions = partition.suggestTerms(prefix, perPartitionLimit);
-          for (const s of suggestions) {
-            if (seen.has(s.term)) continue;
-            seen.add(s.term);
-            merged.set(s.term, (merged.get(s.term) ?? 0) + s.documentFrequency);
-          }
-        }
-      }
-      const terms = Array.from(merged.entries()).map(([term, documentFrequency]) => ({ term, documentFrequency })).sort((a, b) => b.documentFrequency - a.documentFrequency);
-      if (terms.length > limit) terms.length = limit;
-      return { terms, elapsed: performance.now() - t0 };
+      return executeSuggest(requireManager(indexName), requireIndex(indexName).language, params);
     },
     async snapshot(indexName) {
       guardShutdown();
-      const entry = requireIndex(indexName);
-      const manager = requireManager(indexName);
-      const partitionBuffers = [];
-      for (let i = 0; i < manager.partitionCount; i++) {
-        partitionBuffers.push(manager.serializePartitionToBytes(i));
-      }
-      const { encode: encode2 } = await import('@msgpack/msgpack');
-      return encode2({
-        version: 2,
-        schema: entry.config.schema,
-        language: entry.language.name,
-        partitions: partitionBuffers
-      });
+      return createSnapshot(requireManager(indexName), requireIndex(indexName));
     },
     async restore(indexName, data) {
       guardShutdown();
-      if (!(data instanceof Uint8Array)) {
-        throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Snapshot data must be a Uint8Array");
-      }
-      const { decode: decode2 } = await import('@msgpack/msgpack');
-      const envelope = decode2(data);
-      if (envelope.version !== 1 && envelope.version !== 2) {
-        throw new NarsilError(
-          ErrorCodes.DOC_VALIDATION_FAILED,
-          `Unsupported snapshot version: ${envelope.version}. Expected version 1 or 2`,
-          { version: envelope.version }
-        );
-      }
-      if (!envelope.schema || typeof envelope.schema !== "object") {
-        throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Invalid snapshot: missing or invalid schema");
-      }
-      if (!envelope.language || typeof envelope.language !== "string") {
-        throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Invalid snapshot: missing or invalid language");
-      }
-      if (!Array.isArray(envelope.partitions)) {
-        throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Invalid snapshot: missing partitions");
-      }
-      const language = getLanguage(envelope.language);
-      const schema = envelope.schema;
-      validateSchema(schema);
-      if (indexRegistry.has(indexName)) {
-        await narsil.dropIndex(indexName);
-      }
-      const indexConfig = { schema, language: envelope.language };
-      executor.createIndex(indexName, indexConfig, language);
-      indexRegistry.set(indexName, { config: indexConfig, language });
-      try {
-        const manager = requireManager(indexName);
-        while (manager.partitionCount < envelope.partitions.length) {
-          manager.addPartition();
-        }
-        const deserializePartitionPayload = envelope.version === 2 ? deserializePayloadV2 : deserializePayloadV1;
-        for (let i = 0; i < envelope.partitions.length; i++) {
-          const partition = deserializePartitionPayload(envelope.partitions[i]);
-          manager.deserializePartition(i, partition);
-        }
-      } catch (err) {
-        try {
-          executor.dropIndex(indexName);
-          indexRegistry.delete(indexName);
-        } catch (_) {
-        }
-        throw err;
-      }
+      return restoreFromSnapshot(
+        indexName,
+        data,
+        executor,
+        indexRegistry,
+        getVectorFieldPaths,
+        narsil.dropIndex.bind(narsil),
+        requireManager
+      );
     },
     async clear(indexName) {
       guardShutdown();
@@ -1905,65 +3126,7 @@ async function createNarsil(config) {
     async rebalance(indexName, targetPartitionCount) {
       guardShutdown();
       requireIndex(indexName);
-      const manager = requireManager(indexName);
-      if (targetPartitionCount <= 0 || !Number.isInteger(targetPartitionCount)) {
-        throw new NarsilError(
-          ErrorCodes.PARTITION_CAPACITY_EXCEEDED,
-          `Target partition count must be a positive integer, got ${targetPartitionCount}`,
-          { targetPartitionCount }
-        );
-      }
-      if (rebalancingIndexes.has(indexName)) {
-        throw new NarsilError(
-          ErrorCodes.PARTITION_REBALANCING_BACKPRESSURE,
-          `Index "${indexName}" is already being rebalanced`
-        );
-      }
-      if (targetPartitionCount === manager.partitionCount) {
-        return;
-      }
-      const waq = createWriteAheadQueue();
-      waqMap.set(indexName, waq);
-      rebalancingIndexes.add(indexName);
-      try {
-        const oldCount = manager.partitionCount;
-        await rebalancer.rebalance(manager, targetPartitionCount, rebalanceRouter, (progress) => {
-          if (progress.phase === "complete") {
-            const handlers = eventHandlers.get("partitionRebalance");
-            if (handlers) {
-              for (const handler of handlers) {
-                handler({ indexName, oldCount, newCount: targetPartitionCount });
-              }
-            }
-          }
-        });
-        const entries = waq.drain();
-        const appliedSeqs = lastAppliedSeqMap.get(indexName) ?? /* @__PURE__ */ new Map();
-        for (const entry of entries) {
-          const partitionLastSeq = appliedSeqs.get(0) ?? 0;
-          if (entry.sequenceNumber <= partitionLastSeq) continue;
-          try {
-            if (entry.action === "insert" && entry.document) {
-              manager.insert(entry.docId, entry.document);
-            } else if (entry.action === "remove") {
-              manager.remove(entry.docId);
-            } else if (entry.action === "update" && entry.document) {
-              manager.update(entry.docId, entry.document);
-            }
-          } catch (replayErr) {
-            const isDuplicate = replayErr instanceof NarsilError && replayErr.code === ErrorCodes.DOC_ALREADY_EXISTS;
-            const isMissing = replayErr instanceof NarsilError && replayErr.code === ErrorCodes.DOC_NOT_FOUND;
-            if (!isDuplicate && !isMissing) {
-              console.warn(`WAQ replay failed for ${entry.action} on doc "${entry.docId}":`, replayErr);
-            }
-          }
-          appliedSeqs.set(0, entry.sequenceNumber);
-        }
-        lastAppliedSeqMap.set(indexName, appliedSeqs);
-      } finally {
-        rebalancingIndexes.delete(indexName);
-        waqMap.delete(indexName);
-      }
+      return executeRebalance(requireManager(indexName), indexName, targetPartitionCount, rebalanceCtx);
     },
     async updatePartitionConfig(indexName, partitionConfig) {
       guardShutdown();
@@ -1988,29 +3151,35 @@ async function createNarsil(config) {
           );
         }
       }
-      if (!entry.config.partitions) {
-        entry.config.partitions = {};
-      }
-      if (partitionConfig.maxDocsPerPartition !== void 0) {
+      if (!entry.config.partitions) entry.config.partitions = {};
+      if (partitionConfig.maxDocsPerPartition !== void 0)
         entry.config.partitions.maxDocsPerPartition = partitionConfig.maxDocsPerPartition;
-      }
-      if (partitionConfig.maxPartitions !== void 0) {
+      if (partitionConfig.maxPartitions !== void 0)
         entry.config.partitions.maxPartitions = partitionConfig.maxPartitions;
-      }
     },
     getMemoryStats() {
       const workerStats = orchestrator.getMemoryStats();
       let mainThreadBytes = 0;
       for (const [name] of indexRegistry) {
-        const manager = executor.getManager(name);
-        if (manager) {
-          mainThreadBytes += manager.estimateMemoryBytes();
-        }
+        const mgr = executor.getManager(name);
+        if (mgr) mainThreadBytes += mgr.estimateMemoryBytes();
       }
-      return {
-        totalBytes: mainThreadBytes + workerStats.totalBytes,
-        workers: workerStats.workers
-      };
+      return { totalBytes: mainThreadBytes + workerStats.totalBytes, workers: workerStats.workers };
+    },
+    async compactVectors(indexName, fieldName) {
+      guardShutdown();
+      requireIndex(indexName);
+      compactVectors(requireManager(indexName), indexName, fieldName);
+    },
+    async optimizeVectors(indexName, fieldName) {
+      guardShutdown();
+      requireIndex(indexName);
+      await optimizeVectors(requireManager(indexName), indexName, fieldName);
+    },
+    vectorMaintenanceStatus(indexName) {
+      guardShutdown();
+      requireIndex(indexName);
+      return getVectorMaintenanceStatus(requireManager(indexName));
     },
     on(event, handler) {
       const key = event;
@@ -2026,16 +3195,31 @@ async function createNarsil(config) {
       const handlers = eventHandlers.get(key);
       if (handlers) {
         handlers.delete(handler);
-        if (handlers.size === 0) {
-          eventHandlers.delete(key);
-        }
+        if (handlers.size === 0) eventHandlers.delete(key);
       }
     },
     async shutdown() {
       if (isShutdown) return;
       isShutdown = true;
-      if (flushManager) {
-        await flushManager.shutdown();
+      abortController.abort();
+      for (const [name] of indexRegistry) {
+        const mgr = executor.getManager(name);
+        if (mgr) {
+          for (const [, vecIdx] of mgr.getVectorIndexes()) {
+            vecIdx.dispose();
+          }
+        }
+      }
+      if (flushManager) await flushManager.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();