@delali/narsil 0.2.0 → 0.2.1-next.25

package/dist/adapters/filesystem.d.ts

@@ -1,8 +1,30 @@
-import { b as PersistenceAdapter } from '../adapters-Bo2JQg8b.js';
+import { b as PersistenceAdapter } from '../adapters-CVqI5NBt.js';
 
+/**
+ * Where {@link createFilesystemPersistence} writes its partitions.
+ *
+ * @public
+ */
 interface FilesystemPersistenceConfig {
+    /** The adapter writes every partition under this directory. It creates the directory, and it refuses any key that would escape it. */
     directory: string;
 }
+/**
+ * Builds a persistence adapter that writes each partition to its own file, so
+ * an index comes back after a restart.
+ *
+ * The adapter writes each partition to a temporary file, flushes it to the
+ * disk, and renames it into place, which is what keeps a crash mid-write from
+ * leaving a half-written partition behind. It refuses a key that would escape
+ * the configured directory.
+ *
+ * @param config - The directory this adapter writes partitions under.
+ * @returns An adapter you pass as `persistence` when creating an engine.
+ * @throws A `NarsilError` with `PERSISTENCE_SAVE_FAILED` when the directory is
+ * empty or blank.
+ *
+ * @public
+ */
 declare function createFilesystemPersistence(config: FilesystemPersistenceConfig): PersistenceAdapter;
 
 export { type FilesystemPersistenceConfig, createFilesystemPersistence };

package/dist/adapters/filesystem.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-M2EDG55Y.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-UNJZ7ZDB.mjs';
 
 // src/persistence/filesystem.ts
 var cachedFs = null;

package/dist/adapters/indexeddb.d.ts

@@ -1,9 +1,33 @@
-import { b as PersistenceAdapter } from '../adapters-Bo2JQg8b.js';
+import { b as PersistenceAdapter } from '../adapters-CVqI5NBt.js';
 
+/**
+ * Which IndexedDB database and object store
+ * {@link createIndexedDBPersistence} writes to.
+ *
+ * @public
+ */
 interface IndexedDBPersistenceConfig {
+    /** The adapter opens this database, and opens `narsil` by default. */
     dbName?: string;
+    /** The adapter writes partitions to this object store, and to `partitions` by default. */
     storeName?: string;
 }
+/**
+ * Builds a persistence adapter that writes partitions to IndexedDB, so an
+ * index in a browser survives a reload.
+ *
+ * The adapter opens the database on its first call and keeps the handle, so
+ * creating it costs nothing until the engine writes.
+ *
+ * @param config - The database and object store to use. Omit it to accept the
+ * defaults.
+ * @returns An adapter you pass as `persistence` when creating an engine.
+ * @throws A `NarsilError` with `PERSISTENCE_SAVE_FAILED` in a runtime without
+ * IndexedDB, where {@link createMemoryPersistence} or
+ * {@link createFilesystemPersistence} applies instead.
+ *
+ * @public
+ */
 declare function createIndexedDBPersistence(config?: IndexedDBPersistenceConfig): PersistenceAdapter;
 
 export { type IndexedDBPersistenceConfig, createIndexedDBPersistence };

package/dist/adapters/indexeddb.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-M2EDG55Y.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-UNJZ7ZDB.mjs';
 
 // src/persistence/indexeddb.ts
 var DEFAULT_DB_NAME = "narsil";

package/dist/adapters/memory.d.ts

@@ -1,5 +1,18 @@
-import { b as PersistenceAdapter } from '../adapters-Bo2JQg8b.js';
+import { b as PersistenceAdapter } from '../adapters-CVqI5NBt.js';
 
+/**
+ * Builds a persistence adapter that keeps every partition in a map, which is
+ * what tests and short-lived processes want.
+ *
+ * Nothing survives the process, so reach for
+ * {@link createFilesystemPersistence} or
+ * {@link createIndexedDBPersistence} when an index has to come back after a
+ * restart.
+ *
+ * @returns An adapter you pass as `persistence` when creating an engine.
+ *
+ * @public
+ */
 declare function createMemoryPersistence(): PersistenceAdapter;
 
 export { createMemoryPersistence };

