@delali/narsil 0.2.4-next.55 → 0.3.0

package/dist/{chunk-BH5SYB5W.mjs → chunk-24RXHMEL.mjs}

@@ -1,19 +1,110 @@
 import { ReplicationMessageTypes } from './chunk-GCM3JFVA.mjs';
-import { WIRE_BATCH_BUDGET, resolveVectorText, bindEngineCore, collectRequiredFieldFailures, embedChunkDocuments, providedDocId, admitInsert, asBatchInsertError, embedDocumentFields, assertDocumentCarriesMappedVectors } from './chunk-4NVPQ6S5.mjs';
-import { getNestedValue, generateId, getLanguage, splitWorkerBudget, resolveWorkerCount, createDirectExecutor, createPartitionRouter, createCompositePartition, deserializePayloadV2, createSharedFrozenSegment, createPartitionManager, buildSegmentPayload, resolvePartitionInsertOptions, readHeapStatistics, resolveIndexAnalysis, deserializePayloadV1, decodeVectorIndexParts, resolveRequestThreadCount, createPartitionIndex, VECTOR_FILE_MAX_VECTORS, deadBytesFor, mergeFrozenSegments, isCompositePartition, workerResourceLimits, deserializeMetadata, isNodeMainThread, spawnNodeWorker, freezeSegmentShared, DEFAULT_BACKPRESSURE_LIMIT, DEFAULT_REQUEST_TIMEOUT_MS, serializeMetadata, SHUTDOWN_TIMEOUT_MS, encodeSegmentState, CONSECUTIVE_TIMEOUTS_BEFORE_DEATH, decodeVectorFilePayload, documentsOfPayloadV2, countDead, decodeVectorGraphPayload, deadBitsWhere, NO_LIVE_VECTOR_AT_POSITION, createFrozenSegment } from './chunk-XNQAIO74.mjs';
+import { WIRE_BATCH_BUDGET, resolveVectorText, bindEngineCore, collectRequiredFieldFailures, embedChunkDocuments, providedDocId, admitInsert, asBatchInsertError, embedDocumentFields, assertDocumentCarriesMappedVectors } from './chunk-UXNWQZST.mjs';
+import { generateId, getLanguage, splitWorkerBudget, resolveWorkerCount, createDirectExecutor, createPartitionRouter, createCompositePartition, deserializePayloadV2, createSharedFrozenSegment, createPartitionManager, buildSegmentPayload, resolvePartitionInsertOptions, resolveWorkerEntry, missingWorkerEntry, readHeapStatistics, resolveIndexAnalysis, deserializePayloadV1, decodeVectorIndexParts, nodeThreadId, resolveRequestThreadCount, createPartitionIndex, VECTOR_FILE_MAX_VECTORS, deadBytesFor, mergeFrozenSegments, isCompositePartition, workerResourceLimits, deserializeMetadata, isNodeMainThread, spawnNodeWorker, freezeSegmentShared, DEFAULT_BACKPRESSURE_LIMIT, DEFAULT_REQUEST_TIMEOUT_MS, SHUTDOWN_TIMEOUT_MS, serializeMetadata, encodeSegmentState, CONSECUTIVE_TIMEOUTS_BEFORE_DEATH, decodeVectorFilePayload, documentsOfPayloadV2, countDead, decodeVectorGraphPayload, deadBitsWhere, NO_LIVE_VECTOR_AT_POSITION, createFrozenSegment } from './chunk-ZZT3EAUC.mjs';
 import { detectRuntime } from './chunk-AV4IJKD2.mjs';
-import { validateWorkerConfig, validateIndexName, validateBM25Params, validatePartitionConfig, executeQuery, queryBindingOf, executePreflight, executeSuggest, executeListDocuments, validateDocId } from './chunk-TVT5V4E7.mjs';
-import { BATCH_CHUNK_SIZE, STATISTICS_BROADCAST_INTERVAL_MS, MAX_SWEEP_INTERVAL_MS, MIN_SWEEP_INTERVAL_MS, HEAP_PRESSURE_WARNING_FRACTION, FOREIGN_STATS_TTL_MS, MIN_DOCUMENTS_FOR_SEGMENTS, HEAP_PRESSURE_REARM_FRACTION } from './chunk-D2S642IV.mjs';
-import { collectQueryTermStats, mergePartitionStats, fnv1a, kWayMerge, mergeFacets } from './chunk-5T6AOR37.mjs';
-import { extractVectorFieldsFromSchema, validateSchema, validateVectorPromotion, validateVectorStorage, flattenSchema, isTextFieldType, validateRequiredFields, validateDocument, validateDocumentStrict } from './chunk-L225SHNB.mjs';
-import { releaseLocksHeldBy } from './chunk-U2AL3SON.mjs';
+import { validateWorkerConfig, validateIndexName, validateBM25Params, validatePartitionConfig, executeQuery, queryBindingOf, executePreflight, executeSuggest, executeListDocuments, validateDocId } from './chunk-B2TFROFX.mjs';
+import { BATCH_CHUNK_SIZE, STATISTICS_BROADCAST_INTERVAL_MS, MAX_SWEEP_INTERVAL_MS, MIN_SWEEP_INTERVAL_MS, HEAP_PRESSURE_WARNING_FRACTION, FOREIGN_STATS_TTL_MS, MIN_DOCUMENTS_FOR_SEGMENTS, HEAP_PRESSURE_REARM_FRACTION } from './chunk-3LHGNRYE.mjs';
+import { getNestedValue, collectQueryTermStats, mergePartitionStats, oversampledFacetConfig, fnv1a, kWayMerge, mergeFacets } from './chunk-ZNZBXMP5.mjs';
+import { extractVectorFieldsFromSchema, validateSchema, validateVectorPromotion, validateVectorStorage, flattenSchema, isTextFieldType, validateRequiredFields, validateDocument, validateDocumentStrict } from './chunk-L6TNPLAR.mjs';
+import { releaseLocksHeldBy } from './chunk-THYRHHO2.mjs';
+import { requireSearchBackendSettings } from './chunk-YNVIUGF5.mjs';
 import { crc32, nativeCrc32, crc32Final, crc32Init, crc32Update } from './chunk-3L4U6EJQ.mjs';
 import { CHECKSUM_TIMEOUT_MS, CHECKSUM_YIELD_CHUNK_BYTES } from './chunk-IFBKLBGB.mjs';
