@delali/narsil 0.1.8 → 0.1.10

package/dist/index.browser.mjs

@@ -1049,6 +1049,38 @@ function extractVectorFieldsFromSchema(schema) {
   }
   return result;
 }
+
+// src/schema/validator/vector-promotion.ts
+function fail(message, details) {
+  throw new NarsilError(ErrorCodes.CONFIG_INVALID, message, details);
+}
+function isPositiveInteger(value) {
+  return Number.isInteger(value) && value >= 1;
+}
+function validateVectorPromotion(config) {
+  if (config === void 0) return;
+  if (config.threshold !== void 0 && !isPositiveInteger(config.threshold)) {
+    fail("vectorPromotion.threshold must be a positive integer", { threshold: config.threshold });
+  }
+  const quantization = config.quantization;
+  if (quantization !== void 0 && quantization !== "sq8" && quantization !== "none") {
+    fail("vectorPromotion.quantization must be 'sq8' or 'none'", { quantization });
+  }
+  const hnsw = config.hnswConfig;
+  if (hnsw === void 0) return;
+  if (hnsw.m !== void 0 && !isPositiveInteger(hnsw.m)) {
+    fail("vectorPromotion.hnswConfig.m must be a positive integer", { m: hnsw.m });
+  }
+  if (hnsw.efConstruction !== void 0 && !isPositiveInteger(hnsw.efConstruction)) {
+    fail("vectorPromotion.hnswConfig.efConstruction must be a positive integer", {
+      efConstruction: hnsw.efConstruction
+    });
+  }
+  const metric = hnsw.metric;
+  if (metric !== void 0 && metric !== "cosine" && metric !== "dotProduct" && metric !== "euclidean") {
+    fail("vectorPromotion.hnswConfig.metric must be 'cosine', 'dotProduct', or 'euclidean'", { metric });
+  }
+}
 function encodeRawPayloadV2(wire) {
   return encode(wire);
 }
@@ -3992,6 +4024,123 @@ function createPluginRegistry() {
   };
 }
 
+// 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"
+    );
+  }
+  if (typeof embeddingConfig.adapter === "string") {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      `Embedding adapter "${embeddingConfig.adapter}" must be resolved against the engine registry before validation`,
+      { adapter: embeddingConfig.adapter }
+    );
+  }
+  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 validateRegisteredAdapter(name, adapter) {
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new NarsilError(ErrorCodes.EMBEDDING_CONFIG_INVALID, "Embedding adapter names must be non-empty strings");
+  }
+  if (typeof adapter?.embed !== "function") {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      `Embedding adapter "${name}" must provide an embed function`,
+      { adapter: name }
+    );
+  }
+  if (typeof adapter.dimensions !== "number" || !Number.isInteger(adapter.dimensions) || adapter.dimensions <= 0) {
+    throw new NarsilError(
+      ErrorCodes.EMBEDDING_CONFIG_INVALID,
+      `Embedding adapter "${name}" dimensions must be a positive integer, got ${adapter.dimensions}`,
+      { adapter: name, dimensions: adapter.dimensions }
+    );
+  }
+}
+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/search/facets.ts
 function mergeFacets(partitionFacets) {
   const merged = /* @__PURE__ */ new Map();
@@ -6027,6 +6176,14 @@ function createHNSWIndex(dimension, store, config, quantizer) {
   };
 }
 
