@delali/narsil 0.1.8 → 0.1.10

package/dist/{chunk-GQEHCZG7.mjs → chunk-CU6BVZEU.mjs}

@@ -1,4 +1,4 @@
-import { getNestedValue, getLanguage, extractVectorFieldsFromSchema, createDirectExecutor, createPartitionRouter, validateSchema, createPartitionManager, createVectorIndex, deserializePayloadV2, tokenize, fanOutQuery, validateRequiredFields, flattenSchema, createPartitionIndex, fnv1a, detectRuntime, kWayMerge } from './chunk-FS7XLIUS.mjs';
+import { getNestedValue, getLanguage, extractVectorFieldsFromSchema, createDirectExecutor, createPartitionRouter, createPartitionManager, createVectorIndex, validateSchema, deserializePayloadV2, tokenize, fanOutQuery, validateRequiredFields, validateVectorPromotion, createPartitionIndex, flattenSchema, fnv1a, detectRuntime, isNodeMainThread, spawnNodeWorker, kWayMerge } from './chunk-Q4OVNESD.mjs';
 import { crc32, crc32Init, crc32Update, crc32Final } from './chunk-KMMJMDUA.mjs';
 import { ErrorCodes, NarsilError } from './chunk-ALB35PRQ.mjs';
 import { generateId, createRequestId, isValidWorkerResponse } from './chunk-HRABJLPB.mjs';
@@ -132,6 +132,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/workers/promoter.ts
 var DEFAULT_PER_INDEX_THRESHOLD = 1e4;
 var DEFAULT_TOTAL_THRESHOLD = 5e4;
@@ -170,7 +287,7 @@ function createExecutionPromoter(config) {
   return { check, markPromoted, isPromoted };
 }
 
-// src/persistence/durability/durable-filesystem.ts
+// src/persistence/durability/node-fs.ts
 var cachedFs = null;
 var cachedPath = null;
 async function getFs() {
@@ -185,6 +302,8 @@ async function getPath() {
   }
   return cachedPath;
 }