package/dist/adapters-CVqI5NBt.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Where the engine writes partitions so that they outlive the process.
+ *
+ * Every method addresses a partition by an opaque key, so any key-value store
+ * works: memory, the filesystem, IndexedDB, or a service you write yourself.
+ * The engine never interprets a key beyond the prefix it lists by.
+ *
+ * @public
+ */
+interface PersistenceAdapter {
+    /**
+     * Writes one partition, replacing whatever the key already held.
+     *
+     * @param key - The key the engine reads this partition back under.
+     * @param data - The serialised partition.
+     */
+    save(key: string, data: Uint8Array): Promise<void>;
+    /**
+     * Reads one partition back.
+     *
+     * @param key - The key a matching {@link PersistenceAdapter.save} wrote.
+     * @returns The stored bytes, or `null` when the key holds nothing.
+     */
+    load(key: string): Promise<Uint8Array | null>;
+    /**
+     * Removes one partition. A key that holds nothing is not an error.
+     *
+     * @param key - The key to clear.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists the keys the store holds under a prefix, which is how the engine
+     * finds an index's partitions on start-up.
+     *
+     * @param prefix - Matched against the start of each key.
+     * @returns Every matching key, in any order.
+     */
+    list(prefix: string): Promise<string[]>;
+    /** This adapter writes to this directory, when a filesystem backs it. */
+    readonly directory?: string;
+}
+/**
+ * Carries partition changes between engine instances that share one store.
+ *
+ * Two processes reading the same persisted index each hold their own copy in
+ * memory, so a write in one has to reach the other. Publish an event on every
+ * write and each subscriber reloads the partitions that event names.
+ *
+ * @public
+ */
+interface InvalidationAdapter {
+    /**
+     * Broadcasts one change to every other subscriber.
+     *
+     * @param event - The partitions that changed, or the statistics that moved.
+     */
+    publish(event: InvalidationEvent): Promise<void>;
+    /**
+     * Starts delivering the events other instances publish.
+     *
+     * @param handler - Called once per event.
+     */
+    subscribe(handler: (event: InvalidationEvent) => void): Promise<void>;
+    /** Closes the channel and releases whatever it held open. */
+    shutdown(): Promise<void>;
+}
+/**
+ * What one instance tells the others about a change it made.
+ *
+ * A `partition` event names the partitions a subscriber must reload. A
+ * `statistics` event carries the term counts that keep BM25 scores comparable
+ * across instances.
+ *
+ * @public
+ */
+type InvalidationEvent = {
+    /** This marks the event as a set of partitions to reload. */
+    type: 'partition';
+    /** The partitions belong to this index. */
+    indexName: string;
+    /** These partition ids changed. */
+    partitions: number[];
+    /** The publisher stamped the event at this many milliseconds since the epoch, which lets a subscriber drop a late one. */
+    timestamp: number;
+    /** This instance published the event, so a subscriber can skip its own. */
+    sourceInstanceId: string;
+} | {
+    /** This marks the event as a statistics update. */
+    type: 'statistics';
+    /** The statistics describe this index. */
+    indexName: string;
+    /** The statistics were measured on this instance. */
+    instanceId: string;
+    /** That instance holds these term counts. */
+    stats: PartitionStatistics;
+};
+/**
+ * The term counts one instance holds, which the others fold into their own so
+ * that BM25 scores stay comparable across a shared index.
+ *
+ * @public
+ */
+interface PartitionStatistics {
+    /** This instance holds this many documents for the index. */
+    totalDocs: number;
+    /** Each term appears in this many documents, keyed by term. */
+    docFrequencies: Record<string, number>;
+    /** Each field holds this many tokens in total, which gives BM25 its average field length. */
+    totalFieldLengths: Record<string, number>;
+}
+/**
+ * Turns text into vectors, so an index embeds documents as they arrive and
+ * embeds a query as it runs.
+ *
+ * Write one against any model you like. The engine calls it on every write to
+ * a field the index maps, and on every vector query that passes `text`.
+ *
+ * @public
+ */
+interface EmbeddingAdapter {
+    /**
+     * Embeds one string.
+     *
+     * @param input - The text to embed.
+     * @param purpose - `document` on a write and `query` on a search, which lets
+     * an asymmetric model pick the right prompt or prefix.
+     * @param signal - Aborts a call the engine no longer needs.
+     * @returns The vector, whose length must equal
+     * {@link EmbeddingAdapter.dimensions}.
+     */
+    embed(input: string, purpose: 'document' | 'query', signal?: AbortSignal): Promise<Float32Array>;
+    /**
+     * Embeds many strings in one call, which a batch load uses when the adapter
+     * offers it. The engine falls back to {@link EmbeddingAdapter.embed} per
+     * item when it is absent.
+     *
+     * @param inputs - The texts to embed.
+     * @param purpose - `document` on a write and `query` on a search.
+     * @param signal - Aborts a call the engine no longer needs.
+     * @returns One vector per input, in the same order.
+     */
+    embedBatch?(inputs: string[], purpose: 'document' | 'query', signal?: AbortSignal): Promise<Float32Array[]>;
+    /** Every vector this adapter returns is this long, which must match the schema's `vector[N]`. */
+    readonly dimensions: number;
+    /** Releases whatever the adapter holds open, such as a model or a connection pool. */
+    shutdown?(): Promise<void>;
+}
+
+export type { EmbeddingAdapter as E, InvalidationAdapter as I, PartitionStatistics as P, InvalidationEvent as a, PersistenceAdapter as b };

