@delali/narsil 0.2.3-next.35 → 0.2.3

package/dist/embeddings/openai.mjs

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

package/dist/{engine-DEtRLYpB.d.ts → engine-BE45D5ZG.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-Dt4dkzpf.js';
-import { I as IndexConfig, A as AnyDocument, a as InsertOptions, P as PartitionConfig } from './schema-emTQfEiX.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';
 
 /**
  * Every event the engine emits, with the payload each one carries.
@@ -455,4 +455,4 @@ interface Narsil {
     shutdown(): Promise<void>;
 }
 
-export type { Narsil as N, NarsilEventMap as a };
+export type { NarsilEventMap as N, Narsil as a };

package/dist/index.browser.mjs

@@ -55,6 +55,8 @@ var ErrorCodes = {
   NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED",
   NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED",
   NODE_NOT_JOINED: "NODE_NOT_JOINED",
+  NODE_NOT_READY: "NODE_NOT_READY",
+  NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER",
   COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING",
   TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING",
   REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID",
@@ -2544,6 +2546,9 @@ function metadataToWire(meta) {
   if (meta.indexUuid !== void 0) {
     wire.index_uuid = meta.indexUuid;
   }
+  if (meta.heldPartitions !== void 0) {
+    wire.held_partitions = meta.heldPartitions;
+  }
   return wire;
 }
 function wireToMetadata(raw) {
@@ -2633,8 +2638,14 @@ function wireToMetadata(raw) {
   if (typeof raw.index_uuid === "string" && raw.index_uuid.length > 0) {
     meta.indexUuid = raw.index_uuid;
   }
+  if (Array.isArray(raw.held_partitions) && raw.held_partitions.every(isNonNegativeInteger)) {
+    meta.heldPartitions = raw.held_partitions;
+  }
   return meta;
 }
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
 function isPositiveInteger2(value) {
   return typeof value === "number" && Number.isInteger(value) && value >= 1;
 }
@@ -15845,7 +15856,7 @@ function normalizePartitions(raw) {
   }
   const result = [];
   for (const entry of raw) {
-    if (!isNonNegativeInteger(entry?.partitionId)) {
+    if (!isNonNegativeInteger2(entry?.partitionId)) {
       throw new NarsilError(ErrorCodes.PERSISTENCE_LOAD_FAILED, "Segment manifest has a partition without a valid id", {
         partitionId: entry?.partitionId
       });
@@ -15880,7 +15891,7 @@ function normalizeSegments(raw, partitionId) {
   const seenIds = /* @__PURE__ */ new Set();
   const result = [];
   for (const segment of raw) {
-    if (!isSegmentId(segment?.id) || !isNonNegativeInteger(segment.docCount) || !isNonNegativeInteger(segment.tombstoneCount) || !isKey(segment.key)) {
+    if (!isSegmentId(segment?.id) || !isNonNegativeInteger2(segment.docCount) || !isNonNegativeInteger2(segment.tombstoneCount) || !isKey(segment.key)) {
       throw new NarsilError(ErrorCodes.PERSISTENCE_LOAD_FAILED, "Segment manifest has an invalid segment reference", {
         partitionId,
         segment
@@ -15932,7 +15943,7 @@ function normalizeVectors(raw, partitionId) {
   }
   const result = [];
   for (const vector of raw) {
-    if (typeof vector?.fieldPath !== "string" || !isNonNegativeInteger(vector.generation) || !isKey(vector.key)) {
+    if (typeof vector?.fieldPath !== "string" || !isNonNegativeInteger2(vector.generation) || !isKey(vector.key)) {
       throw new NarsilError(ErrorCodes.PERSISTENCE_LOAD_FAILED, "Segment manifest has an invalid vector reference", {
         partitionId,
         vector
@@ -15942,7 +15953,7 @@ function normalizeVectors(raw, partitionId) {
   }
   return result;
 }
-function isNonNegativeInteger(value) {
+function isNonNegativeInteger2(value) {
   return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
 function isSegmentId(value) {
@@ -17728,6 +17739,7 @@ function createDurabilityManager(config, hooks, directoryOverride) {
   const mode = config.mode ?? "sync";
   const flushIntervalMs = config.flushIntervalMs ?? DEFAULT_ASYNC_FLUSH_INTERVAL_MS;
   const indexes = /* @__PURE__ */ new Map();
+  const metadataWrites = /* @__PURE__ */ new Map();
   let checkpointTimer = null;
   let asyncFlushTimer = null;
   let shuttingDown = false;
@@ -17780,6 +17792,15 @@ function createDurabilityManager(config, hooks, directoryOverride) {
     }
     return partition;
   }
+  function queueMetadataWrite(indexName, write) {
+    const previous = metadataWrites.get(indexName) ?? Promise.resolve();
+    const queued = previous.then(write);
+    metadataWrites.set(
+      indexName,
+      queued.catch(() => void 0)
+    );
+    return queued;
+  }
   function startCheckpointTimer() {
     if (checkpointTimer !== null || shuttingDown || fatalError !== null || checkpointIntervalMs <= 0) {
       return;
@@ -17937,6 +17958,9 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       }
       startCheckpointTimer();
     },
+    highestPersistedSeqNo(indexName, partitionId) {
+      return indexes.get(indexName)?.partitions.get(partitionId)?.appliedSeqNo ?? 0;
+    },
     async recordMutation(record) {
       if (fatalError !== null) {
         throw fatalError;
@@ -17984,14 +18008,16 @@ function createDurabilityManager(config, hooks, directoryOverride) {
       }
       return allocatedSeqNo;
     },
-    async persistMetadata(indexName) {
-      const metadata = hooks.buildMetadata(indexName);
-      if (metadata === void 0) {
-        return;
-      }
-      const bytes = await writeMetadataEnvelope(metadata, { checksum: true });
-      await directory.atomicWrite(`${indexName}/meta`, bytes);
-      getOrCreateIndexState(indexName);
+    persistMetadata(indexName) {
+      return queueMetadataWrite(indexName, async () => {
+        const metadata = hooks.buildMetadata(indexName);
+        if (metadata === void 0) {
+          return;
+        }
+        const bytes = await writeMetadataEnvelope(metadata, { checksum: true });
+        await directory.atomicWrite(`${indexName}/meta`, bytes);
+        getOrCreateIndexState(indexName);
+      });
     },
     checkpoint(indexName) {
       return checkpointIndex(indexName);
@@ -18048,6 +18074,7 @@ function createSnapshotOnlyManager(adapter, config, hooks, publisher) {
   const checkpointIntervalMs = config.checkpointIntervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS;
   const checkpointMutationThreshold = config.checkpointMutationThreshold ?? DEFAULT_CHECKPOINT_MUTATION_THRESHOLD;
   const indexes = /* @__PURE__ */ new Map();
+  const metadataWrites = /* @__PURE__ */ new Map();
   let checkpointTimer = null;
   let shuttingDown = false;
   function getOrCreateIndexState(indexName) {
@@ -18126,6 +18153,15 @@ function createSnapshotOnlyManager(adapter, config, hooks, publisher) {
     indexState.checkpointInFlight = run;
     return run;
   }
+  function queueMetadataWrite(indexName, write) {
+    const previous = metadataWrites.get(indexName) ?? Promise.resolve();
+    const queued = previous.then(write);
+    metadataWrites.set(
+      indexName,
+      queued.catch(() => void 0)
+    );
+    return queued;
+  }
   async function recoverIndex(indexName) {
     const metaBytes = await adapter.load(metadataKey(indexName));
     if (metaBytes === null) {
@@ -18160,6 +18196,9 @@ function createSnapshotOnlyManager(adapter, config, hooks, publisher) {
       }
       startCheckpointTimer();
     },
+    highestPersistedSeqNo() {
+      return 0;
+    },
     async recordMutation(record) {
       const indexState = getOrCreateIndexState(record.indexName);
       const buffered = indexState.applyChain.then(() => record.apply());
@@ -18174,14 +18213,16 @@ function createSnapshotOnlyManager(adapter, config, hooks, publisher) {
       }
       return 0;
     },
-    async persistMetadata(indexName) {
-      const metadata = hooks.buildMetadata(indexName);
-      if (metadata === void 0) {
-        return;
-      }
-      const bytes = await writeMetadataEnvelope(metadata, { checksum: true });
-      await adapter.save(metadataKey(indexName), bytes);
-      getOrCreateIndexState(indexName);
+    persistMetadata(indexName) {
+      return queueMetadataWrite(indexName, async () => {
+        const metadata = hooks.buildMetadata(indexName);
+        if (metadata === void 0) {
+          return;
+        }
+        const bytes = await writeMetadataEnvelope(metadata, { checksum: true });
+        await adapter.save(metadataKey(indexName), bytes);
+        getOrCreateIndexState(indexName);
+      });
     },
     checkpoint(indexName) {
       return checkpointIndex(indexName);
@@ -18274,6 +18315,9 @@ function buildMetadata(indexName, hooks) {
   if (config.indexUuid !== void 0) {
     metadata.indexUuid = config.indexUuid;
   }
+  if (config.heldPartitions !== void 0) {
+    metadata.heldPartitions = config.heldPartitions;
+  }
   return metadata;
 }
 function createDurabilityIntegration(tier, hooks) {
@@ -18335,6 +18379,7 @@ function createDurabilityFromTier(tier, wiring) {
       } : void 0;
       return {
         ...entry.indexUuid !== null ? { indexUuid: entry.indexUuid } : {},
+        ...entry.heldPartitions !== null ? { heldPartitions: entry.heldPartitions } : {},
         schema: flattenSchema(entry.config.schema),
         language: entry.language.name,
         k1: entry.config.bm25?.k1 ?? 1.2,
@@ -19446,7 +19491,8 @@ function createEngineCore(config) {
       embeddingAdapter,
       embeddingAdapterName: adapterName,
       vectorFieldPaths: getVectorFieldPaths(indexConfig.schema),
-      indexUuid: metadata.indexUuid ?? null
+      indexUuid: metadata.indexUuid ?? null,
+      heldPartitions: metadata.heldPartitions ?? null
     });
     if (metadata.analysisRevision !== language.revision) {
       analysisRebuild.markStale({
@@ -19726,7 +19772,8 @@ async function createEngineIndex(core, config, name, indexConfig, indexUuid) {
     embeddingAdapter: resolvedEmbeddingAdapter,
     embeddingAdapterName,
     vectorFieldPaths: getVectorFieldPaths(indexConfig.schema),
-    indexUuid: null
+    indexUuid: null,
+    heldPartitions: null
   });
   if (core.durability) {
     await core.durability.manager.persistMetadata(name);
@@ -21656,7 +21703,8 @@ async function restoreFromSnapshot(indexName, data, deps) {
     embeddingAdapter,
     embeddingAdapterName: adapterName,
     vectorFieldPaths: vectorFieldPaths2,
-    indexUuid: null
+    indexUuid: null,
+    heldPartitions: null
   });
   try {
     const manager = deps.requireManager(indexName);

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { c as StopWordOverride, C as CustomTokenizer } from './schema-emTQfEiX.js';
-export { A as AnyDocument, B as BM25Params, E as EmbeddingFieldConfig, F as FieldType, I as IndexConfig, a as InsertOptions, P as PartitionConfig, S as SchemaDefinition, b as ScoringMode, V as VectorIndexConfig, d as VectorQuantizationMode } from './schema-emTQfEiX.js';
+import { c as StopWordOverride, C as CustomTokenizer } from './schema-ZRbk8BgH.js';
+export { A as AnyDocument, B as BM25Params, E as EmbeddingFieldConfig, F as FieldType, I as IndexConfig, a as InsertOptions, P as PartitionConfig, S as SchemaDefinition, b as ScoringMode, V as VectorIndexConfig, d as VectorQuantizationMode } from './schema-ZRbk8BgH.js';
 import { L as LanguageModule } from './language-DB8KG1z5.js';
 export { T as TokenizerConfig } from './language-DB8KG1z5.js';
-export { A as ArrayFilter, B as BatchResult, C as ClientErrorCode, a as ClientErrorCodes, k as ComparisonFilter, D as DocumentProjection, E as ErrorCode, b as ErrorCodes, F as FacetConfig, l as FacetResult, m as FieldFilter, n as FilterExpression, G as GeoFilter, o as GeoPolygonFilter, p as GeoRadiusFilter, q as GroupConfig, r as GroupReducer, s as GroupResult, H as HighlightConfig, t as HighlightMatch, u as Hit, v as HybridConfig, I as IndexInfo, f as IndexStats, L as ListParams, g as ListResult, w as ListedDocument, M as MemoryStats, N as NarsilError, c as NarsilErrorCode, P as PartitionStatsResult, h as PreflightResult, x as PresenceFilter, y as ProcessMemoryReport, z as QueryCoverage, Q as QueryParams, e as QueryResult, J as ScoreComponents, K as SearchMode, S as ServerErrorCode, d as ServerErrorCodes, O as SortField, R as SortSpec, T as StringFilter, i as SuggestParams, j as SuggestResult, U as TermMatchPolicy, V as VectorMaintenanceResult, W as VectorQueryConfig } from './search-Dt4dkzpf.js';
-import { N as NarsilConfig } from './config-CzTJJili.js';
-export { A as AnalysisConfig, D as DurabilityConfig, I as IndexContext, a as InsertContext, b as NarsilPlugin, P as PartitionContext, R as RemoveContext, S as SearchContext, c as StaleAnalysis, U as UpdateContext, W as WorkerConfig, d as WorkerContext } from './config-CzTJJili.js';
-import { N as Narsil } from './engine-DEtRLYpB.js';
-export { a as NarsilEventMap } from './engine-DEtRLYpB.js';
+export { A as ArrayFilter, B as BatchResult, C as ClientErrorCode, a as ClientErrorCodes, k as ComparisonFilter, D as DocumentProjection, E as ErrorCode, b as ErrorCodes, F as FacetConfig, l as FacetResult, m as FieldFilter, n as FilterExpression, G as GeoFilter, o as GeoPolygonFilter, p as GeoRadiusFilter, q as GroupConfig, r as GroupReducer, s as GroupResult, H as HighlightConfig, t as HighlightMatch, u as Hit, v as HybridConfig, I as IndexInfo, f as IndexStats, L as ListParams, g as ListResult, w as ListedDocument, M as MemoryStats, N as NarsilError, c as NarsilErrorCode, P as PartitionStatsResult, h as PreflightResult, x as PresenceFilter, y as ProcessMemoryReport, z as QueryCoverage, Q as QueryParams, e as QueryResult, J as ScoreComponents, K as SearchMode, S as ServerErrorCode, d as ServerErrorCodes, O as SortField, R as SortSpec, T as StringFilter, i as SuggestParams, j as SuggestResult, U as TermMatchPolicy, V as VectorMaintenanceResult, W as VectorQueryConfig } from './search-DHuXwJYk.js';
+import { N as NarsilConfig } from './config-Byyl1QqH.js';
+export { A as AnalysisConfig, D as DurabilityConfig, I as IndexContext, a as InsertContext, b as NarsilPlugin, P as PartitionContext, R as RemoveContext, S as SearchContext, c as StaleAnalysis, U as UpdateContext, W as WorkerConfig, d as WorkerContext } from './config-Byyl1QqH.js';
+import { a as Narsil } from './engine-BE45D5ZG.js';
+export { N as NarsilEventMap } from './engine-BE45D5ZG.js';
 export { E as EmbeddingAdapter, I as InvalidationAdapter, a as InvalidationEvent, b as PartitionStatistics, P as PersistenceAdapter } from './adapters-79OIa4xm.js';
 
 /**

package/dist/index.mjs

@@ -1,6 +1,7 @@
-export { VERSION, createNarsil } from './chunk-OOA7OBLA.mjs';
-import './chunk-36ER4WCG.mjs';
-export { clearNormalizationCache, configureNormalizationCache, getLanguage, getNormalizationCacheSize, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer, resetNormalizationCache } from './chunk-RO4EFWE6.mjs';
+export { VERSION, createNarsil } from './chunk-MMSWEEZT.mjs';
+import './chunk-JQUL2T6I.mjs';
+import './chunk-WU2UZEVD.mjs';
+export { clearNormalizationCache, configureNormalizationCache, getLanguage, getNormalizationCacheSize, getStopWords, getTokenizer, hasStopWords, hasTokenizer, registerLanguage, registerStopWords, registerTokenizer, resetNormalizationCache } from './chunk-GRWFY2HI.mjs';
 import './chunk-TGP5M5R7.mjs';
 import './chunk-OBXS7OZM.mjs';
 export { isSimdAvailable } from './chunk-WDL632CN.mjs';
@@ -8,4 +9,4 @@ import './chunk-KMMJMDUA.mjs';
 import './chunk-U2BKYEC7.mjs';
 import './chunk-BFIH7OV5.mjs';
 import './chunk-WTONLDU3.mjs';
-export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes } from './chunk-EMI63EXP.mjs';
+export { ClientErrorCodes, ErrorCodes, NarsilError, ServerErrorCodes } from './chunk-GB2IIJJG.mjs';

package/dist/{options-BORJg5XB.d.ts → options-EXYFcem-.d.ts}

@@ -1,3 +1,4 @@
+import { C as ClusterNamespace } from './config-fLC4lbmg.js';
 import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
 import { h as TaskStore } from './tasks-CnMLpfk-.js';
 
@@ -194,6 +195,14 @@ interface ServerOptions {
      * is controlled elsewhere.
      */
     allowInsecure?: boolean;
+    /**
+     * The cluster-facing side of the node this server fronts, which is
+     * `node.cluster` on a {@link ClusterNode}. With it set, `/readyz` answers
+     * 200 only while the node reports `SERVING`, `/cluster` reports the
+     * topology, and `/indexes/:name/cluster` reports one index's allocation.
+     * Without it, both cluster routes answer 501.
+     */
+    cluster?: ClusterNamespace;
 }
 /**
  * The running HTTP server, as {@link createServer} returns it.

package/dist/persistence/durability/checkpoint-worker.d.ts

@@ -1,10 +1,12 @@
-import { P as PartitionConfig, b as ScoringMode, V as VectorIndexConfig } from '../../schema-emTQfEiX.js';
+import { P as PartitionConfig, b as ScoringMode, V as VectorIndexConfig } from '../../schema-ZRbk8BgH.js';
 import '../../adapters-79OIa4xm.js';
 
 interface IndexMetadata {
     indexName: string;
     /** The identity a cluster gave the index at creation; absent on a single engine. */
     indexUuid?: string;
+    /** The partitions this copy holds, which a cluster node answers a partition-stores request from. */
+    heldPartitions?: number[];
     schema: Record<string, string>;
     language: string;
     partitionCount: number;

package/dist/persistence/durability/checkpoint-worker.mjs

@@ -1,6 +1,7 @@
-import { createDurableDirectory, writeSegmentedCheckpoint } from '../../chunk-OOA7OBLA.mjs';
-import '../../chunk-36ER4WCG.mjs';
-import '../../chunk-RO4EFWE6.mjs';
+import { createDurableDirectory, writeSegmentedCheckpoint } from '../../chunk-MMSWEEZT.mjs';
+import '../../chunk-JQUL2T6I.mjs';
+import '../../chunk-WU2UZEVD.mjs';
+import '../../chunk-GRWFY2HI.mjs';
 import '../../chunk-TGP5M5R7.mjs';
 import '../../chunk-OBXS7OZM.mjs';
 import '../../chunk-WDL632CN.mjs';
@@ -8,7 +9,7 @@ import '../../chunk-KMMJMDUA.mjs';
 import '../../chunk-U2BKYEC7.mjs';
 import '../../chunk-BFIH7OV5.mjs';
 import '../../chunk-WTONLDU3.mjs';
-import '../../chunk-EMI63EXP.mjs';
+import '../../chunk-GB2IIJJG.mjs';
 
 // src/persistence/durability/rebuild.ts
 async function rebuildSnapshotFromDurable(root, metadata, targets, compactionThreshold) {

package/dist/react.d.ts

@@ -1,10 +1,10 @@
-import { N as NarsilError, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, Q as QueryParams, h as PreflightResult, e as QueryResult, i as SuggestParams, j as SuggestResult } from './search-Dt4dkzpf.js';
-export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './search-Dt4dkzpf.js';
+import { N as NarsilError, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, Q as QueryParams, h as PreflightResult, e as QueryResult, i as SuggestParams, j as SuggestResult } from './search-DHuXwJYk.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes } from './search-DHuXwJYk.js';
 import { e as TaskRecord, d as TaskProgress, b as ImportResult, c as TaskListQuery, T as TaskListPage } from './tasks-CnMLpfk-.js';
 export { I as ImportError, f as TaskStatus, g as TaskType } from './tasks-CnMLpfk-.js';
 import { ReactNode, ReactElement } from 'react';
-import { N as NarsilClient, I as ImportSource } from './client-DAJ_UHOa.js';
-import { A as AnyDocument } from './schema-emTQfEiX.js';
+import { N as NarsilClient, I as ImportSource } from './client-BobVnoIK.js';
+import { A as AnyDocument } from './schema-ZRbk8BgH.js';
 import './adapters-79OIa4xm.js';
 
 /**

package/dist/react.mjs

@@ -55,6 +55,8 @@ var ErrorCodes = {
   NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED",
   NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED",
   NODE_NOT_JOINED: "NODE_NOT_JOINED",
+  NODE_NOT_READY: "NODE_NOT_READY",
+  NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER",
   COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING",
   TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING",
   REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID",

package/dist/{schema-emTQfEiX.d.ts → schema-ZRbk8BgH.d.ts}

@@ -9,6 +9,7 @@ import { E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
  * @public
  */
 type AnyDocument = Record<string, unknown> & {
+    /** Identifier the engine stores this document under when you insert without passing one separately. */
     id?: string;
 };
 /**

package/dist/{search-Dt4dkzpf.d.ts → search-DHuXwJYk.d.ts}

@@ -1,4 +1,4 @@
-import { A as AnyDocument, S as SchemaDefinition, b as ScoringMode } from './schema-emTQfEiX.js';
+import { A as AnyDocument, S as SchemaDefinition, b as ScoringMode } from './schema-ZRbk8BgH.js';
 
 /**
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -64,6 +64,8 @@ declare const ErrorCodes: {
     readonly NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED";
     readonly NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED";
     readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
+    readonly NODE_NOT_READY: "NODE_NOT_READY";
+    readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
     readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
     readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
     readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
@@ -829,7 +831,9 @@ interface QueryParams {
  * @public
  */
 type DocumentProjection = boolean | {
+    /** Names the fields to keep, so every field left out of this list is dropped. */
     include?: string[];
+    /** Names the fields to drop, so every other field is kept. */
     exclude?: string[];
 };
 /**

package/dist/server.d.ts

@@ -1,11 +1,15 @@
-import { b as ServerOptions, N as NarsilServer } from './options-BORJg5XB.js';
-export { A as ASYNC_IMPORT_CAPABILITY, C as CorsOptions, E as ErrorEnvelope, O as OnRequestHook, R as REBUILD_ANALYSIS_CAPABILITY, c as RequestContext, d as RequestDenial, S as SERVER_CAPABILITIES, e as ServerLimits, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './options-BORJg5XB.js';
-import { N as Narsil } from './engine-DEtRLYpB.js';
+import { b as ServerOptions, N as NarsilServer } from './options-EXYFcem-.js';
+export { A as ASYNC_IMPORT_CAPABILITY, C as CorsOptions, E as ErrorEnvelope, O as OnRequestHook, R as REBUILD_ANALYSIS_CAPABILITY, c as RequestContext, d as RequestDenial, S as SERVER_CAPABILITIES, e as ServerLimits, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './options-EXYFcem-.js';
+import { a as Narsil } from './engine-BE45D5ZG.js';
 import { h as TaskStore, e as TaskRecord, d as TaskProgress, b as ImportResult } from './tasks-CnMLpfk-.js';
 export { C as CapabilitiesResponse, a as CreateIndexEmbedding, i as CreateIndexRequest, H as HttpIndexConfig, I as ImportError, T as TaskListPage, c as TaskListQuery, f as TaskStatus, g as TaskType } from './tasks-CnMLpfk-.js';
-export { d as ServerErrorCodes } from './search-Dt4dkzpf.js';
+export { d as ServerErrorCodes } from './search-DHuXwJYk.js';
+import './config-fLC4lbmg.js';
+import './config-Byyl1QqH.js';
 import './adapters-79OIa4xm.js';
-import './schema-emTQfEiX.js';
+import './schema-ZRbk8BgH.js';
+import './types-B5Tsaalz.js';
+import './types-D5OwhtsQ.js';
 
 /**
  * Wraps a Narsil engine in an HTTP server. The caller builds and owns the engine

package/dist/server.mjs

@@ -1,5 +1,6 @@
-import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-EMI63EXP.mjs';
-export { ServerErrorCodes } from './chunk-EMI63EXP.mjs';
+import { validateIndexName } from './chunk-WU2UZEVD.mjs';
+import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-GB2IIJJG.mjs';
+export { ServerErrorCodes } from './chunk-GB2IIJJG.mjs';
 import { randomUUID } from 'crypto';
 
 // src/server/capabilities.ts
@@ -117,6 +118,8 @@ var STATUS_BY_CODE = {
   CONTROLLER_NOT_ACTIVE: 503,
   NODE_ALREADY_JOINED: 409,
   NODE_NOT_JOINED: 503,
+  NODE_NOT_READY: 503,
+  NODE_NOT_CONTROLLER: 503,
   NODE_BOOTSTRAP_FAILED: 503,
   COORDINATOR_DEPENDENCY_MISSING: 500,
   SNAPSHOT_SYNC_UNAUTHORIZED: 403,
@@ -649,6 +652,79 @@ function createCapabilitiesHandler() {
   return { report };
 }
 
+// src/server/handlers/cluster.ts
+function requireCluster(deps) {
+  if (deps.cluster === void 0) {
+    throw new NarsilError(
+      ErrorCodes.CLUSTER_OPERATION_UNSUPPORTED,
+      "This server fronts a single engine, so it reports no cluster",
+      {}
+    );
+  }
+  return deps.cluster;
+}
+function describeNode(cluster) {
+  return { ...cluster.getNodeInfo(), readiness: cluster.getReadiness(), isController: cluster.isControllerActive() };
+}
+function malformedIndexName(indexName) {
+  try {
+    validateIndexName(indexName);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+function createClusterHandlers(deps) {
+  async function topology(ctx) {
+    try {
+      const cluster = requireCluster(deps);
+      const [nodes, controllerNodeId] = await Promise.all([cluster.listNodes(), cluster.getControllerNodeId()]);
+      respondJson(ctx, {
+        node: describeNode(cluster),
+        controllerNodeId,
+        nodes: nodes.map((node) => ({ nodeId: node.nodeId, address: node.address, roles: [...node.roles] }))
+      });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  async function allocation(ctx) {
+    try {
+      const cluster = requireCluster(deps);
+      const indexName = ctx.params[0] ?? "";
+      const malformed = malformedIndexName(indexName);
+      if (malformed !== null) {
+        badRequest(ctx.res, malformed, { indexName });
+        return;
+      }
+      const table = await cluster.getAllocation(indexName);
+      if (table === null) {
+        respondJson(ctx, { indexName, allocated: false, version: null, partitions: [] });
+        return;
+      }
+      const partitions = [];
+      for (const [partitionId, assignment] of table.assignments) {
+        partitions.push({
+          partitionId,
+          state: assignment.state,
+          primary: assignment.primary,
+          primaryTerm: assignment.primaryTerm,
+          commitPoint: assignment.commitPoint,
+          replicas: [...assignment.replicas],
+          inSyncSet: [...assignment.inSyncSet],
+          lastHolders: [...assignment.lastHolders ?? []],
+          unassignedReason: assignment.unassignedReason ?? null
+        });
+      }
+      partitions.sort((left, right) => left.partitionId - right.partitionId);
+      respondJson(ctx, { indexName, allocated: partitions.length > 0, version: table.version, partitions });
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
+  return { topology, allocation };
+}
+
 // src/server/handlers/documents.ts
 function createDocumentHandlers(deps) {
   const { engine, limits } = deps;
@@ -804,11 +880,25 @@ function createHealthHandlers(deps) {
     respondJson(ctx, { status: "ok" });
   }
   function readyz(ctx) {
-    if (deps.isReady()) {
-      respondJson(ctx, { status: "ready" });
-    } else {
-      respondJson(ctx, { status: "unavailable" }, 503);
+    const cluster = deps.cluster;
+    if (cluster === void 0) {
+      if (deps.isReady()) {
+        respondJson(ctx, { status: "ready" });
+      } else {
+        respondJson(ctx, { status: "unavailable" }, 503);
+      }
+      return;
     }
+    const readiness = cluster.getReadiness();
+    const ready = deps.isReady() && readiness === "SERVING";
+    respondJson(
+      ctx,
+      {
+        status: ready ? "ready" : "unavailable",
+        cluster: describeNode(cluster)
+      },
+      ready ? 200 : 503
+    );
   }
   return { livez, readyz };
 }
@@ -1576,7 +1666,8 @@ var NarsilHttpServer = class {
       tasks: new TaskRegistry(taskStore, instanceId, limits.maxConcurrentTasks),
       limits,
       isReady: () => this.ready,
-      build: resolveBuild(options.build)
+      build: resolveBuild(options.build),
+      cluster: options.cluster
     };
   }
   async listen() {
@@ -1622,6 +1713,7 @@ var NarsilHttpServer = class {
     const search = createSearchHandlers(this.deps);
     const admin = createAdminHandlers(this.deps);
     const health = createHealthHandlers(this.deps);
+    const cluster = createClusterHandlers(this.deps);
     const version = createVersionHandler(this.deps);
     const capabilities = createCapabilitiesHandler();
     const importNdjson = createImportHandler(this.deps);
@@ -1641,6 +1733,7 @@ var NarsilHttpServer = class {
     app.get("/health", json(health.livez, { maxBytes: 0, skipHooks: true }));
     app.get("/version", json(version.report, { maxBytes: 0, skipHooks: true }));
     app.get("/capabilities", json(capabilities.report, { maxBytes: 0, skipHooks: true }));
+    app.get("/cluster", json(cluster.topology, { maxBytes: 0 }));
     app.get("/stats/memory", json(admin.memory, { maxBytes: 0 }));
     app.get("/tasks", json(admin.listTasks, { maxBytes: 0 }));
     app.get("/tasks/:id", json(admin.getTask, { paramCount: 1, maxBytes: 0 }));
@@ -1650,6 +1743,7 @@ var NarsilHttpServer = class {
     app.del("/indexes/:name", json(idx.drop, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/stats", json(idx.stats, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/partitions", json(idx.partitions, { paramCount: 1, maxBytes: 0 }));
+    app.get("/indexes/:name/cluster", json(cluster.allocation, { paramCount: 1, maxBytes: 0 }));
     app.post("/indexes/:name/_clear", json(idx.clear, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/count", json(doc.count, { paramCount: 1, maxBytes: 0 }));
     app.post("/indexes/:name/documents", json(doc.insert, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes }));

package/dist/{types-BhdINMtE.d.ts → types-B5Tsaalz.d.ts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './schema-emTQfEiX.js';
+import { S as SchemaDefinition } from './schema-ZRbk8BgH.js';
 
 /**
  * What a node does in a cluster. A node may hold several roles at once.
@@ -20,6 +20,19 @@ type NodeRole = 'data' | 'coordinator' | 'controller';
  * @public
  */
 type PartitionState = 'UNASSIGNED' | 'INITIALISING' | 'ACTIVE' | 'MIGRATING' | 'DECOMMISSIONING';
+/**
+ * Why a partition stays `UNASSIGNED` after the controller has asked its last holders for a copy.
+ *
+ * `HOLDER_OFFLINE` means a last holder has yet to register again, so the controller is still waiting for it.
+ * `HOLDER_UNREACHABLE` means a registered holder left the request unanswered or answered with a payload the
+ * controller could not read. `HOLDER_IDENTITY_MISMATCH` means a holder answered under a different index identity,
+ * so its copy holds the documents of an earlier index of the same name, or it keeps no copy of that name at all.
+ * `HOLDER_WITHOUT_DATA` means every holder answered under the coordinator's identity with a list that left the
+ * partition out.
+ *
+ * @public
+ */
+type UnassignedReason = 'HOLDER_OFFLINE' | 'HOLDER_UNREACHABLE' | 'HOLDER_IDENTITY_MISMATCH' | 'HOLDER_WITHOUT_DATA';
 /**
  * What one node has to offer, which the allocator weighs when it places
  * partitions.
@@ -67,12 +80,16 @@ interface PartitionAssignment {
     replicas: string[];
     /** These replicas are current enough to be promoted, which is the set a failover picks from. */
     inSyncSet: string[];
+    /** These nodes still hold a copy of a partition no node serves, and the field stays until the partition is `ACTIVE`. */
+    lastHolders?: string[];
     /** This says where the partition stands in its move between nodes. */
     state: PartitionState;
     /** This rises each time the primary changes, which is what makes a stale primary's writes detectable. */
     primaryTerm: number;
     /** The primary has acknowledged every sequence number up to here, so every in-sync replica holds them. */
     commitPoint: number;
+    /** Why the partition stays `UNASSIGNED`, which the controller records each time it asks the last holders. */
+    unassignedReason?: UnassignedReason;
 }
 /**
  * How one index's partitions are spread across the cluster.
@@ -323,4 +340,4 @@ interface ClusterCoordinator {
     shutdown(): Promise<void>;
 }
 
-export type { AllocationTable as A, ClusterCoordinator as C, NodeRole as N, PartitionAssignment as P, SchemaEvent as S, NodeCapacity as a, AllocationConstraints as b, AllocationEvent as c, NodeEvent as d, NodeRegistration as e, PartitionState as f };
+export type { AllocationTable as A, ClusterCoordinator as C, NodeRole as N, PartitionAssignment as P, SchemaEvent as S, UnassignedReason as U, NodeRegistration as a, NodeCapacity as b, AllocationConstraints as c, AllocationEvent as d, NodeEvent as e, PartitionState as f };