-import { compareCodePoints } from './chunk-2GWVQWGA.mjs';
+import { compareCodePoints } from './chunk-YMZCMH5M.mjs';
 import { createRequestId, isValidWorkerResponse, threadSlotOfWorker } from './chunk-POWOTUKJ.mjs';
-import { NarsilError, ErrorCodes } from './chunk-FRQVMFY7.mjs';
+import { NarsilError, ErrorCodes } from './chunk-USKFU7J5.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
+// src/engine/config-keys.ts
+var NARSIL_CONFIG_KEYS = {
+  persistence: true,
+  invalidation: true,
+  plugins: true,
+  idGenerator: true,
+  workers: true,
+  embedding: true,
+  embeddingAdapters: true,
+  durability: true,
+  analysis: true,
+  lifecycle: true
+};
+var DURABILITY_CONFIG_KEYS = {
+  tier: true,
+  directory: true,
+  mode: true,
+  flushIntervalMs: true,
+  segmentMaxBytes: true,
+  checkpointIntervalMs: true,
+  checkpointMutationThreshold: true,
+  compactionThreshold: true
+};
+var WORKER_CONFIG_KEYS = {
+  enabled: true,
+  count: true,
+  promotionThreshold: true,
+  idleTimeoutMs: true,
+  mainCopyQueries: true,
+  bootstrapModule: true
+};
+var LIFECYCLE_CONFIG_KEYS = {
+  idleTimeoutMs: true,
+  maxOpenIndexes: true,
+  maxOpenBytes: true,
+  maxReopenWaiters: true
+};
+var ANALYSIS_CONFIG_KEYS = {
+  rebuild: true,
+  onStaleAnalysis: true
+};
+function requireKnownKeys(section, value, known) {
+  if (value === void 0 || value === null || typeof value !== "object") return;
+  for (const key of Object.keys(value)) {
+    if (Object.hasOwn(known, key)) continue;
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      `The configuration sets "${section}${key}", which is no setting that createNarsil accepts. The settings at that level are ${Object.keys(known).join(", ")}`,
+      { setting: `${section}${key}`, settings: Object.keys(known) }
+    );
+  }
+}
+function requireNamedPlugins(plugins) {
+  if (plugins === void 0) return;
+  if (!Array.isArray(plugins)) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, 'The configuration sets "plugins" to something other than a list');
+  }
+  plugins.forEach((plugin, position) => {
+    const name = plugin?.name;
+    if (typeof name !== "string" || name.trim().length === 0) {
+      throw new NarsilError(
+        ErrorCodes.CONFIG_INVALID,
+        `The plugin at position ${position} carries no name, and the engine names each plugin in its errors and event payloads`,
+        { position }
+      );
+    }
+  });
+}
+function requireKnownConfig(config) {
+  if (config === void 0) return;
+  requireKnownKeys("", config, NARSIL_CONFIG_KEYS);
+  requireKnownKeys("durability.", config.durability, DURABILITY_CONFIG_KEYS);
+  requireKnownKeys("workers.", config.workers, WORKER_CONFIG_KEYS);
+  requireKnownKeys("lifecycle.", config.lifecycle, LIFECYCLE_CONFIG_KEYS);
+  requireKnownKeys("analysis.", config.analysis, ANALYSIS_CONFIG_KEYS);
+  requireNamedPlugins(config.plugins);
+}
+
+// src/engine/orchestration/turn.ts
+function afterCurrentTurn(callback) {
+  if (typeof setImmediate === "function") {
+    setImmediate(callback);
+    return;
+  }
+  setTimeout(callback, 0);
+}
+function yieldToEventLoop() {
+  return new Promise((resolve) => afterCurrentTurn(resolve));
+}
+
 // src/partitioning/constants.ts
 var REBALANCE_CHUNK_SIZE = 1e3;
 var DEFAULT_WRITE_AHEAD_QUEUE_MAX_SIZE = 1e4;
@@ -88,7 +179,7 @@ function createRebalancer() {
               documentsProcessed,
               documentsTotal
             });
-            await new Promise((resolve) => setTimeout(resolve, 0));
+            await yieldToEventLoop();
           }
         }
       }
@@ -98,7 +189,7 @@ function createRebalancer() {
           documentsProcessed,
           documentsTotal
         });