package/dist/{chunk-S6IAXOBA.mjs → chunk-ASI6AOW2.mjs}

@@ -1,6 +1,6 @@
 import { english } from './chunk-TGP5M5R7.mjs';
 import { createVectorStore, createArenaSimd, createHNSWIndex, magnitude, createBoundedMaxHeap, euclideanDistance, dotProduct, cosineSimilarityWithMagnitudes } from './chunk-S7RJJMHI.mjs';
-import { NarsilError, ErrorCodes, createNarsilError } from './chunk-M2EDG55Y.mjs';
+import { NarsilError, ErrorCodes, createNarsilError } from './chunk-UNJZ7ZDB.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/languages/registry.ts

package/dist/{chunk-AUMKFYTG.mjs → chunk-FKK76OR7.mjs}

@@ -1,6 +1,42 @@
-import { NarsilError, ErrorCodes } from './chunk-M2EDG55Y.mjs';
+import { NarsilError, ErrorCodes } from './chunk-UNJZ7ZDB.mjs';
 import { decode, encode } from '@msgpack/msgpack';
 
+// src/distribution/coordinator/etcd/types.ts
+var DEFAULT_ETCD_CONFIG = {
+  endpoints: ["http://localhost:2379"],
+  keyPrefix: "_narsil",
+  nodeHeartbeatTtlSeconds: 30,
+  leaseTtlSeconds: 15
+};
+var ETCD_KEY_NODES = "nodes";
+var ETCD_KEY_ALLOCATION = "allocation";
+var ETCD_KEY_PARTITION = "partition";
+var ETCD_KEY_SCHEMA = "schema";
+function buildKey(prefix, ...segments) {
+  return [prefix, ...segments].join("/");
+}
+
+// src/distribution/coordinator/etcd/keys.ts
+var ETCD_KEY_LEASE = "lease";
+var ETCD_KEY_GENERIC = "kv";
+function coordinatorKeys(config) {
+  const prefix = config.keyPrefix;
+  return {
+    node: (nodeId) => buildKey(prefix, ETCD_KEY_NODES, nodeId),
+    nodePrefix: () => buildKey(prefix, ETCD_KEY_NODES),
+    allocation: (indexName) => buildKey(prefix, ETCD_KEY_ALLOCATION, indexName),
+    allocationPrefix: () => buildKey(prefix, ETCD_KEY_ALLOCATION),
+    partition: (indexName, partitionId) => buildKey(prefix, ETCD_KEY_PARTITION, indexName, String(partitionId)),
+    schema: (indexName) => buildKey(prefix, ETCD_KEY_SCHEMA, indexName),
+    schemaPrefix: () => buildKey(prefix, ETCD_KEY_SCHEMA),
+    lease: (key) => buildKey(prefix, ETCD_KEY_LEASE, key),
+    generic: (key) => buildKey(prefix, ETCD_KEY_GENERIC, key)
+  };
+}
+function extractSuffix(fullKey, prefix) {
+  return fullKey.slice(prefix.length + 1);
+}
+
 // src/distribution/coordinator/etcd/leases.ts
 var LeaseManager = class {
   leases = /* @__PURE__ */ new Map();
@@ -99,21 +135,6 @@ function deserializeSchema(data) {
   return decode(data);
 }
 
-// src/distribution/coordinator/etcd/types.ts
-var DEFAULT_ETCD_CONFIG = {
-  endpoints: ["http://localhost:2379"],
-  keyPrefix: "_narsil",
-  nodeHeartbeatTtlSeconds: 30,
-  leaseTtlSeconds: 15
-};
-var ETCD_KEY_NODES = "nodes";
-var ETCD_KEY_ALLOCATION = "allocation";
-var ETCD_KEY_PARTITION = "partition";
-var ETCD_KEY_SCHEMA = "schema";
-function buildKey(prefix, ...segments) {
-  return [prefix, ...segments].join("/");
-}
-
 // src/distribution/coordinator/etcd/validation.ts
 var MAX_NODE_ID_LENGTH = 255;
 var VALID_PARTITION_STATES = /* @__PURE__ */ new Set(["UNASSIGNED", "INITIALISING", "ACTIVE", "MIGRATING", "DECOMMISSIONING"]);
@@ -164,27 +185,7 @@ async function createEtcdCoordinator(config) {
       throw new NarsilError(ErrorCodes.CONFIG_INVALID, "Coordinator has been shut down");
     }
   }