+
+// src/persistence/durability/durable-filesystem.ts
 function validateRelativeKey(key) {
   if (key.length === 0) {
     throw new NarsilError(ErrorCodes.PERSISTENCE_SAVE_FAILED, "Invalid key: empty");
@@ -452,12 +571,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;
@@ -472,8 +586,7 @@ function resolveWorkerEntryPoint() {
 }
 async function spawnWorker() {
   try {
-    const workerThreads = await import('worker_threads');
-    return new workerThreads.Worker(new URL(resolveWorkerEntryPoint()));
+    return await spawnNodeWorker(new URL(resolveWorkerEntryPoint()));
   } catch {
     return null;
   }
@@ -739,6 +852,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) {
@@ -754,6 +870,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) {
@@ -1146,8 +1265,10 @@ function resolveWorkerEntryPoint2() {
 }
 async function spawnWorker2() {
   try {
-    const workerThreads = await import('worker_threads');
-    const worker = new workerThreads.Worker(new URL(resolveWorkerEntryPoint2()));
+    const worker = await spawnNodeWorker(new URL(resolveWorkerEntryPoint2()));
+    if (worker === null) {
+      return null;
+    }
     if (typeof worker.unref === "function") {
       worker.unref();
     }
@@ -2115,11 +2236,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
@@ -3693,7 +3818,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,
@@ -3702,6 +3827,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 = {
@@ -4211,11 +4340,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,
@@ -4234,6 +4368,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();
@@ -4283,11 +4424,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)
     });
   }
@@ -4330,6 +4495,7 @@ function createEngineCore(config) {
     durability,
     idGenerator,
     indexRegistry,
+    embeddingAdapters,
     eventHandlers,
     shutdownState,
     abortController,
@@ -4347,285 +4513,50 @@ function createEngineCore(config) {
     rebalanceCtx
   };
 }
-
-// src/engine/lifecycle.ts
-async function shutdownEngine(core) {
-  const { executor, durability, indexRegistry, eventHandlers, orchestrator } = core;
-  for (const [name] of indexRegistry) {
-    const manager = executor.getManager(name);
-    if (manager) {
-      for (const [, vectorIndex] of manager.getVectorIndexes()) {
-        vectorIndex.dispose();
-      }
-    }
-  }
-  if (durability) {
-    await durability.manager.shutdown();
-  }
-  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 {
-    }
+var INDEX_CONFIG_PREFIX = "_narsil/index/";
+var INDEX_CONFIG_SUFFIX = "/config";
+var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var MAX_INDEX_NAME_LENGTH = 255;
+var MAX_PARTITION_COUNT = 65536;
+var MAX_REPLICATION_FACTOR = 255;
+function truncateForDisplay(value) {
+  const str = String(value);
+  if (str.length > 100) {
+    return `${str.slice(0, 100)}...`;
   }
-  await orchestrator.shutdown();
-  await executor.shutdown();
-  eventHandlers.clear();
-  indexRegistry.clear();
+  return str;
 }
-
-// src/engine/embed.ts
-function validateVector(vector, targetField, expectedDimensions) {
-  if (!(vector instanceof Float32Array)) {
+function validateIndexName(indexName) {
+  if (indexName.length === 0 || indexName.length > MAX_INDEX_NAME_LENGTH) {
     throw new NarsilError(
-      ErrorCodes.EMBEDDING_FAILED,
-      `Adapter returned ${typeof vector} for field "${targetField}", expected Float32Array`,
-      { field: targetField, returnedType: typeof vector }
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index name must be between 1 and ${MAX_INDEX_NAME_LENGTH} characters`,
+      { indexName: truncateForDisplay(indexName) }
     );
   }
-  if (vector.length !== expectedDimensions) {
+  if (indexName.includes("\0") || indexName.includes("/") || indexName.includes("\\") || indexName.includes("..")) {
     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 }
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      "Index name contains forbidden characters (/, \\, .., or null bytes)",
+      { indexName: truncateForDisplay(indexName) }
     );
   }
-  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 }
-      );
-    }
+  if (!INDEX_NAME_PATTERN.test(indexName)) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      "Index name must start with an alphanumeric character and contain only alphanumeric characters, hyphens, underscores, or dots",
+      { indexName: truncateForDisplay(indexName) }
+    );
   }
-  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 isValidInteger(value) {
+  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value);
 }
-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 indexConfigKey(indexName) {
+  return `${INDEX_CONFIG_PREFIX}${indexName}${INDEX_CONFIG_SUFFIX}`;
 }
-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 };
-}
-var INDEX_CONFIG_PREFIX = "_narsil/index/";
-var INDEX_CONFIG_SUFFIX = "/config";
-var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-var MAX_INDEX_NAME_LENGTH = 255;
-var MAX_PARTITION_COUNT = 65536;
-var MAX_REPLICATION_FACTOR = 255;
-function truncateForDisplay(value) {
-  const str = String(value);
-  if (str.length > 100) {
-    return `${str.slice(0, 100)}...`;
-  }
-  return str;
-}
-function validateIndexName(indexName) {
-  if (indexName.length === 0 || indexName.length > MAX_INDEX_NAME_LENGTH) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index name must be between 1 and ${MAX_INDEX_NAME_LENGTH} characters`,
-      { indexName: truncateForDisplay(indexName) }
-    );
-  }
-  if (indexName.includes("\0") || indexName.includes("/") || indexName.includes("\\") || indexName.includes("..")) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      "Index name contains forbidden characters (/, \\, .., or null bytes)",
-      { indexName: truncateForDisplay(indexName) }
-    );
-  }
-  if (!INDEX_NAME_PATTERN.test(indexName)) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      "Index name must start with an alphanumeric character and contain only alphanumeric characters, hyphens, underscores, or dots",
-      { indexName: truncateForDisplay(indexName) }
-    );
-  }
-}
-function isValidInteger(value) {
-  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value);
-}
-function indexConfigKey(indexName) {
-  return `${INDEX_CONFIG_PREFIX}${indexName}${INDEX_CONFIG_SUFFIX}`;
-}
-function isRecord2(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function validateDecodedMetadata(decoded, indexName) {
   if (!isRecord2(decoded)) {
@@ -4743,27 +4674,361 @@ 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) {
+  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();
+  validateIndexName2(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) {
+  const { executor, durability, indexRegistry, eventHandlers, orchestrator } = core;
+  for (const [name] of indexRegistry) {
+    const manager = executor.getManager(name);
+    if (manager) {
+      for (const [, vectorIndex] of manager.getVectorIndexes()) {
+        vectorIndex.dispose();
+      }
+    }
+  }
+  if (durability) {
+    await durability.manager.shutdown();
+  }
+  const adaptersToShutdown = /* @__PURE__ */ new Set();
+  for (const [, entry] of indexRegistry) {
+    if (entry.embeddingAdapter?.shutdown) {
+      adaptersToShutdown.add(entry.embeddingAdapter);
+    }
+  }
+  for (const adapter of adaptersToShutdown) {
+    try {
+      await adapter.shutdown?.();
+    } catch {
+    }
+  }
+  await orchestrator.shutdown();
+  await executor.shutdown();
+  eventHandlers.clear();
+  indexRegistry.clear();
+}
+
+// src/engine/embed.ts
+function assertDocumentCarriesMappedVectors(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 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.DOC_VALIDATION_FAILED,
-      `Document ID must not exceed ${MAX_DOC_ID_LENGTH} characters`,
-      {
-        docId,
-        length: docId.length
-      }
+      ErrorCodes.EMBEDDING_NO_SOURCE,
+      `All source fields for embedding target "${targetField}" are missing or empty`,
+      details
     );
   }
-  if (docId.includes("\0")) {
-    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not contain null bytes", { docId });
+  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;
 }
-function clampLimit(limit) {
-  if (limit === void 0) return DEFAULT_LIMIT;
-  return Math.max(0, Math.min(limit, MAX_LIMIT));
+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);
 }
-function clampOffset(offset) {
-  if (offset === void 0) return DEFAULT_OFFSET;
-  return Math.max(0, Math.min(offset, MAX_OFFSET));
+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/mutations/durable-rollback.ts
@@ -4827,13 +5092,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();
@@ -4913,6 +5186,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();
@@ -4928,7 +5202,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))
           });
         }
@@ -4953,16 +5227,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;
@@ -5156,13 +5447,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);
@@ -6212,7 +6511,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;
@@ -6222,7 +6521,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") {
@@ -6304,7 +6604,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) {
@@ -6435,97 +6741,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);
@@ -6552,43 +6767,14 @@ function createNarsilFromCore(core, config) {
     rebalanceCtx
   } = core;
   const narsil = {
-    async createIndex(name, indexConfig) {
-      guardShutdown();
-      validateIndexName2(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 = [];
@@ -6667,7 +6853,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, {
@@ -6692,7 +6883,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,