-        await new Promise((resolve) => setTimeout(resolve, 0));
+        await yieldToEventLoop();
       }
       onProgress?.({
         phase: "swapping",
@@ -125,13 +216,43 @@ function createRebalancer() {
 }
 
 // src/plugins/registry.ts
+var WRITE_REJECTING_HOOKS = /* @__PURE__ */ new Set(["beforeInsert", "beforeUpdate", "beforeRemove"]);
 function isThenable(value) {
   return value !== null && typeof value === "object" && typeof value.then === "function";
 }
-async function continueAsync(pending, hooks, startIndex, context) {
+function thrownText(err, plugin, hookName) {
+  if (err instanceof Error) return err.message;
+  try {
+    return String(err);
+  } catch {
+    return `The ${hookName} hook of plugin "${plugin}" rejects the write`;
+  }
+}
+function asWriteRejection(err, plugin, hookName) {
+  if (err instanceof NarsilError) return err;
+  return new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, thrownText(err, plugin, hookName), {
+    plugin,
+    hook: hookName
+  });
+}
+function invoke(hook, hookName, context) {
+  const rejectsWrites = WRITE_REJECTING_HOOKS.has(hookName);
+  let result;
+  try {
+    result = hook.run(context);
+  } catch (err) {
+    throw rejectsWrites ? asWriteRejection(err, hook.plugin, hookName) : err;
+  }
+  if (!isThenable(result)) return null;
+  if (!rejectsWrites) return result;
+  return Promise.resolve(result).catch((err) => {
+    throw asWriteRejection(err, hook.plugin, hookName);
+  });
+}
+async function continueAsync(pending, hooks, startIndex, hookName, context) {
   await pending;
   for (let i = startIndex; i < hooks.length; i++) {
-    await hooks[i](context);
+    await invoke(hooks[i], hookName, context);
   }
 }
 function createPluginRegistry() {
@@ -148,14 +269,14 @@ function createPluginRegistry() {
       for (const plugin of plugins) {
         const hook = plugin[hookName];
         if (typeof hook === "function") {
-          hooks.push(hook.bind(plugin));
+          hooks.push({ plugin: plugin.name, run: hook.bind(plugin) });
         }
       }
       if (hooks.length === 0) return;
       for (let i = 0; i < hooks.length; i++) {
-        const result = hooks[i](context);
-        if (isThenable(result)) {
-          return continueAsync(result, hooks, i + 1, context);
+        const pending = invoke(hooks[i], hookName, context);
+        if (pending !== null) {
+          return continueAsync(pending, hooks, i + 1, hookName, context);
         }
       }
     }
@@ -294,7 +415,7 @@ function emitEngineEvent(eventHandlers, event, payload) {
 }
 
 // src/engine/analysis-rebuild.ts
-function yieldToEventLoop() {
+function yieldToEventLoop2() {
   return new Promise((resolve) => {
     setTimeout(resolve, 0);
   });
@@ -335,7 +456,7 @@ function createAnalysisRebuildCoordinator(config, deps) {
       for (let partitionId = 0; partitionId < manager.partitionCount; partitionId += 1) {
         manager.rebuildTextIndex(partitionId);
         entry.partitionsRebuilt = partitionId + 1;
-        await yieldToEventLoop();
+        await yieldToEventLoop2();
       }
       stale.delete(indexName);
       await deps.persistAnalysisRevision(indexName);
@@ -514,6 +635,10 @@ function resolveDurabilityTier(config) {
 var DEFAULT_CHECKPOINT_INTERVAL_MS = 3e5;
 var DEFAULT_CHECKPOINT_MUTATION_THRESHOLD = 1e5;
 var DEFAULT_ASYNC_FLUSH_INTERVAL_MS = 1e3;
+var DIRECTORY_IDENTITY_CHECK_INTERVAL_MS = 1e3;
+var DIRECTORY_LOCK_ATTEMPTS = 3;
+var DIRECTORY_LOCK_SETTLE_MS = 50;
+var DIRECTORY_LOCK_PROCESS_START_TOLERANCE_MS = 1e3;
 var DEFAULT_SEGMENT_MAX_BYTES = 67108864;
 var DEFAULT_COMPACTION_THRESHOLD = 12;
 var COMPACTION_LARGEST_MERGED_DOCUMENT_COUNT = 2e5;
@@ -542,6 +667,163 @@ async function getPath() {
   return cachedPath;
 }
 
+// src/persistence/durability/directory-lock.ts
+var LOCK_FILE_NAME = ".narsil.lock";
+var HARD_LINK_UNSUPPORTED_CODES = /* @__PURE__ */ new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+var lockedDirectories = /* @__PURE__ */ new Set();
+function errnoOf(err) {
+  return err?.code;
+}
+function processIsRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return errnoOf(err) === "EPERM";
+  }
+}
+function integerOrNull(text) {
+  const value = Number.parseInt(text ?? "", 10);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function parseHolder(text) {
+  const [pidText, threadText, startText, nonceText] = text.split("\n");
+  const pid = integerOrNull(pidText);
+  if (pid === null || pid <= 0) return null;
+  const nonce = nonceText?.trim() ?? "";
+  return {
+    pid,
+    threadId: integerOrNull(threadText),
+    processStartMs: integerOrNull(startText),
+    nonce: nonce.length > 0 ? nonce : null
+  };
+}
+function formatHolder(holder) {
+  return `${holder.pid}
+${holder.threadId ?? ""}
+${holder.processStartMs ?? ""}
+${holder.nonce ?? ""}
+`;
+}
+async function readHolder(fs, lockPath) {
+  try {
+    return parseHolder(await fs.readFile(lockPath, "utf8")) ?? "unreadable";
+  } catch (err) {
+    if (errnoOf(err) === "ENOENT") return "absent";
+    throw err;
+  }
+}
+async function settledHolder(fs, lockPath) {
+  const first = await readHolder(fs, lockPath);
+  if (first !== "unreadable") return first;
+  await new Promise((resolve) => setTimeout(resolve, DIRECTORY_LOCK_SETTLE_MS));
+  return readHolder(fs, lockPath);
+}
+function holderIsLive(holder, self) {
+  if (holder.pid !== self.pid) return processIsRunning(holder.pid);
+  if (holder.processStartMs === null || self.processStartMs === null) return false;
+  return Math.abs(holder.processStartMs - self.processStartMs) <= DIRECTORY_LOCK_PROCESS_START_TOLERANCE_MS;
+}
+function heldElsewhere(root, holder, lockPath) {
+  return new NarsilError(
+    ErrorCodes.CONFIG_INVALID,
+    `The durability directory "${root}" is in use by ${holder}, and only one engine may write a write-ahead log directory. Point this engine at another directory, or shut the other engine down first. Where no engine uses the directory, delete "${lockPath}"`,
+    { directory: root }
+  );
+}
+function holderLabel(holder, self) {
+  if (holder.pid !== self.pid) return `process ${holder.pid}`;
+  return holder.threadId === self.threadId ? "another copy of Narsil in this thread" : "another thread of this process";
+}
+async function createLockFileExclusively(fs, lockPath, content) {
+  try {
+    await fs.writeFile(lockPath, content, { flag: "wx" });
+    return true;
+  } catch (err) {
+    if (errnoOf(err) === "EEXIST") return false;
+    throw err;
+  }
+}
+async function createLockFile(fs, lockPath, draftPath, content) {
+  await fs.writeFile(draftPath, content, { flag: "w" });
+  try {
+    await fs.link(draftPath, lockPath);
+    return true;
+  } catch (err) {
+    const code = errnoOf(err);
+    if (code === "EEXIST") return false;
+    if (code !== void 0 && HARD_LINK_UNSUPPORTED_CODES.has(code)) {
+      return createLockFileExclusively(fs, lockPath, content);
+    }
+    throw err;
+  } finally {
+    await fs.unlink(draftPath).catch(() => void 0);
+  }
+}
+async function acquire(fs, root, lockPath, self) {
+  const draftPath = `${lockPath}.${self.pid}.${self.threadId ?? 0}`;
+  const content = formatHolder(self);
+  for (let attempt = 0; attempt < DIRECTORY_LOCK_ATTEMPTS; attempt++) {
+    if (await createLockFile(fs, lockPath, draftPath, content)) return;
+    const holder = await settledHolder(fs, lockPath);
+    if (typeof holder === "object" && holderIsLive(holder, self)) {
+      throw heldElsewhere(root, holderLabel(holder, self), lockPath);
+    }
+    await fs.unlink(lockPath).catch((err) => {
+      if (errnoOf(err) !== "ENOENT") throw err;
+    });
+  }
+  throw heldElsewhere(root, "another process", lockPath);
+}
+async function describeSelf() {
+  return {
+    pid: process.pid,
+    threadId: await nodeThreadId(),
+    processStartMs: Math.round(Date.now() - process.uptime() * 1e3),
+    nonce: globalThis.crypto.randomUUID()
+  };
+}
+async function lockDirectory(root) {
+  const fs = await getFs();
+  const pathMod = await getPath();
+  const resolvedRoot = pathMod.resolve(root);
+  const lockPath = pathMod.join(resolvedRoot, LOCK_FILE_NAME);
+  const self = await describeSelf();
+  let directoryKey = null;
+  try {
+    await fs.mkdir(resolvedRoot, { recursive: true });
+    const stat = await fs.stat(resolvedRoot, { bigint: true });
+    const key = `${stat.dev}:${stat.ino}`;
+    if (lockedDirectories.has(key)) throw heldElsewhere(root, "another engine in this process", lockPath);
+    lockedDirectories.add(key);
+    directoryKey = key;
+    await acquire(fs, root, lockPath, self);
+  } catch (err) {
+    if (directoryKey !== null) lockedDirectories.delete(directoryKey);
+    if (err instanceof NarsilError) throw err;
+    throw new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The engine cannot lock the durability directory "${root}"`,
+      { directory: root, cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const heldKey = directoryKey;
+  let released = false;
+  async function holds() {
+    const holder = await readHolder(fs, lockPath);
+    return typeof holder === "object" && holder.nonce === self.nonce;
+  }
+  return {
+    holds,
+    async release() {
+      if (released) return;
+      released = true;
+      lockedDirectories.delete(heldKey);
+      if (await holds().catch(() => false)) await fs.unlink(lockPath).catch(() => void 0);
+    }
+  };
+}
+
 // src/persistence/durability/durable-filesystem.ts
 function validateRelativeKey(key) {
   if (key.length === 0) {
@@ -627,6 +909,20 @@ function createDurableDirectory(root) {
     get root() {
       return root;
     },
+    lock() {
+      return lockDirectory(root);
+    },
+    async identity() {
+      const fs = await getFs();
+      const pathMod = await getPath();
+      try {
+        const stat = await fs.stat(pathMod.resolve(root), { bigint: true });
+        return `${stat.dev}:${stat.ino}`;
+      } catch (err) {
+        if (err.code === "ENOENT") return null;
+        throw err;
+      }
+    },
     async appendHandle(key) {
       const { path: filePath, pathMod } = await resolve(key);
       const fs = await getFs();
@@ -817,22 +1113,20 @@ async function isOnMainThread() {
   }
   return onMainThread;
 }
-function resolveWorkerEntryPoint() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("serialization/crc32-worker.mjs", base.slice(0, distIndex + 6)).href;
-  }
-  return base.replace(/\/src\/serialization\/[^/]+$/, "/dist/serialization/crc32-worker.mjs");
-}
 async function spawnWorker() {
+  const entryPoint = resolveWorkerEntry(
+    import.meta.url,
+    /\/src\/serialization\/[^/]+$/,
+    "serialization/crc32-worker.mjs"
+  );
+  if (entryPoint === null) return null;
   try {
-    return await spawnNodeWorker(new URL(resolveWorkerEntryPoint()));
+    return await spawnNodeWorker(new URL(entryPoint));
   } catch {
     return null;
   }
 }
-function yieldToEventLoop2() {
+function yieldToEventLoop3() {
   if (typeof setImmediate === "function") {
     return new Promise((resolve) => setImmediate(resolve));
   }
@@ -844,7 +1138,7 @@ async function advanceChecksum(start, payload) {
     const end = Math.min(offset + CHECKSUM_YIELD_CHUNK_BYTES, payload.length);
     state = crc32Update(state, payload.subarray(offset, end));
     if (end < payload.length) {
-      await yieldToEventLoop2();
+      await yieldToEventLoop3();
     }
   }
   return state;
@@ -2132,7 +2426,7 @@ function attachDocuments(manager, partitionId, segment) {
   }
   manager.attachFrozenSegment(partitionId, createSharedFrozenSegment(snapshot));
 }
-function yieldToEventLoop3() {
+function yieldToEventLoop4() {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
 async function loadPartitionSegmentBySegment(directory, partition, manager) {
@@ -2142,7 +2436,7 @@ async function loadPartitionSegmentBySegment(directory, partition, manager) {
     addSegmentSchema(agreedSchema, segment.schema);
     removeWhatTheSegmentReplaces(manager, segment);
     attachDocuments(manager, partition.partitionId, segment);
-    await yieldToEventLoop3();
+    await yieldToEventLoop4();
   }
 }
 
@@ -3807,17 +4101,15 @@ var workerBusy = false;
 var spawnedWorkerCount = 0;
 var workerIdleMs = CHECKPOINT_WORKER_IDLE_MS;
 var idleTimer = null;
-function resolveWorkerEntryPoint2() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("persistence/durability/checkpoint-worker.mjs", base.slice(0, distIndex + 6)).href;
-  }
-  return base.replace(/\/src\/persistence\/durability\/[^/]+$/, "/dist/persistence/durability/checkpoint-worker.mjs");
-}
 async function spawnWorker2() {
+  const entryPoint = resolveWorkerEntry(
+    import.meta.url,
+    /\/src\/persistence\/durability\/[^/]+$/,
+    "persistence/durability/checkpoint-worker.mjs"
+  );
+  if (entryPoint === null) return null;
   try {
-    const worker = await spawnNodeWorker(new URL(resolveWorkerEntryPoint2()));
+    const worker = await spawnNodeWorker(new URL(entryPoint));
     if (worker === null) {
       return null;
     }
@@ -4048,11 +4340,29 @@ async function garbageThatNoFieldStillReads(directory, vectorIndexes, keys) {
   return unread;
 }
 async function runDurableCheckpoint(input) {
-  let recordsLeftInLog = await writeOneBoundedCheckpoint(input);
-  while (recordsLeftInLog > 0 && input.mayContinue()) {
-    recordsLeftInLog = await writeOneBoundedCheckpoint(input);
+  try {
+    let recordsLeftInLog = await writeOneBoundedCheckpoint(input);
+    while (recordsLeftInLog > 0 && input.mayContinue()) {
+      recordsLeftInLog = await writeOneBoundedCheckpoint(input);
+    }
+  } catch (err) {
+    if (!isSystemError(err)) throw err;
+    const error = new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The engine cannot write the checkpoint of index "${input.indexName}" to the durability directory "${input.directory.root}"`,
+      {
+        indexName: input.indexName,
+        directory: input.directory.root,
+        cause: err.message
+      }
+    );
+    input.markFatal(error);
+    throw error;
   }
 }
+function isSystemError(err) {
+  return err instanceof Error && !(err instanceof NarsilError) && typeof err.code === "string";
+}
 async function writeOneBoundedCheckpoint(input) {
   const manager = input.hooks.getManager(input.indexName);
   if (manager === void 0) {
@@ -4132,6 +4442,94 @@ function recordsBeyond(indexState, targets) {
   return records;
 }
 
+// src/persistence/durability/directory-watch.ts
+function unrefInterval(tick, intervalMs) {
+  const timer = setInterval(tick, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return timer;
+}
+function createDirectoryWatch(directory, isStopped, onLost) {
+  let expected = null;
+  let timer = null;
+  let lock = null;
+  function cannotCheck(err) {
+    return new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The engine cannot check the durability directory "${directory.root}", so it cannot confirm that a write is durable`,
+      { directory: directory.root, cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  async function currentIdentity() {
+    try {
+      return await directory.identity?.() ?? null;
+    } catch (err) {
+      return cannotCheck(err);
+    }
+  }
+  async function lockTakenOver() {
+    if (lock === null) return null;
+    try {
+      if (await lock.holds()) return null;
+    } catch (err) {
+      return cannotCheck(err);
+    }
+    return new NarsilError(
+      ErrorCodes.PERSISTENCE_SAVE_FAILED,
+      `The lock file of the durability directory "${directory.root}" records another engine, which may be writing the same log`,
+      { directory: directory.root }
+    );
+  }
+  async function verify() {
+    if (directory.identity === void 0 || isStopped()) return true;
+    const current = await currentIdentity();
+    if (current instanceof Error) {
+      onLost(current);
+      return false;
+    }
+    if (expected === null) {
+      expected = current;
+    } else if (current !== expected) {
+      onLost(
+        new NarsilError(
+          ErrorCodes.PERSISTENCE_SAVE_FAILED,
+          `The durability directory "${directory.root}" is missing or is a different directory from the one that this instance opens at start-up, so a write to it is not durable`,
+          { directory: directory.root }
+        )
+      );
+      return false;
+    }
+    const takenOver = await lockTakenOver();
+    if (takenOver === null) return true;
+    onLost(takenOver);
+    return false;
+  }
+  function stop() {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+  return {
+    async claim() {
+      if (lock === null && directory.lock !== void 0) lock = await directory.lock();
+    },
+    async release() {
+      const held = lock;
+      lock = null;
+      await held?.release();
+    },
+    verify,
+    async verifyOnce() {
+      if (expected === null && directory.identity !== void 0) await verify();
+    },
+    start() {
+      if (directory.identity === void 0 || timer !== null || isStopped()) return;
+      timer = unrefInterval(() => void verify(), DIRECTORY_IDENTITY_CHECK_INTERVAL_MS);
+    },
+    stop
+  };
+}
+
 // src/persistence/durability/manager-state.ts
 async function drainIndexStateForUnload(indexState, pendingMetadataWrite, closeWalWriter) {
   indexState.unloading = true;
@@ -4604,11 +5002,13 @@ function createDurabilityManager(config, hooks, directoryOverride) {
   let asyncFlushTimer = null;
   let shuttingDown = false;
   let fatalError = null;
+  const directoryWatch = createDirectoryWatch(directory, () => shuttingDown || fatalError !== null, markFatal);
   function markFatal(error) {
     if (fatalError !== null) {
       return;
     }
     fatalError = error;
+    directoryWatch.stop();
     if (checkpointTimer !== null) {
       clearInterval(checkpointTimer);
       checkpointTimer = null;
@@ -4672,23 +5072,13 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     if (checkpointTimer !== null || shuttingDown || fatalError !== null || checkpointIntervalMs <= 0) {
       return;
     }
-    checkpointTimer = setInterval(() => {
-      void runScheduledCheckpoints();
-    }, checkpointIntervalMs);
-    if (typeof checkpointTimer.unref === "function") {
-      checkpointTimer.unref();
-    }
+    checkpointTimer = unrefInterval(() => void runScheduledCheckpoints(), checkpointIntervalMs);
   }
   function startAsyncFlushTimer() {
     if (mode !== "async" || asyncFlushTimer !== null || shuttingDown || fatalError !== null || flushIntervalMs <= 0) {
       return;
     }
-    asyncFlushTimer = setInterval(() => {
-      void flushAllPartitions();
-    }, flushIntervalMs);
-    if (typeof asyncFlushTimer.unref === "function") {
-      asyncFlushTimer.unref();
-    }
+    asyncFlushTimer = unrefInterval(() => void flushAllPartitions(), flushIntervalMs);
   }
   async function flushAllPartitions() {
     if (fatalError !== null) {
@@ -4750,6 +5140,8 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     return run;
   }
   async function performCheckpoint(indexName, indexState, fromMemory = false) {
+    await directoryWatch.verify();
+    if (fatalError !== null) throw fatalError;
     await runDurableCheckpoint({
       directory,
       hooks,
@@ -4799,10 +5191,14 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       }
       await stallWhileCheckpointsFallBehind(indexState);
     }
-    if (recordedByIndex.size > 0) {
-      startCheckpointTimer();
-      startAsyncFlushTimer();
-    }
+    if (recordedByIndex.size === 0) return outcomes;
+    if (mode === "sync") await directoryWatch.verify();
+    const lost = mode === "sync" ? fatalError : null;
+    if (lost !== null) return outcomes.map((outcome) => outcome.ok ? { ok: false, error: lost } : outcome);
+    await directoryWatch.verifyOnce();
+    directoryWatch.start();
+    startCheckpointTimer();
+    startAsyncFlushTimer();
     return outcomes;
   }
   function recoverIndex(indexName, metadataOnly = false) {
@@ -4824,10 +5220,13 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       return true;
     },
     async recover(metadataOnly = false) {
+      await directoryWatch.claim();
       const names = await listPersistedIndexes(directory);
       for (const indexName of names) {
         await recoverIndex(indexName, metadataOnly);
       }
+      await directoryWatch.verify();
+      directoryWatch.start();
       startCheckpointTimer();
     },
     recoverIndex(indexName) {
@@ -4889,6 +5288,7 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     },
     async shutdown() {
       shuttingDown = true;
+      directoryWatch.stop();
       if (checkpointTimer !== null) {
         clearInterval(checkpointTimer);
         checkpointTimer = null;
@@ -4907,6 +5307,7 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       }
       indexes.clear();
       terminateCheckpointWorker();
+      await directoryWatch.release();
     }
   };
 }
@@ -6298,18 +6699,6 @@ function eligibleIndexNames(state) {
   return names;
 }
 
-// src/engine/orchestration/turn.ts
-function afterCurrentTurn(callback) {
-  if (typeof setImmediate === "function") {
-    setImmediate(callback);
-    return;
-  }
-  setTimeout(callback, 0);
-}
-function yieldToEventLoop4() {
-  return new Promise((resolve) => afterCurrentTurn(resolve));
-}
-
 // src/engine/orchestration/replication.ts
 async function dispatchToWorkers(state, action) {
   const pool = state.workerPool;
@@ -6467,7 +6856,7 @@ async function replicateToWorkers(state, action) {
   const loading = state.copyLoadBuffers.get(action.indexName);
   if (loading !== void 0) {
     queueForCopies(state, detached);
-    if (loading.length % LOAD_BUFFER_YIELD_INTERVAL === 0) await yieldToEventLoop4();
+    if (loading.length % LOAD_BUFFER_YIELD_INTERVAL === 0) await yieldToEventLoop();
     return;
   }
   const queue = state.replicationQueues.get(action.indexName);
@@ -6909,17 +7298,25 @@ function createWorkerExecutor(worker, config) {
 }
 
 // src/workers/factory.ts
-function resolveEntryPoint() {
-  const base = import.meta.url;
-  const distIndex = base.lastIndexOf("/dist/");
-  if (distIndex !== -1) {
-    return new URL("workers/entry.mjs", base.slice(0, distIndex + 6)).href;
+async function entryFileExists(entry) {
+  if (!entry.startsWith("file:")) return true;
+  const [{ access }, { fileURLToPath }] = await Promise.all([import('fs/promises'), import('url')]);
+  try {
+    await access(fileURLToPath(entry));
+    return true;
+  } catch {
+    return false;
   }
-  return base.replace(/\/src\/workers\/[^/]+$/, "/dist/workers/entry.mjs");
+}
+async function requireWorkerEntry() {
+  const entry = resolveWorkerEntry(import.meta.url, /\/src\/workers\/[^/]+$/, "workers/entry.mjs");
+  if (entry === null) throw missingWorkerEntry(import.meta.url);
+  if (import.meta.url.includes("/dist/") && !await entryFileExists(entry)) throw missingWorkerEntry(import.meta.url);
+  return entry;
 }
 async function createWorkerFactory(entryPoint) {
   const runtime = detectRuntime();
-  const resolvedEntry = resolveEntryPoint();
+  const resolvedEntry = await requireWorkerEntry();
   if (runtime.supportsWorkerThreads) {
     const workerThreadsModule = await import('worker_threads');
     return function nodeFactory(workerId, onDeath, onGone) {
@@ -7119,10 +7516,13 @@ function createWorkerPool(config) {
     }
     isShutdown = true;
     const shutdownPromises = [...threadsStillRunning].map((executor) => {
+      let timeoutId;
       const timeoutPromise = new Promise((resolve) => {
-        setTimeout(resolve, 5e3);
+        timeoutId = setTimeout(resolve, SHUTDOWN_TIMEOUT_MS);
       });
-      return Promise.race([shutDownUntilTheThreadIsGone(executor), timeoutPromise]);
+      return Promise.race([shutDownUntilTheThreadIsGone(executor), timeoutPromise]).finally(
+        () => clearTimeout(timeoutId)
+      );
     });
     await Promise.allSettled(shutdownPromises);
     indexAssignment.clear();
@@ -7553,8 +7953,12 @@ async function ensurePool(state) {
 function documentCountOf(state, indexName) {
   return state.executor.getManager(indexName)?.countDocuments() ?? 0;
 }
-function copyThresholdReason(state, indexName) {
-  return `Index "${indexName}" holds ${documentCountOf(state, indexName)} documents, reaching the copy threshold of ${state.copyThreshold}`;
+function copyThresholdReason(state, indexName, incomingCount = 0) {
+  const held = documentCountOf(state, indexName);
+  if (incomingCount <= 0) {
+    return `Index "${indexName}" holds ${held} documents, reaching the copy threshold of ${state.copyThreshold}`;
+  }
+  return `Index "${indexName}" holds ${held} documents, and the batch that the engine is writing adds ${incomingCount}, for ${held + incomingCount} against the copy threshold of ${state.copyThreshold}`;
 }
 function indexReadyForCopies(state, indexName, incomingCount = 0) {
   if (!copiesAllowed(state)) return false;
@@ -7643,7 +8047,7 @@ async function scaleOutBeforeBatch(state, indexName, incomingCount) {
     return;
   }
   if (!indexReadyForCopies(state, indexName, incomingCount)) return;
-  await scaleOutIndex(state, indexName, copyThresholdReason(state, indexName));
+  await scaleOutIndex(state, indexName, copyThresholdReason(state, indexName, incomingCount));
 }
 
 // src/engine/orchestration/idle.ts
@@ -7723,7 +8127,7 @@ function partitionsPerLease(scope, leaseCount) {
   }
   return assignments;
 }
-function mergeWorkerResults(results) {
+function mergeWorkerResults(results, facetConfig) {
   const merged = kWayMerge(results.map((result) => result.scored));
   let totalMatched = 0;
   const workerFacets = [];
@@ -7734,7 +8138,7 @@ function mergeWorkerResults(results) {
   return {
     scored: merged,
     totalMatched,
-    facets: workerFacets.length > 0 ? mergeFacets(workerFacets) : void 0
+    facets: facetConfig !== void 0 && workerFacets.length > 0 ? mergeFacets(workerFacets, facetConfig) : void 0
   };
 }
 function scoresPerPartition(state, indexName, params, globalStats) {
@@ -7754,12 +8158,13 @@ function queryAction(indexName, params, globalStats, partitionIds) {
 }
 async function runSplit(leases, scope, indexName, params, globalStats) {
   const assignments = partitionsPerLease(scope, leases.length);
+  const workerParams = params.facets !== void 0 ? { ...params, facets: oversampledFacetConfig(params.facets) } : params;
   const results = await Promise.all(
     assignments.map(
-      (partitionIds, at) => leases[at].executor.execute(queryAction(indexName, params, globalStats, partitionIds)).finally(() => leases[at].release())
+      (partitionIds, at) => leases[at].executor.execute(queryAction(indexName, workerParams, globalStats, partitionIds)).finally(() => leases[at].release())
     )
   );
-  return mergeWorkerResults(results);
+  return mergeWorkerResults(results, params.facets);
 }
 function takeMainCopyTurn(state) {
   if (state.mainCopyQueries === "none" || state.mainCopyTurnTaken) return false;
@@ -8119,7 +8524,7 @@ function createEngineCore(config, hooks) {
   const rebalanceTargets = /* @__PURE__ */ new Map();
   function guardShutdown() {
     if (shutdownState.isShutdown) {
-      throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "This Narsil instance has been shut down");
+      throw new NarsilError(ErrorCodes.INSTANCE_SHUT_DOWN, "This Narsil instance has been shut down");
     }
   }
   function requireIndex(indexName) {
@@ -8286,6 +8691,82 @@ function createEngineCore(config, hooks) {
   };
 }
 
+// src/engine/lifecycle.ts
+async function startEngineCore(core, config) {
+  try {
+    if (core.durability) {
+      await core.durability.manager.recover(config?.lifecycle !== void 0);
+      checkHeapAfterRecovery(core);
+    }
+    if (core.invalidation) await core.invalidation.start();
+    if (config?.lifecycle === void 0) await core.analysisRebuild.reviewStaleIndexes();
+  } catch (err) {
+    await core.durability?.manager.shutdown().catch(() => void 0);
+    await shutdownEngine(core).catch(() => void 0);
+    throw err;
+  }
+}
+async function shutdownEngine(core) {
+  const { executor, durability, indexRegistry, eventHandlers, orchestrator } = core;
+  core.indexState.dispose();
+  for (const [name] of indexRegistry) {
+    const manager = executor.getManager(name);
+    if (manager) {
+      for (const [, vectorIndex] of manager.getVectorIndexes()) {
+        vectorIndex.dispose();
+      }
+    }
+  }
+  if (durability) {
+    await durability.manager.shutdown();
+  }
+  if (core.invalidation) {
+    await core.invalidation.shutdown();
+  }
+  const adaptersToShutdown = /* @__PURE__ */ new Set();
+  for (const [, entry] of indexRegistry) {
+    if (entry.embeddingAdapter?.shutdown) {
+      adaptersToShutdown.add(entry.embeddingAdapter);
+    }
+  }
+  for (const adapter of adaptersToShutdown) {
+    try {
+      await adapter.shutdown?.();
+    } catch {
+    }
+  }
+  await orchestrator.shutdown();
+  await executor.shutdown();
+  eventHandlers.clear();
+  indexRegistry.clear();
+}
+
+// src/engine/startup-checks.ts
+var announcedMissingWorkerEntry = false;
+function withoutWorkers(config, reason) {
+  if (!announcedMissingWorkerEntry) {
+    announcedMissingWorkerEntry = true;
+    console.warn(
+      `Narsil answers every query on this thread, because it finds no worker entry beside its own module at "${String(reason.details.moduleUrl)}", which happens where a bundler folds @delali/narsil into an application bundle. Keep @delali/narsil outside the bundle to use worker threads, or set workers.enabled to false to silence this notice.`
+    );
+  }
+  return { ...config, workers: { ...config?.workers, enabled: false } };
+}
+async function resolveRunnableConfig(config) {
+  requireSearchBackendSettings();
+  if (!(config?.workers?.enabled ?? workersEnabledByDefault())) return config;
+  const runtime = detectRuntime();
+  if (!runtime.supportsWorkerThreads && !runtime.supportsWebWorkers) return config;
+  try {
+    await requireWorkerEntry();
+    return config;
+  } catch (err) {
+    const missingEntry = err instanceof NarsilError && err.code === ErrorCodes.CONFIG_INVALID;
+    if (!missingEntry || config?.workers?.enabled === true) throw err;
+    return withoutWorkers(config, err);
+  }
+}
+
 // src/engine/index-lifecycle.ts
 async function runLifecycleHook(core, hookName, context) {
   try {
@@ -8419,42 +8900,6 @@ function registerEngineEmbeddingAdapter(core, name, adapter) {
   }
 }
 
-// src/engine/lifecycle.ts
-async function shutdownEngine(core) {
-  const { executor, durability, indexRegistry, eventHandlers, orchestrator } = core;
-  core.indexState.dispose();
-  for (const [name] of indexRegistry) {
-    const manager = executor.getManager(name);
-    if (manager) {
-      for (const [, vectorIndex] of manager.getVectorIndexes()) {
-        vectorIndex.dispose();
-      }
-    }
-  }
-  if (durability) {
-    await durability.manager.shutdown();
-  }
-  if (core.invalidation) {
-    await core.invalidation.shutdown();
-  }
-  const adaptersToShutdown = /* @__PURE__ */ new Set();
-  for (const [, entry] of indexRegistry) {
-    if (entry.embeddingAdapter?.shutdown) {
-      adaptersToShutdown.add(entry.embeddingAdapter);
-    }
-  }
-  for (const adapter of adaptersToShutdown) {
-    try {
-      await adapter.shutdown?.();
-    } catch {
-    }
-  }
-  await orchestrator.shutdown();
-  await executor.shutdown();
-  eventHandlers.clear();
-  indexRegistry.clear();
-}
-
 // src/engine/mutations/durable-rollback.ts
 function rollbackFailed(docId, originalError, rollbackError) {
   throw new NarsilError(
@@ -8822,6 +9267,7 @@ async function applyAdmittedDocuments(ctx, indexName, admitted, options, failed)
     }
     const applied = chunkStart + BATCH_CHUNK_SIZE;
     if (applied < admitted.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -9061,6 +9507,7 @@ async function recordMergedDocuments(ctx, indexName, built, frozen, memberIndexe
       succeededIds.add(doc.docId);
     }
     if (index + 1 < chunks.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -9272,6 +9719,7 @@ async function insertDocumentBatch(ctx, indexName, documents, options) {
     }
     if (prepared.length > 0) await applyPrepared(prepared);
     if (chunkEnd < documents.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -9469,6 +9917,18 @@ async function settleUpdate(ctx, indexName, prepared) {
 async function prepareUpdate(ctx, indexName, entry, docId, document) {
   ctx.guardShutdown();
   validateDocId(docId);
+  const manager = ctx.requireManager(indexName);
+  if (ctx.pluginRegistry.hasHooks("beforeUpdate")) {
+    await ctx.pluginRegistry.runHook("beforeUpdate", {
+      indexName,
+      docId,
+      oldDocument: manager.get(docId) ?? {},
+      newDocument: document
+    });
+  }
+  if (entry.config.required && entry.config.required.length > 0) {
+    validateRequiredFields(document, entry.config.required);
+  }
   if (entry.config.embedding) {
     if (entry.embeddingAdapter) {
       await embedDocumentFields(
@@ -9485,16 +9945,9 @@ async function prepareUpdate(ctx, indexName, entry, docId, document) {
       );
     }
   }
-  const manager = ctx.requireManager(indexName);
   const oldDocument = manager.get(docId);
   const oldPartitionDoc = manager.getRef(docId);
   const rollbackDoc = oldPartitionDoc ? structuredClone(oldPartitionDoc) : void 0;
-  await ctx.pluginRegistry.runHook("beforeUpdate", {
-    indexName,
-    docId,
-    oldDocument: oldDocument ?? {},
-    newDocument: document
-  });
   const vecIndexes = manager.getVectorIndexes();
   const extractedVectors = /* @__PURE__ */ new Map();
   if (vecIndexes.size > 0) {
@@ -9613,6 +10066,7 @@ async function updateDocumentBatch(ctx, indexName, updates, options) {
       succeeded.push(update.docId);
     }
     if (chunkEnd < updates.length) {
+      ctx.checkHeapPressure(indexName);
       await new Promise((r) => setTimeout(r, 0));
     }
   }
@@ -9857,7 +10311,7 @@ async function executeRebalance(manager, indexName, targetPartitionCount, ctx) {
     await replayQueued(manager, indexName, waq, ctx);
     if (ctx.durabilityManager) {
       await ctx.durabilityManager.persistMetadata(indexName);
-      await ctx.durabilityManager.checkpoint(indexName);
+      await (ctx.durabilityManager.checkpointFromMemory?.(indexName) ?? ctx.durabilityManager.checkpoint(indexName));
       await replayQueued(manager, indexName, waq, ctx);
     }
     await ctx.orchestrator.resyncIndex(indexName, wasPromoted);
@@ -10336,6 +10790,10 @@ function readProcessMemory() {
 }
 
 // src/narsil/reads.ts
+async function enterRead(core, indexName) {
+  core.guardShutdown();
+  if (core.rebalancingIndexes.has(indexName)) await yieldToEventLoop();
+}
 function scopedParams(params, options) {
   if (options?.globalStats === void 0) {
     return params;
@@ -10354,7 +10812,7 @@ function broadcastStatsFor(core, options) {
   return (name) => invalidation.broadcastStats(name);
 }
 async function runEngineQuery(core, indexName, params, options) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
@@ -10395,7 +10853,7 @@ async function runEngineQuery(core, indexName, params, options) {
   }
 }
 async function runEnginePreflight(core, indexName, params, options) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
@@ -10428,7 +10886,7 @@ async function runEnginePreflight(core, indexName, params, options) {
   }
 }
 async function runEngineSuggest(core, indexName, params, partitionIds) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const result = executeSuggest(
@@ -10446,7 +10904,7 @@ async function runEngineSuggest(core, indexName, params, partitionIds) {
   }
 }
 async function runEngineQueryStats(core, indexName, terms, partitionIds) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
@@ -10471,13 +10929,14 @@ async function runEngineQueryStats(core, indexName, terms, partitionIds) {
   }
 }
 async function runEngineListDocuments(core, indexName, params, partitionIds) {
-  core.guardShutdown();
+  await enterRead(core, indexName);
   const release = await core.indexState.acquire(indexName);
   try {
     const entry = core.requireIndex(indexName);
     return executeListDocuments(params, {
       manager: core.requireManager(indexName),
       schema: entry.config.schema,
+      strict: entry.config.strict,
       partitionIds
     });
   } finally {
@@ -10784,19 +11243,14 @@ function createNarsilFromCore(core, config) {
 
 // src/narsil/index.ts
 async function createNarsil(config) {
-  const core = createEngineCore(config);
-  if (core.durability) {
-    await core.durability.manager.recover(config?.lifecycle !== void 0);
-    checkHeapAfterRecovery(core);
-  }
-  if (core.invalidation) {
-    await core.invalidation.start();
-  }
-  if (config?.lifecycle === void 0) await core.analysisRebuild.reviewStaleIndexes();
-  return createNarsilFromCore(core, config);
+  requireKnownConfig(config);
+  const runnableConfig = await resolveRunnableConfig(config);
+  const core = createEngineCore(runnableConfig);
+  await startEngineCore(core, runnableConfig);
+  return createNarsilFromCore(core, runnableConfig);
 }
 
 // src/index.ts
 var VERSION = "0.1.0";
 
-export { CHECKPOINT_WORKER_HEARTBEAT_MS, VERSION, applyDeleteEntry, applyIndexEntry, checkHeapAfterRecovery, computeEntryChecksum, createAckMessage, createDurableDirectory, createEngineCore, createEngineIndex, createEntryBatchMessage, createEntryMessage, createForwardBatchMessage, createForwardBatchResultMessage, createForwardMessage, createInsyncAddMessage, createInsyncConfirmMessage, createInsyncRemoveMessage, createNarsil, createNarsilFromCore, runEngineListDocuments, runEnginePreflight, runEngineQuery, runEngineQueryStats, runEngineSuggest, validateAckPayload, validateEntryBatchPayload, validateEntryPayload, validateForwardBatchPayload, validateForwardBatchResultPayload, validateInsyncConfirmPayload, validateReplicationEntry, writeCheckpointSegments };
+export { CHECKPOINT_WORKER_HEARTBEAT_MS, VERSION, applyDeleteEntry, applyIndexEntry, computeEntryChecksum, createAckMessage, createDurableDirectory, createEngineCore, createEngineIndex, createEntryBatchMessage, createEntryMessage, createForwardBatchMessage, createForwardBatchResultMessage, createForwardMessage, createInsyncAddMessage, createInsyncConfirmMessage, createInsyncRemoveMessage, createNarsil, createNarsilFromCore, requireKnownConfig, resolveRunnableConfig, runEngineListDocuments, runEnginePreflight, runEngineQuery, runEngineQueryStats, runEngineSuggest, startEngineCore, validateAckPayload, validateEntryBatchPayload, validateEntryPayload, validateForwardBatchPayload, validateForwardBatchResultPayload, validateInsyncConfirmPayload, validateReplicationEntry, writeCheckpointSegments };