@delali/narsil 0.2.4-next.42 → 0.2.4-next.44

package/dist/embeddings/openai.mjs

@@ -1,4 +1,4 @@
-import { NarsilError, ErrorCodes } from '../chunk-GB2IIJJG.mjs';
+import { NarsilError, ErrorCodes } from '../chunk-P4ELXVJQ.mjs';
 
 // src/embeddings/openai.ts
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503]);

package/dist/{engine-BE45D5ZG.d.ts → engine-Cjr1uBLa.d.ts}

@@ -1,6 +1,6 @@
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { I as IndexInfo, f as IndexStats, P as PartitionStatsResult, B as BatchResult, L as ListParams, g as ListResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult, M as MemoryStats, V as VectorMaintenanceResult } from './search-DHuXwJYk.js';
-import { I as IndexConfig, A as AnyDocument, a as InsertOptions, P as PartitionConfig } from './schema-ZRbk8BgH.js';
+import { I as IndexInfo, f as IndexStats, P as PartitionStatsResult, B as BatchResult, L as ListParams, g as ListResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult, M as MemoryStats, V as VectorMaintenanceResult } from './search-DDHjfXhJ.js';
+import { I as IndexConfig, A as AnyDocument, b as InsertOptions, P as PartitionConfig } from './schema-B7juWg8Q.js';
 
 /**
  * Every event the engine emits, with the payload each one carries.
@@ -13,18 +13,12 @@ import { I as IndexConfig, A as AnyDocument, a as InsertOptions, P as PartitionC
  * @public
  */
 type NarsilEventMap = {
-    /** A partition failed to reach the persistence adapter. */
-    persistenceError: {
-        /** The partition belongs to this index. */
-        indexName: string;
-        /** This partition failed to save. */
-        partitionId: number;
-        /** The adapter threw this. */
-        error: Error;
-        /** This turns true once the engine has given up retrying, which means the partition stays unsaved. */
-        retriesExhausted: boolean;
-    };
-    /** A worker thread died, and the engine has rebuilt the indexes it held. */
+    /**
+     * A worker thread died. The pool drops it and fails its outstanding requests
+     * with `WORKER_CRASHED`, while the remaining workers keep answering because
+     * each holds a full worker copy of every promoted index. Once no worker is
+     * left, queries fall back to the main thread, which holds every document.
+     */
     workerCrash: {
         /** This worker died. */
         workerId: number;
@@ -94,6 +88,28 @@ type NarsilEventMap = {
     };
 };
 
+/**
+ * Opens and closes durable indexes without deleting them.
+ *
+ * @public
+ */
+interface IndexLifecycleOperations {
+    /**
+     * Loads a closed index from its durable checkpoint and resets a parked recovery failure.
+     *
+     * @param indexName - The index to load.
+     * @returns A promise that settles when the index is ready for operations.
+     */
+    open(indexName: string): Promise<void>;
+    /**
+     * Drains active work, checkpoints the index, releases its memory, and keeps its durable files.
+     *
+     * @param indexName - The index to close.
+     * @returns A promise that settles after the index releases its memory.
+     */
+    close(indexName: string): Promise<void>;
+}
+
 /**
  * The search engine, and everything you do with it.
  *
@@ -103,7 +119,7 @@ type NarsilEventMap = {
  *
  * @public
  */
-interface Narsil {
+interface Narsil extends IndexLifecycleOperations {
     /**
      * Creates an index you can insert documents into and query.
      *
@@ -146,7 +162,7 @@ interface Narsil {
      * an index grows unevenly or a rebalance is worth running.
      *
      * @param indexName - The index to describe.
-     * @returns One entry per partition, in partition order.
+     * @returns One entry per open partition, in partition order, or an empty list while the index is closed.
      */
     getPartitionStats(indexName: string): PartitionStatsResult[];
     /**
@@ -296,8 +312,11 @@ interface Narsil {
      */
     query<T = AnyDocument>(indexName: string, params: QueryParams): Promise<QueryResult<T>>;
     /**
-     * Counts what a query would match without building or ranking a single hit,
-     * which is how a result-count badge stays cheap.
+     * Counts what a query would match without building a single hit, which is
+     * how a result-count badge stays cheap. A full-text count also skips scoring
+     * unless the query carries `minScore`, which prunes matches by score, or a
+     * `termMatch` policy other than `any`, which prunes them by term coverage. A
+     * vector or hybrid count still runs its search.
      *
      * @param indexName - The index the query would run against.
      * @param params - The same parameters {@link Narsil.query} takes. Anything
@@ -341,13 +360,17 @@ interface Narsil {
      */
     snapshot(indexName: string): Promise<Uint8Array>;
     /**
-     * Loads an index from `.nrsl` bytes, replacing whatever the name held.
+     * Loads an index from snapshot bytes, replacing whatever the name held.
+     *
+     * The engine reads the `.nrsl` envelope {@link Narsil.snapshot} writes, and
+     * it also reads the headerless MessagePack form earlier releases wrote.
      *
      * @param indexName - The name the restored index takes.
      * @param data - Bytes a {@link Narsil.snapshot} produced.
-     * @throws A `NarsilError` with `ENVELOPE_INVALID_MAGIC` or
-     * `ENVELOPE_VERSION_MISMATCH` when the bytes are not a file this engine
-     * reads.
+     * @throws A `NarsilError` with `ENVELOPE_VERSION_MISMATCH` when the envelope
+     * carries a different format version, `PERSISTENCE_CRC_MISMATCH` when the
+     * payload fails its checksum, or `DOC_VALIDATION_FAILED` when the bytes hold
+     * no snapshot.
      */
     restore(indexName: string, data: Uint8Array): Promise<void>;
     /**
@@ -421,7 +444,7 @@ interface Narsil {
      * optimisation would cost.
      *
      * @param indexName - The index to describe.
-     * @returns One entry per vector field.
+     * @returns One entry per vector field, or an empty list while the index is closed.
      */
     vectorMaintenanceStatus(indexName: string): VectorMaintenanceResult[];
     /**
@@ -455,4 +478,4 @@ interface Narsil {
     shutdown(): Promise<void>;
 }
 
-export type { NarsilEventMap as N, Narsil as a };
+export type { IndexLifecycleOperations as I, NarsilEventMap as N, Narsil as a };