-  function nodeKey(nodeId) {
-    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_NODES, nodeId);
-  }
-  function allocationKey(indexName) {
-    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_ALLOCATION, indexName);
-  }
-  function partitionKey(indexName, partitionId) {
-    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_PARTITION, indexName, String(partitionId));
-  }
-  function schemaKey(indexName) {
-    return buildKey(resolvedConfig.keyPrefix, ETCD_KEY_SCHEMA, indexName);
-  }
-  function leaseKey(key) {
-    return buildKey(resolvedConfig.keyPrefix, "lease", key);
-  }
-  function genericKey(key) {
-    return buildKey(resolvedConfig.keyPrefix, "kv", key);
-  }
-  function extractSuffix(fullKey, prefix) {
-    return fullKey.slice(prefix.length + 1);
-  }
+  const keys = coordinatorKeys(resolvedConfig);
   function addWatcher(watcher) {
     if (watchers.size >= MAX_WATCHERS) {
       watcher.cancel().catch(() => {
@@ -207,7 +208,7 @@ async function createEtcdCoordinator(config) {
       const ttl = resolvedConfig.nodeHeartbeatTtlSeconds;
       const lease = client.lease(ttl);
       await lease.grant();
-      const key = nodeKey(registration.nodeId);
+      const key = keys.node(registration.nodeId);
       const data = Buffer.from(serializeNodeRegistration(registration));
       await lease.put(key).value(data).exec();
       const existing = leaseManager.get(key);
@@ -220,7 +221,7 @@ async function createEtcdCoordinator(config) {
     async deregisterNode(nodeId) {
       assertNotShutdown();
       validateNodeId(nodeId);
-      const key = nodeKey(nodeId);
+      const key = keys.node(nodeId);
       const entry = leaseManager.remove(key);
       if (entry !== void 0) {
         await entry.lease.revoke().catch(() => {
@@ -230,7 +231,7 @@ async function createEtcdCoordinator(config) {
     },
     async listNodes() {
       assertNotShutdown();
-      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_NODES);
+      const prefix = keys.nodePrefix();
       const result = await client.getAll().prefix(prefix).buffers();
       const nodes = [];
       for (const key of Object.keys(result)) {
@@ -243,7 +244,7 @@ async function createEtcdCoordinator(config) {
     },
     async watchNodes(handler) {
       assertNotShutdown();
-      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_NODES);
+      const prefix = keys.nodePrefix();
       const watcher = await client.watch().prefix(prefix).create();
       addWatcher(watcher);
       watcher.on("put", (kv) => {
@@ -262,7 +263,7 @@ async function createEtcdCoordinator(config) {
     },
     async getAllocation(indexName) {
       assertNotShutdown();
-      const key = allocationKey(indexName);
+      const key = keys.allocation(indexName);
       const buf = await client.get(key).buffer();
       if (buf === null) {
         return null;
@@ -271,7 +272,7 @@ async function createEtcdCoordinator(config) {
     },
     async putAllocation(indexName, table, expectedVersion) {
       assertNotShutdown();
-      const key = allocationKey(indexName);
+      const key = keys.allocation(indexName);
       const data = Buffer.from(serializeAllocationTable(table));
       if (expectedVersion === void 0) {
         await client.put(key).value(data).exec();
@@ -295,7 +296,7 @@ async function createEtcdCoordinator(config) {
     },
     async watchAllocation(handler) {
       assertNotShutdown();
-      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_ALLOCATION);
+      const prefix = keys.allocationPrefix();
       const watcher = await client.watch().prefix(prefix).create();
       addWatcher(watcher);
       watcher.on("put", (kv) => {
@@ -309,7 +310,7 @@ async function createEtcdCoordinator(config) {
     },
     async getPartitionState(indexName, partitionId) {
       assertNotShutdown();
-      const key = partitionKey(indexName, partitionId);
+      const key = keys.partition(indexName, partitionId);
       const value = await client.get(key).string();
       if (value === null) {
         return "UNASSIGNED";
@@ -318,12 +319,12 @@ async function createEtcdCoordinator(config) {
     },
     async putPartitionState(indexName, partitionId, state) {
       assertNotShutdown();
-      const key = partitionKey(indexName, partitionId);
+      const key = keys.partition(indexName, partitionId);
       await client.put(key).value(state).exec();
     },
     async acquireLease(key, nodeId, ttlMs) {
       assertNotShutdown();
-      const etcdKey = leaseKey(key);
+      const etcdKey = keys.lease(key);
       const ttlSeconds = Math.max(1, Math.ceil(ttlMs / 1e3));
       const existing = leaseManager.get(etcdKey);
       if (existing !== void 0 && existing.nodeId === nodeId) {
@@ -348,7 +349,7 @@ async function createEtcdCoordinator(config) {
     },
     async renewLease(key, nodeId, _ttlMs) {
       assertNotShutdown();
-      const etcdKey = leaseKey(key);
+      const etcdKey = keys.lease(key);
       const entry = leaseManager.getByNodeId(etcdKey, nodeId);
       if (entry === void 0) {
         return false;
@@ -363,7 +364,7 @@ async function createEtcdCoordinator(config) {
     },
     async releaseLease(key) {
       assertNotShutdown();
-      const etcdKey = leaseKey(key);
+      const etcdKey = keys.lease(key);
       const entry = leaseManager.remove(etcdKey);
       if (entry !== void 0) {
         await entry.lease.revoke().catch(() => {
@@ -373,7 +374,7 @@ async function createEtcdCoordinator(config) {
     },
     async get(key) {
       assertNotShutdown();
-      const etcdKey = genericKey(key);
+      const etcdKey = keys.generic(key);
       const buf = await client.get(etcdKey).buffer();
       if (buf === null) {
         return null;
@@ -382,7 +383,7 @@ async function createEtcdCoordinator(config) {
     },
     async compareAndSet(key, expected, value) {
       assertNotShutdown();
-      const etcdKey = genericKey(key);
+      const etcdKey = keys.generic(key);
       const newValue = Buffer.from(value);
       if (expected === null) {
         const txn2 = await client.if(etcdKey, "Create", "==", 0).then(client.put(etcdKey).value(newValue)).commit();
@@ -394,7 +395,7 @@ async function createEtcdCoordinator(config) {
     },
     async getSchema(indexName) {
       assertNotShutdown();
-      const key = schemaKey(indexName);
+      const key = keys.schema(indexName);
       const buf = await client.get(key).buffer();
       if (buf === null) {
         return null;
@@ -403,12 +404,12 @@ async function createEtcdCoordinator(config) {
     },
     async putSchema(indexName, schema) {
       assertNotShutdown();
-      const key = schemaKey(indexName);
+      const key = keys.schema(indexName);
       await client.put(key).value(serializeSchema(schema)).exec();
     },
     async watchSchemas(handler) {
       assertNotShutdown();
-      const prefix = buildKey(resolvedConfig.keyPrefix, ETCD_KEY_SCHEMA);
+      const prefix = keys.schemaPrefix();
       const watcher = await client.watch().prefix(prefix).create();
       addWatcher(watcher);
       watcher.on("put", (kv) => {
@@ -429,7 +430,7 @@ async function createEtcdCoordinator(config) {
     },
     async getLeaseHolder(key) {
       assertNotShutdown();
-      const etcdKey = leaseKey(key);
+      const etcdKey = keys.lease(key);
       const value = await client.get(etcdKey).string();
       return value ?? null;
     },

package/dist/{chunk-M2EDG55Y.mjs → chunk-UNJZ7ZDB.mjs}

@@ -90,8 +90,18 @@ var ErrorCodes = {
   SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED"
 };
 var NarsilError = class extends Error {
+  /** This says which failure it is. */
   code;
+  /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
   details;
+  /**
+   * Builds an error carrying a code the caller can branch on.
+   *
+   * @param code - The failure this error reports.
+   * @param message - Plain description, for a log or a person.
+   * @param details - Values behind the failure, which reach
+   * {@link NarsilError.details}.
+   */
   constructor(code, message, details) {
     super(message);
     this.name = "NarsilError";

package/dist/{chunk-XAKNSWIK.mjs → chunk-WLR5BFL3.mjs}

@@ -1,6 +1,6 @@
-import { getNestedValue, getLanguage, extractVectorFieldsFromSchema, createDirectExecutor, createPartitionRouter, createPartitionManager, createVectorIndex, validateSchema, validateVectorPromotion, resolveIndexAnalysis, deserializePayloadV2, deserializePayloadV1, tokenize, fanOutQuery, validateRequiredFields, mergePartitionStats, createPartitionIndex, flattenSchema, pruneStatsToQueryTerms, fnv1a, detectRuntime, serializeMetadata, isNodeMainThread, spawnNodeWorker, deserializeMetadata, kWayMerge } from './chunk-S6IAXOBA.mjs';
+import { getNestedValue, getLanguage, extractVectorFieldsFromSchema, createDirectExecutor, createPartitionRouter, createPartitionManager, createVectorIndex, validateSchema, validateVectorPromotion, resolveIndexAnalysis, deserializePayloadV2, deserializePayloadV1, tokenize, fanOutQuery, validateRequiredFields, mergePartitionStats, createPartitionIndex, flattenSchema, pruneStatsToQueryTerms, fnv1a, detectRuntime, serializeMetadata, isNodeMainThread, spawnNodeWorker, deserializeMetadata, kWayMerge } from './chunk-ASI6AOW2.mjs';
 import { crc32, crc32Init, crc32Update, crc32Final } from './chunk-KMMJMDUA.mjs';
-import { ErrorCodes, NarsilError } from './chunk-M2EDG55Y.mjs';
+import { ErrorCodes, NarsilError } from './chunk-UNJZ7ZDB.mjs';
 import { generateId, createRequestId, isValidWorkerResponse } from './chunk-BKAI2WXI.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
@@ -8023,18 +8023,7 @@ function readProcessMemory() {
   }
 }
 
-// src/narsil.ts
-async function createNarsil(config) {
-  const core = createEngineCore(config);
-  if (core.durability) {
-    await core.durability.manager.recover();
-  }
-  if (core.invalidation) {
-    await core.invalidation.start();
-  }
-  await core.analysisRebuild.reviewStaleIndexes();
-  return createNarsilFromCore(core, config);
-}
+// src/narsil/operations.ts
 function createNarsilFromCore(core, config) {
   const {
     executor,
@@ -8336,6 +8325,19 @@ function createNarsilFromCore(core, config) {
   return narsil;
 }
 
+// src/narsil/index.ts
+async function createNarsil(config) {
+  const core = createEngineCore(config);
+  if (core.durability) {
+    await core.durability.manager.recover();
+  }
+  if (core.invalidation) {
+    await core.invalidation.start();
+  }
+  await core.analysisRebuild.reviewStaleIndexes();
+  return createNarsilFromCore(core, config);
+}
+
 // src/index.ts
 var VERSION = "0.1.0";