+// src/workers/node-worker.browser.ts
+async function spawnNodeWorker(_entryPoint) {
+  return null;
+}
+async function isNodeMainThread() {
+  return true;
+}
+
 // src/runtime/detect.ts
 function detectRuntimeName() {
   if ("Bun" in globalThis) {
@@ -6076,9 +6233,7 @@ async function spawnWorker() {
   const entryPoint = resolveWorkerEntryPoint();
   if (runtime.supportsWorkerThreads) {
     try {
-      const workerThreads = await import('worker_threads');
-      const instance = new workerThreads.Worker(new URL(entryPoint));
-      return instance;
+      return await spawnNodeWorker(new URL(entryPoint));
     } catch {
       return null;
     }
@@ -6966,21 +7121,21 @@ function createExecutionPromoter(config) {
   return { check, markPromoted, isPromoted };
 }
 
-// src/persistence/durability/durable-filesystem.ts
-var cachedFs = null;
-var cachedPath = null;
+// src/persistence/durability/node-fs.browser.ts
+function filesystemUnavailable() {
+  throw new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    "Filesystem durability requires a Node.js runtime; use the memory or IndexedDB persistence adapters in the browser"
+  );
+}
 async function getFs() {
-  if (cachedFs === null) {
-    cachedFs = await import('fs/promises');
-  }
-  return cachedFs;
+  return filesystemUnavailable();
 }
 async function getPath() {
-  if (cachedPath === null) {
-    cachedPath = await import('path');
-  }
-  return cachedPath;
+  return filesystemUnavailable();
 }
+
+// src/persistence/durability/durable-filesystem.ts
 function validateRelativeKey(key) {
   if (key.length === 0) {
     throw new NarsilError(ErrorCodes.PERSISTENCE_SAVE_FAILED, "Invalid key: empty");
@@ -7293,12 +7448,7 @@ var mainThreadResolved = false;
 var onMainThread = true;
 async function isOnMainThread() {
   if (!mainThreadResolved) {
-    try {
-      const workerThreads = await import('worker_threads');
-      onMainThread = workerThreads.isMainThread;
-    } catch {
-      onMainThread = true;
-    }
+    onMainThread = await isNodeMainThread();
     mainThreadResolved = true;
   }
   return onMainThread;
@@ -7313,8 +7463,7 @@ function resolveWorkerEntryPoint2() {
 }
 async function spawnWorker2() {
   try {
-    const workerThreads = await import('worker_threads');
-    return new workerThreads.Worker(new URL(resolveWorkerEntryPoint2()));
+    return await spawnNodeWorker(new URL(resolveWorkerEntryPoint2()));
   } catch {
     return null;
   }
@@ -7580,6 +7729,9 @@ function metadataToWire(meta) {
   if (meta.vectorFields) {
     wire.vector_fields = meta.vectorFields;
   }
+  if (meta.embedding) {
+    wire.embedding = meta.embedding.adapter !== void 0 ? { adapter: meta.embedding.adapter, fields: meta.embedding.fields } : { fields: meta.embedding.fields };
+  }
   return wire;
 }
 function wireToMetadata(raw) {
@@ -7595,6 +7747,9 @@ function wireToMetadata(raw) {
   if (raw.vector_fields) {
     meta.vectorFields = raw.vector_fields;
   }
+  if (raw.embedding && typeof raw.embedding === "object" && typeof raw.embedding.fields === "object") {
+    meta.embedding = typeof raw.embedding.adapter === "string" ? { adapter: raw.embedding.adapter, fields: raw.embedding.fields } : { fields: raw.embedding.fields };
+  }
   return meta;
 }
 function serializeMetadata(meta) {
@@ -7987,8 +8142,10 @@ function resolveWorkerEntryPoint3() {
 }
 async function spawnWorker3() {
   try {
-    const workerThreads = await import('worker_threads');
-    const worker = new workerThreads.Worker(new URL(resolveWorkerEntryPoint3()));
+    const worker = await spawnNodeWorker(new URL(resolveWorkerEntryPoint3()));
+    if (worker === null) {
+      return null;
+    }
     if (typeof worker.unref === "function") {
       worker.unref();
     }
@@ -8947,11 +9104,15 @@ function unflattenSchema(flat) {
   return root;
 }
 function reconstructSchemaFromMetadata(metadata) {
-  return {
+  const config = {
     schema: unflattenSchema(metadata.schema),
     language: metadata.language,
     bm25: { k1: metadata.bm25Params.k1, b: metadata.bm25Params.b }
   };
+  if (metadata.embedding) {
+    config.embedding = metadata.embedding.adapter !== void 0 ? { adapter: metadata.embedding.adapter, fields: metadata.embedding.fields } : { fields: metadata.embedding.fields };
+  }
+  return config;
 }
 
 // src/persistence/durability/segment/build-segment.ts
@@ -10399,7 +10560,7 @@ function buildMetadata(indexName, hooks) {
   if (config === void 0 || manager === void 0) {
     return void 0;
   }
-  return {
+  const metadata = {
     indexName,
     schema: config.schema,
     language: config.language,
@@ -10408,6 +10569,10 @@ function buildMetadata(indexName, hooks) {
     createdAt: Date.now(),
     engineVersion: VERSION
   };
+  if (config.embedding) {
+    metadata.embedding = config.embedding;
+  }
+  return metadata;
 }
 function createDurabilityIntegration(tier, hooks) {
   const managerHooks = {
@@ -10928,11 +11093,16 @@ function createDurabilityFromConfig(config, wiring) {
       if (entry === void 0) {
         return void 0;
       }
+      const embedding = entry.config.embedding ? {
+        fields: entry.config.embedding.fields,
+        ...entry.embeddingAdapterName !== null ? { adapter: entry.embeddingAdapterName } : {}
+      } : void 0;
       return {
         schema: flattenSchema(entry.config.schema),
         language: entry.language.name,
         k1: entry.config.bm25?.k1 ?? 1.2,
-        b: entry.config.bm25?.b ?? 0.75
+        b: entry.config.bm25?.b ?? 0.75,
+        ...embedding !== void 0 ? { embedding } : {}
       };
     },
     createIndexFromMetadata: wiring.createIndexFromMetadata,
@@ -10951,6 +11121,13 @@ function createEngineCore(config) {
   }
   const idGenerator = config?.idGenerator ?? generateId;
   const indexRegistry = /* @__PURE__ */ new Map();
+  const embeddingAdapters = /* @__PURE__ */ new Map();
+  if (config?.embeddingAdapters) {
+    for (const [name, adapter] of Object.entries(config.embeddingAdapters)) {
+      validateRegisteredAdapter(name, adapter);
+      embeddingAdapters.set(name, adapter);
+    }
+  }
   const eventHandlers = /* @__PURE__ */ new Map();
   const shutdownState = { isShutdown: false };
   const abortController = new AbortController();
@@ -11000,11 +11177,35 @@ function createEngineCore(config) {
     }
     const indexConfig = reconstructSchemaFromMetadata(metadata);
     const language = getLanguage(indexConfig.language ?? "english");
+    const adapterName = metadata.embedding?.adapter ?? null;
+    let embeddingAdapter = null;
+    if (metadata.embedding) {
+      const candidate = adapterName !== null ? embeddingAdapters.get(adapterName) ?? null : config?.embedding ?? null;
+      if (candidate) {
+        try {
+          validateEmbeddingConfig(
+            { fields: metadata.embedding.fields, adapter: candidate },
+            indexConfig.schema,
+            void 0
+          );
+        } catch (err) {
+          if (err instanceof NarsilError) {
+            throw new NarsilError(err.code, `Recovery of index "${metadata.indexName}" failed: ${err.message}`, {
+              indexName: metadata.indexName,
+              adapter: adapterName ?? void 0
+            });
+          }
+          throw err;
+        }
+        embeddingAdapter = candidate;
+      }
+    }
     executor.createIndex(metadata.indexName, indexConfig, language);
     indexRegistry.set(metadata.indexName, {
       config: indexConfig,
       language,
-      embeddingAdapter: null,
+      embeddingAdapter,
+      embeddingAdapterName: adapterName,
       vectorFieldPaths: getVectorFieldPaths(indexConfig.schema)
     });
   }
@@ -11047,6 +11248,7 @@ function createEngineCore(config) {
     durability,
     idGenerator,
     indexRegistry,
+    embeddingAdapters,
     eventHandlers,
     shutdownState,
     abortController,
@@ -11064,6 +11266,160 @@ function createEngineCore(config) {
     rebalanceCtx
   };
 }
+var MAX_INDEX_NAME_LENGTH = 255;
+
+// src/engine/validation.ts
+var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+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/index-lifecycle.ts
+async function createEngineIndex(core, config, name, indexConfig) {
+  core.guardShutdown();
+  validateIndexName(name);
+  if (core.indexRegistry.has(name)) {
+    throw new NarsilError(ErrorCodes.INDEX_ALREADY_EXISTS, `Index "${name}" already exists`, { indexName: name });
+  }
+  validateSchema(indexConfig.schema);
+  validateVectorPromotion(indexConfig.vectorPromotion);
+  let resolvedEmbeddingAdapter = null;
+  let embeddingAdapterName = null;
+  if (indexConfig.embedding) {
+    let configuredAdapter = indexConfig.embedding.adapter;
+    if (typeof configuredAdapter === "string") {
+      embeddingAdapterName = configuredAdapter;
+      const registered = core.embeddingAdapters.get(configuredAdapter);
+      if (!registered) {
+        throw new NarsilError(
+          ErrorCodes.EMBEDDING_CONFIG_INVALID,
+          `Embedding adapter "${configuredAdapter}" is not registered on this engine`,
+          { adapter: configuredAdapter, available: [...core.embeddingAdapters.keys()] }
+        );
+      }
+      configuredAdapter = registered;
+    }
+    resolvedEmbeddingAdapter = validateEmbeddingConfig(
+      { fields: indexConfig.embedding.fields, adapter: configuredAdapter },
+      indexConfig.schema,
+      config?.embedding
+    );
+  }
+  if (indexConfig.required && indexConfig.required.length > 0) {
+    validateRequiredFieldsInSchema(indexConfig.required, indexConfig.schema);
+  }
+  const language = getLanguage(indexConfig.language ?? "english");
+  core.executor.createIndex(name, indexConfig, language);
+  core.indexRegistry.set(name, {
+    config: indexConfig,
+    language,
+    embeddingAdapter: resolvedEmbeddingAdapter,
+    embeddingAdapterName,
+    vectorFieldPaths: getVectorFieldPaths(indexConfig.schema)
+  });
+  if (core.durability) {
+    await core.durability.manager.persistMetadata(name);
+  }
+  await core.pluginRegistry.runHook("onIndexCreate", { indexName: name, config: indexConfig });
+}
+async function dropEngineIndex(core, name) {
+  core.guardShutdown();
+  const entry = core.requireIndex(name);
+  core.executor.dropIndex(name);
+  core.indexRegistry.delete(name);
+  if (core.durability) {
+    await core.durability.manager.removeIndex(name);
+  }
+  await core.pluginRegistry.runHook("onIndexDrop", { indexName: name, config: entry.config });
+}
+function registerEngineEmbeddingAdapter(core, name, adapter) {
+  core.guardShutdown();
+  validateRegisteredAdapter(name, adapter);
+  const affected = [];
+  for (const [indexName, entry] of core.indexRegistry) {
+    if (entry.embeddingAdapterName !== name || !entry.config.embedding) continue;
+    try {
+      validateEmbeddingConfig({ fields: entry.config.embedding.fields, adapter }, entry.config.schema, void 0);
+    } catch (err) {
+      if (err instanceof NarsilError) {
+        throw new NarsilError(
+          err.code,
+          `Cannot bind embedding adapter "${name}" to index "${indexName}": ${err.message}`,
+          {
+            indexName,
+            adapter: name
+          }
+        );
+      }
+      throw err;
+    }
+    affected.push(entry);
+  }
+  core.embeddingAdapters.set(name, adapter);
+  for (const entry of affected) {
+    entry.embeddingAdapter = adapter;
+  }
+}
 
 // src/engine/lifecycle.ts
 async function shutdownEngine(core) {
@@ -11098,6 +11454,18 @@ async function shutdownEngine(core) {
 }
 
 // src/engine/embed.ts
+function assertDocumentCarriesMappedVectors(document, embeddingConfig, adapterName) {
+  for (const targetField of Object.keys(embeddingConfig.fields)) {
+    const existing = resolveFieldValue(document, targetField);
+    if (existing === void 0 || existing === null) {
+      throw new NarsilError(
+        ErrorCodes.EMBEDDING_CONFIG_INVALID,
+        adapterName ? `The index embeds "${targetField}" via adapter "${adapterName}", which is not registered on this engine. Register the adapter or supply the vector on the document.` : `The index embeds "${targetField}" automatically but no embedding adapter is bound. Bind an adapter or supply the vector on the document.`,
+        adapterName ? { field: targetField, adapter: adapterName } : { field: targetField }
+      );
+    }
+  }
+}
 function validateVector2(vector, targetField, expectedDimensions) {
   if (!(vector instanceof Float32Array)) {
     throw new NarsilError(
@@ -11299,73 +11667,6 @@ async function embedBatchDocumentFields(documents, embeddingConfig, adapter, sig
   }
   return { embedded, failed };
 }
-var MAX_INDEX_NAME_LENGTH = 255;
-
-// src/engine/validation.ts
-var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-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/mutations/durable-rollback.ts
 function rollbackFailed(docId, originalError, rollbackError) {
@@ -11428,13 +11729,21 @@ async function insertDocument(ctx, indexName, document, docId, options) {
   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
-    );
+  if (entry.config.embedding) {
+    if (entry.embeddingAdapter) {
+      await embedDocumentFields(
+        document,
+        entry.config.embedding,
+        entry.embeddingAdapter,
+        ctx.abortController.signal
+      );
+    } else {
+      assertDocumentCarriesMappedVectors(
+        document,
+        entry.config.embedding,
+        entry.embeddingAdapterName
+      );
+    }
   }
   const insertManager = ctx.requireManager(indexName);
   const insertVecIndexes = insertManager.getVectorIndexes();
@@ -11514,6 +11823,7 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
   const hasAfterHook = ctx.pluginRegistry.hasHooks("afterInsert");
   const hasRequired = entry.config.required && entry.config.required.length > 0;
   const hasEmbedding = entry.embeddingAdapter && entry.config.embedding;
+  const embeddingUnbound = !entry.embeddingAdapter && entry.config.embedding;
   const batchManager = ctx.requireManager(indexName);
   const batchVecIndexes = batchManager.getVectorIndexes();
   const batchVectorFieldPaths = batchVecIndexes.size > 0 ? entry.vectorFieldPaths : /* @__PURE__ */ new Set();
@@ -11529,7 +11839,7 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
         } catch (err) {
           chunkFailedIndexes.add(i);
           failed.push({
-            docId: "",
+            docId: providedDocId(documents[i]) ?? "",
             error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, String(err))
           });
         }
@@ -11554,16 +11864,33 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
           for (const [sliceIndex, error] of embedResult.failed) {
             const originalIdx = embeddableOriginalIndexes[sliceIndex];
             chunkFailedIndexes.add(originalIdx);
-            failed.push({ docId: "", error });
+            failed.push({ docId: providedDocId(documents[originalIdx]) ?? "", 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 });
+            failed.push({ docId: providedDocId(documents[originalIdx]) ?? "", error: embeddingError });
           }
         }
       }
+    } else if (embeddingUnbound) {
+      for (let i = chunkStart; i < chunkEnd; i++) {
+        if (chunkFailedIndexes.has(i)) continue;
+        try {
+          assertDocumentCarriesMappedVectors(
+            documents[i],
+            entry.config.embedding,
+            entry.embeddingAdapterName
+          );
+        } catch (err) {
+          chunkFailedIndexes.add(i);
+          failed.push({
+            docId: providedDocId(documents[i]) ?? "",
+            error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.EMBEDDING_FAILED, String(err))
+          });
+        }
+      }
     }
     for (let i = chunkStart; i < chunkEnd; i++) {
       if (ctx.abortController.signal.aborted) break;
@@ -11757,13 +12084,21 @@ async function updateDocument(ctx, indexName, docId, document) {
   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
-    );
+  if (entry.config.embedding) {
+    if (entry.embeddingAdapter) {
+      await embedDocumentFields(
+        document,
+        entry.config.embedding,
+        entry.embeddingAdapter,
+        ctx.abortController.signal
+      );
+    } else {
+      assertDocumentCarriesMappedVectors(
+        document,
+        entry.config.embedding,
+        entry.embeddingAdapterName
+      );
+    }
   }
   const updateManager = ctx.requireManager(indexName);
   const oldDocument = updateManager.get(docId);
@@ -12813,7 +13148,7 @@ async function executeRebalance(manager, indexName, targetPartitionCount, ctx) {
 }
 
 // src/engine/resolve-vector-text.ts
-async function resolveVectorText(params, embeddingAdapter, signal) {
+async function resolveVectorText(params, embeddingAdapter, signal, embeddingAdapterName) {
   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;
@@ -12823,7 +13158,8 @@ async function resolveVectorText(params, embeddingAdapter, signal) {
   if (!embeddingAdapter) {
     throw new NarsilError(
       ErrorCodes.EMBEDDING_CONFIG_INVALID,
-      "Vector query with 'text' requires an embedding adapter on the index or instance"
+      embeddingAdapterName ? `Vector query with 'text' needs embedding adapter "${embeddingAdapterName}", which is not registered on this engine. Register it with registerEmbeddingAdapter or supply a raw vector.` : "Vector query with 'text' requires an embedding adapter on the index or instance",
+      embeddingAdapterName ? { adapter: embeddingAdapterName } : void 0
     );
   }
   if (typeof params.vector.text !== "string") {
@@ -12905,7 +13241,13 @@ async function restoreFromSnapshot(indexName, data, executor, indexRegistry, get
   const indexConfig = { schema, language: envelope.language };
   executor.createIndex(indexName, indexConfig, language);
   const vectorFieldPaths = getVectorFieldPaths2(schema);
-  indexRegistry.set(indexName, { config: indexConfig, language, embeddingAdapter: null, vectorFieldPaths });
+  indexRegistry.set(indexName, {
+    config: indexConfig,
+    language,
+    embeddingAdapter: null,
+    embeddingAdapterName: null,
+    vectorFieldPaths
+  });
   try {
     const manager = requireManager(indexName);
     while (manager.partitionCount < envelope.partitions.length) {
@@ -13036,97 +13378,6 @@ function readProcessMemory() {
   }
 }
 
-// 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/narsil.ts
 async function createNarsil(config) {
   const core = createEngineCore(config);
@@ -13153,43 +13404,14 @@ function createNarsilFromCore(core, config) {
     rebalanceCtx
   } = core;
   const narsil = {
-    async createIndex(name, indexConfig) {
-      guardShutdown();
-      validateIndexName(name);
-      if (indexRegistry.has(name)) {
-        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);
-      const vectorFieldPaths = getVectorFieldPaths(indexConfig.schema);
-      indexRegistry.set(name, {
-        config: indexConfig,
-        language,
-        embeddingAdapter: resolvedEmbeddingAdapter,
-        vectorFieldPaths
-      });
-      if (durability) {
-        await durability.manager.persistMetadata(name);
-      }
-      await pluginRegistry.runHook("onIndexCreate", { indexName: name, config: indexConfig });
+    createIndex(name, indexConfig) {
+      return createEngineIndex(core, config, name, indexConfig);
     },
-    async dropIndex(name) {
-      guardShutdown();
-      const entry = requireIndex(name);
-      executor.dropIndex(name);
-      indexRegistry.delete(name);
-      if (durability) {
-        await durability.manager.removeIndex(name);
-      }
-      await pluginRegistry.runHook("onIndexDrop", { indexName: name, config: entry.config });
+    registerEmbeddingAdapter(name, adapter) {
+      registerEngineEmbeddingAdapter(core, name, adapter);
+    },
+    dropIndex(name) {
+      return dropEngineIndex(core, name);
     },
     listIndexes() {
       const infos = [];
@@ -13268,7 +13490,12 @@ function createNarsilFromCore(core, config) {
       guardShutdown();
       const entry = requireIndex(indexName);
       const manager = requireManager(indexName);
-      const resolvedParams = await resolveVectorText(params, entry.embeddingAdapter, abortController.signal);
+      const resolvedParams = await resolveVectorText(
+        params,
+        entry.embeddingAdapter,
+        abortController.signal,
+        entry.embeddingAdapterName
+      );
       await pluginRegistry.runHook("beforeSearch", { indexName, params: resolvedParams });
       const workerSearch = orchestrator.isPromoted() ? orchestrator.searchViaWorker.bind(orchestrator) : void 0;
       const result = await executeQuery(resolvedParams, {
@@ -13293,7 +13520,12 @@ function createNarsilFromCore(core, config) {
       guardShutdown();
       const entry = requireIndex(indexName);
       const manager = requireManager(indexName);
-      const resolvedParams = await resolveVectorText(params, entry.embeddingAdapter, abortController.signal);
+      const resolvedParams = await resolveVectorText(
+        params,
+        entry.embeddingAdapter,
+        abortController.signal,
+        entry.embeddingAdapterName
+      );
       const workerSearch = orchestrator.isPromoted() ? orchestrator.searchViaWorker.bind(orchestrator) : void 0;
       return executePreflight(resolvedParams, {
         manager,