@delali/narsil 0.2.3-next.34 → 0.2.3-next.36

package/README.md

@@ -79,7 +79,7 @@ const results = await narsil.query('products', {
 })
 ```
 
-Every hit holds the document, its id, and its BM25 score. `results.count` reports how many documents matched in total, and `results.elapsed` reports the query time in milliseconds.
+Every hit holds the document, its id, and its BM25 score. `results.count` reports how many documents matched in total, `results.elapsed` reports the query time in milliseconds, and `results.coverage` reports how many partitions the search read, which is how you spot a cluster that answered from part of its data.
 
 ## Features
 
@@ -129,7 +129,7 @@ The [specification](../spec/) defines the `.nrsl` format, the analysis pipeline,
 
 ## Distribution
 
-`@delali/narsil/distribution` holds Narsil's multi-node cluster mode: nodes and roles, replication, coordinator adapters for etcd and in-process testing, TCP and gRPC transports with mutual TLS, and distributed query routing. A cluster node creates, drops, clears, writes, updates, searches, lists, counts, and suggests across every partition, and the [cluster example](examples/cluster) runs three node processes against etcd and survives a kill. The layer is experimental and its APIs change without notice, so pin an exact version before you depend on it. The [cluster guide](../../docs/cluster.md) covers the surface, and [`packages/spec/distribution`](../spec/distribution) specifies the contract every implementation follows.
+`@delali/narsil/distribution` holds Narsil's multi-node cluster mode: nodes and roles, replication, coordinator adapters for etcd and in-process testing, TCP and gRPC transports with mutual TLS, and distributed query routing. A cluster node creates, drops, clears, writes, updates, searches, lists, counts, and suggests across every partition, and the [cluster dashboard example](examples/cluster-dashboard) runs three nodes against etcd and shows what each partition does while you cut the links between them. The layer is experimental and its APIs change without notice, so pin an exact version before you depend on it. The [cluster guide](../../docs/cluster.md) covers the surface, and [`packages/spec/distribution`](../spec/distribution) specifies the contract every implementation follows.
 
 ## Search quality
 

package/dist/adapters/filesystem.mjs

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

package/dist/adapters/indexeddb.mjs

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

package/dist/{chunk-EMI63EXP.mjs → chunk-GB2IIJJG.mjs}

@@ -53,6 +53,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/{chunk-RO4EFWE6.mjs → chunk-GRWFY2HI.mjs}

@@ -3,7 +3,7 @@ import { createScalarQuantizer } from './chunk-OBXS7OZM.mjs';
 import { MAX_M, createVectorStore, createHNSWIndex, createOrdinalFilter, addToOrdinalFilter, removeFromOrdinalFilter, ordinalFilterValues, magnitude, createBoundedMaxHeap, toScore, euclideanDistance, dotProduct, cosineSimilarityWithMagnitudes, ordinalFilterHas, ABSENT_DOCUMENT_RANK } from './chunk-WDL632CN.mjs';
 import { compareCodePoints, compareComparableKeys, toComparableSortValue, readSortField, compareSortValues, compareComparableValues, SORT_VALUE_MAX_CODE_POINTS } from './chunk-BFIH7OV5.mjs';
 import { generateId, createRequestId } from './chunk-WTONLDU3.mjs';
-import { NarsilError, ErrorCodes, createNarsilError } from './chunk-EMI63EXP.mjs';
+import { NarsilError, ErrorCodes, createNarsilError } from './chunk-GB2IIJJG.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/schema/validator/shared.ts
@@ -552,6 +552,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) {
@@ -641,8 +644,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;
 }

package/dist/{chunk-36ER4WCG.mjs → chunk-JQUL2T6I.mjs}

@@ -58,7 +58,8 @@ var QueryMessageTypes = {
 var ClusterMessageTypes = {
   PING: "cluster.ping",
   PONG: "cluster.pong",
-  BOOTSTRAP_COMPLETE: "cluster.bootstrap_complete"
+  BOOTSTRAP_COMPLETE: "cluster.bootstrap_complete",
+  PARTITION_STORES: "cluster.partition_stores"
 };
 
 export { ClusterMessageTypes, DEFAULT_TRANSPORT_CONFIG, MAX_MESSAGE_SIZE_BYTES, QueryMessageTypes, ReplicationMessageTypes, TransportError, TransportErrorCodes };

package/dist/{chunk-GN7KF675.mjs → chunk-MMSWEEZT.mjs}

@@ -1,9 +1,10 @@
-import { ReplicationMessageTypes } from './chunk-36ER4WCG.mjs';
-import { getNestedValue, getLanguage, extractVectorFieldsFromSchema, createDirectExecutor, createPartitionRouter, clampRowCount, DEFAULT_PAGE_SIZE, validateSchema, validateVectorPromotion, collectQueryTermStats, createPartitionManager, createVectorIndex, flattenSchema, isTextFieldType, requireWithinResultWindow, normalizeSort, sortSignatureOf, requireSortableFields, fanOutQuery, applySorting, applyPagination, resolveProjection, tokenize, decodePageCursor, requireMatchingCursor, encodePageCursor, resolveIndexAnalysis, deserializePayloadV2, deserializePayloadV1, validateRequiredFields, mergePartitionStats, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, createPartitionIndex, fnv1a, createWorkerPool, validateDocument, validateDocumentStrict, createFrozenSegment, detectRuntime, serializeMetadata, isNodeMainThread, spawnNodeWorker, createSharedFrozenSegment, buildCompactedSegmentPayload, freezeSegmentShared, deserializeMetadata, isCompositePartition, kWayMerge } from './chunk-RO4EFWE6.mjs';
+import { ReplicationMessageTypes } from './chunk-JQUL2T6I.mjs';
+import { MAX_INDEX_NAME_LENGTH } from './chunk-WU2UZEVD.mjs';
+import { getNestedValue, getLanguage, extractVectorFieldsFromSchema, createDirectExecutor, createPartitionRouter, clampRowCount, DEFAULT_PAGE_SIZE, validateSchema, validateVectorPromotion, collectQueryTermStats, createPartitionManager, createVectorIndex, flattenSchema, isTextFieldType, requireWithinResultWindow, normalizeSort, sortSignatureOf, requireSortableFields, fanOutQuery, applySorting, applyPagination, resolveProjection, tokenize, decodePageCursor, requireMatchingCursor, encodePageCursor, resolveIndexAnalysis, deserializePayloadV2, deserializePayloadV1, validateRequiredFields, mergePartitionStats, fulltextMatches, mergeFacets, pruneStatsToQueryTerms, createPartitionIndex, fnv1a, createWorkerPool, validateDocument, validateDocumentStrict, createFrozenSegment, detectRuntime, isNodeMainThread, spawnNodeWorker, createSharedFrozenSegment, buildCompactedSegmentPayload, freezeSegmentShared, deserializeMetadata, isCompositePartition, serializeMetadata, kWayMerge } from './chunk-GRWFY2HI.mjs';
 import { crc32, crc32Init, crc32Update, crc32Final } from './chunk-KMMJMDUA.mjs';
 import { compareCodePoints, compareComparableKeys } from './chunk-BFIH7OV5.mjs';
 import { generateId, createRequestId, isValidWorkerResponse } from './chunk-WTONLDU3.mjs';
-import { ErrorCodes, NarsilError } from './chunk-EMI63EXP.mjs';
+import { ErrorCodes, NarsilError } from './chunk-GB2IIJJG.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/partitioning/rebalancer.ts
@@ -3751,6 +3752,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;
@@ -3803,6 +3805,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;
@@ -3960,6 +3971,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;
@@ -4007,14 +4021,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);
@@ -4071,6 +4087,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) {
@@ -4149,6 +4166,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) {
@@ -4183,6 +4209,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());
@@ -4197,14 +4226,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);
@@ -4297,6 +4328,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) {
@@ -4358,6 +4392,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,
@@ -5476,7 +5511,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({
@@ -5602,141 +5638,9 @@ function createEngineCore(config) {
     rebalanceCtx
   };
 }
-var INDEX_CONFIG_PREFIX = "_narsil/index/";
-var INDEX_CONFIG_SUFFIX = "/config";
-var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-var MAX_INDEX_NAME_LENGTH = 255;
-var MAX_PARTITION_COUNT = 65536;
-var MAX_REPLICATION_FACTOR = 255;
-function truncateForDisplay(value) {
-  const str = String(value);
-  if (str.length > 100) {
-    return `${str.slice(0, 100)}...`;
-  }
-  return str;
-}
-function validateIndexName(indexName) {
-  if (indexName.length === 0 || indexName.length > MAX_INDEX_NAME_LENGTH) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index name must be between 1 and ${MAX_INDEX_NAME_LENGTH} characters`,
-      { indexName: truncateForDisplay(indexName) }
-    );
-  }
-  if (indexName.includes("\0") || indexName.includes("/") || indexName.includes("\\") || indexName.includes("..")) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      "Index name contains forbidden characters (/, \\, .., or null bytes)",
-      { indexName: truncateForDisplay(indexName) }
-    );
-  }
-  if (!INDEX_NAME_PATTERN.test(indexName)) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      "Index name must start with an alphanumeric character and contain only alphanumeric characters, hyphens, underscores, or dots",
-      { indexName: truncateForDisplay(indexName) }
-    );
-  }
-}
-function isValidInteger(value) {
-  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value);
-}
-function indexConfigKey(indexName) {
-  return `${INDEX_CONFIG_PREFIX}${indexName}${INDEX_CONFIG_SUFFIX}`;
-}
-function isRecord2(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function validateDecodedMetadata(decoded, indexName) {
-  if (!isRecord2(decoded)) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' is not an object`,
-      { indexName }
-    );
-  }
-  if (typeof decoded.indexUuid !== "string" || decoded.indexUuid.length === 0 || decoded.indexUuid.length > 128) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' has invalid indexUuid`,
-      { indexName, received: truncateForDisplay(decoded.indexUuid) }
-    );
-  }
-  if (typeof decoded.indexName !== "string") {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' has invalid indexName`,
-      { indexName, received: truncateForDisplay(decoded.indexName) }
-    );
-  }
-  if (!isValidInteger(decoded.partitionCount) || decoded.partitionCount <= 0 || decoded.partitionCount > MAX_PARTITION_COUNT) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' has invalid partitionCount (must be an integer between 1 and ${MAX_PARTITION_COUNT})`,
-      { indexName, partitionCount: truncateForDisplay(decoded.partitionCount) }
-    );
-  }
-  if (!isValidInteger(decoded.replicationFactor) || decoded.replicationFactor < 0 || decoded.replicationFactor > MAX_REPLICATION_FACTOR) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' has invalid replicationFactor (must be an integer between 0 and ${MAX_REPLICATION_FACTOR})`,
-      { indexName, replicationFactor: truncateForDisplay(decoded.replicationFactor) }
-    );
-  }
-  if (!isRecord2(decoded.constraints)) {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' has invalid constraints`,
-      { indexName }
-    );
-  }
-  const constraints = decoded.constraints;
-  if (constraints.maxShardsPerNode !== void 0 && constraints.maxShardsPerNode !== null && typeof constraints.maxShardsPerNode !== "number") {
-    throw new NarsilError(
-      ErrorCodes.CONTROLLER_METADATA_INVALID,
-      `Index metadata for '${indexName}' has invalid maxShardsPerNode (must be a number or null)`,
-      { indexName, maxShardsPerNode: truncateForDisplay(constraints.maxShardsPerNode) }
-    );
-  }
-  return {
-    indexUuid: decoded.indexUuid,
-    indexName: decoded.indexName,
-    partitionCount: decoded.partitionCount,
-    replicationFactor: decoded.replicationFactor,
-    constraints: {
-      zoneAwareness: constraints.zoneAwareness === true,
-      zoneAttribute: typeof constraints.zoneAttribute === "string" ? constraints.zoneAttribute : "zone",
-      maxShardsPerNode: typeof constraints.maxShardsPerNode === "number" ? constraints.maxShardsPerNode : null
-    }
-  };
-}
-async function putIndexMetadata(coordinator, metadata) {
-  validateIndexName(metadata.indexName);
-  const key = indexConfigKey(metadata.indexName);
-  const encoded = encode(metadata);
-  const bytes = new Uint8Array(encoded);
-  if (await coordinator.compareAndSet(key, null, bytes)) {
-    return true;
-  }
-  const current = await coordinator.get(key);
-  if (current === null || current.byteLength > 0) {
-    return false;
-  }
-  return coordinator.compareAndSet(key, current, bytes);
-}
-async function getIndexMetadata(coordinator, indexName) {
-  validateIndexName(indexName);
-  const key = indexConfigKey(indexName);
-  const raw = await coordinator.get(key);
-  if (raw === null || raw.byteLength === 0) {
-    return null;
-  }
-  const decoded = decode(raw);
-  return validateDecodedMetadata(decoded, indexName);
-}
 
 // src/engine/validation.ts
-var INDEX_NAME_PATTERN2 = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 var MAX_DOC_ID_LENGTH = 512;
 var BATCH_CHUNK_SIZE = 1e3;
 var DEFAULT_LIMIT = DEFAULT_PAGE_SIZE;
@@ -5747,7 +5651,7 @@ function now() {
   }
   return Date.now();
 }
-function validateIndexName2(name) {
+function validateIndexName(name) {
   if (!name || name.length === 0) {
     throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "Index name must not be empty", { indexName: name });
   }
@@ -5761,7 +5665,7 @@ function validateIndexName2(name) {
       }
     );
   }
-  if (!INDEX_NAME_PATTERN2.test(name)) {
+  if (!INDEX_NAME_PATTERN.test(name)) {
     throw new NarsilError(
       ErrorCodes.INDEX_NOT_FOUND,
       `Index name "${name}" contains invalid characters; use alphanumeric, dots, hyphens, and underscores only`,
@@ -5828,7 +5732,7 @@ function clampOffset(offset) {
 // src/engine/index-lifecycle.ts
 async function createEngineIndex(core, config, name, indexConfig, indexUuid) {
   core.guardShutdown();
-  validateIndexName2(name);
+  validateIndexName(name);
   if (core.indexRegistry.has(name)) {
     throw new NarsilError(ErrorCodes.INDEX_ALREADY_EXISTS, `Index "${name}" already exists`, { indexName: name });
   }
@@ -5887,7 +5791,8 @@ async function createEngineIndex(core, config, name, indexConfig, indexUuid) {
     embeddingAdapter: resolvedEmbeddingAdapter,
     embeddingAdapterName,
     vectorFieldPaths: getVectorFieldPaths(indexConfig.schema),
-    indexUuid: indexUuid ?? null
+    indexUuid: indexUuid ?? null,
+    heldPartitions: null
   });
   if (core.durability) {
     await core.durability.manager.persistMetadata(name);
@@ -7697,8 +7602,8 @@ async function createSnapshot(manager, entry) {
   }
   const config = entry.config;
   const bm25 = config.bm25;
-  const { encode: encode10 } = await import('@msgpack/msgpack');
-  return encode10({
+  const { encode: encode9 } = await import('@msgpack/msgpack');
+  return encode9({
     version: 2,
     schema: config.schema,
     language: entry.language.name,
@@ -7733,10 +7638,10 @@ async function restoreFromSnapshot(indexName, data, deps) {
   if (!(data instanceof Uint8Array)) {
     throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Snapshot data must be a Uint8Array");
   }
-  const { decode: decode10 } = await import('@msgpack/msgpack');
+  const { decode: decode9 } = await import('@msgpack/msgpack');
   let decoded;
   try {
-    decoded = decode10(data);
+    decoded = decode9(data);
   } catch (err) {
     throw new NarsilError(
       ErrorCodes.DOC_VALIDATION_FAILED,
@@ -7817,7 +7722,8 @@ async function restoreFromSnapshot(indexName, data, deps) {
     embeddingAdapter,
     embeddingAdapterName: adapterName,
     vectorFieldPaths,
-    indexUuid: null
+    indexUuid: null,
+    heldPartitions: null
   });
   try {
     const manager = deps.requireManager(indexName);
@@ -8342,6 +8248,23 @@ function partitionsFor(manager, partitionIds) {
   }
   return partitions;
 }
+function coverageFor(manager, partitionIds) {
+  if (partitionIds === void 0) {
+    return {
+      totalPartitions: manager.partitionCount,
+      queriedPartitions: manager.partitionCount,
+      timedOutPartitions: 0,
+      failedPartitions: 0
+    };
+  }
+  const queriedPartitions = partitionsFor(manager, partitionIds).length;
+  return {
+    totalPartitions: partitionIds.length,
+    queriedPartitions,
+    timedOutPartitions: 0,
+    failedPartitions: partitionIds.length - queriedPartitions
+  };
+}
 function partitionsForVectorSearch(manager, vecIndex, partitionIds) {
   if (partitionIds === void 0) {
     return void 0;
@@ -8803,7 +8726,8 @@ async function executeQuery(params, context) {
     elapsed,
     cursor: nextCursor,
     facets,
-    groups
+    groups,
+    coverage: coverageFor(manager, context.partitionIds)
   };
 }
 async function executePreflight(params, context) {
@@ -9329,4 +9253,4 @@ async function createNarsil(config) {
 // src/index.ts
 var VERSION = "0.1.0";
 
-export { DEFAULT_SUGGEST_LIMIT, MAX_INDEX_NAME_LENGTH, MAX_PARTITION_COUNT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, VERSION, WIRE_BATCH_BUDGET, applyDeleteEntry, applyIndexEntry, chunkByBudget, clampLimit, computeEntryChecksum, createAckMessage, createDurableDirectory, createEngineCore, createEngineIndex, createEntryBatchMessage, createEntryMessage, createForwardBatchMessage, createForwardBatchResultMessage, createForwardMessage, createInsyncAddMessage, createInsyncConfirmMessage, createInsyncRemoveMessage, createNarsil, createNarsilFromCore, getIndexMetadata, indexConfigKey, now, putIndexMetadata, runEngineListDocuments, runEnginePreflight, runEngineQuery, runEngineQueryStats, runEngineSuggest, validateAckPayload, validateEntryBatchPayload, validateEntryPayload, validateForwardBatchPayload, validateForwardBatchResultPayload, validateIndexName, validateInsyncConfirmPayload, validateReplicationEntry, writeSegmentedCheckpoint };
+export { DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, MAX_SUGGEST_SCATTER_LIMIT, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, VERSION, WIRE_BATCH_BUDGET, applyDeleteEntry, applyIndexEntry, chunkByBudget, clampLimit, computeEntryChecksum, createAckMessage, createDurableDirectory, createEngineCore, createEngineIndex, createEntryBatchMessage, createEntryMessage, createForwardBatchMessage, createForwardBatchResultMessage, createForwardMessage, createInsyncAddMessage, createInsyncConfirmMessage, createInsyncRemoveMessage, createNarsil, createNarsilFromCore, now, runEngineListDocuments, runEnginePreflight, runEngineQuery, runEngineQueryStats, runEngineSuggest, validateAckPayload, validateEntryBatchPayload, validateEntryPayload, validateForwardBatchPayload, validateForwardBatchResultPayload, validateInsyncConfirmPayload, validateReplicationEntry, writeSegmentedCheckpoint };

package/dist/{chunk-GODECMDT.mjs → chunk-PM52SMBT.mjs}

@@ -1,4 +1,4 @@
-import { MAX_MESSAGE_SIZE_BYTES, TransportError, TransportErrorCodes } from './chunk-36ER4WCG.mjs';
+import { MAX_MESSAGE_SIZE_BYTES, TransportError, TransportErrorCodes } from './chunk-JQUL2T6I.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/distribution/transport/tcp/types.ts

package/dist/chunk-WU2UZEVD.mjs

@@ -0,0 +1,137 @@
+import { NarsilError, ErrorCodes } from './chunk-GB2IIJJG.mjs';
+import { encode, decode } from '@msgpack/msgpack';
+
+var INDEX_CONFIG_PREFIX = "_narsil/index/";
+var INDEX_CONFIG_SUFFIX = "/config";
+var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var MAX_INDEX_NAME_LENGTH = 255;
+var MAX_PARTITION_COUNT = 65536;
+var MAX_REPLICATION_FACTOR = 255;
+function truncateForDisplay(value) {
+  const str = String(value);
+  if (str.length > 100) {
+    return `${str.slice(0, 100)}...`;
+  }
+  return str;
+}
+function validateIndexName(indexName) {
+  if (indexName.length === 0 || indexName.length > MAX_INDEX_NAME_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index name must be between 1 and ${MAX_INDEX_NAME_LENGTH} characters`,
+      { indexName: truncateForDisplay(indexName) }
+    );
+  }
+  if (indexName.includes("\0") || indexName.includes("/") || indexName.includes("\\") || indexName.includes("..")) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      "Index name contains forbidden characters (/, \\, .., or null bytes)",
+      { indexName: truncateForDisplay(indexName) }
+    );
+  }
+  if (!INDEX_NAME_PATTERN.test(indexName)) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      "Index name must start with an alphanumeric character and contain only alphanumeric characters, hyphens, underscores, or dots",
+      { indexName: truncateForDisplay(indexName) }
+    );
+  }
+}
+function isValidInteger(value) {
+  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value);
+}
+function indexConfigKey(indexName) {
+  return `${INDEX_CONFIG_PREFIX}${indexName}${INDEX_CONFIG_SUFFIX}`;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validateDecodedMetadata(decoded, indexName) {
+  if (!isRecord(decoded)) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' is not an object`,
+      { indexName }
+    );
+  }
+  if (typeof decoded.indexUuid !== "string" || decoded.indexUuid.length === 0 || decoded.indexUuid.length > 128) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' has invalid indexUuid`,
+      { indexName, received: truncateForDisplay(decoded.indexUuid) }
+    );
+  }
+  if (typeof decoded.indexName !== "string") {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' has invalid indexName`,
+      { indexName, received: truncateForDisplay(decoded.indexName) }
+    );
+  }
+  if (!isValidInteger(decoded.partitionCount) || decoded.partitionCount <= 0 || decoded.partitionCount > MAX_PARTITION_COUNT) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' has invalid partitionCount (must be an integer between 1 and ${MAX_PARTITION_COUNT})`,
+      { indexName, partitionCount: truncateForDisplay(decoded.partitionCount) }
+    );
+  }
+  if (!isValidInteger(decoded.replicationFactor) || decoded.replicationFactor < 0 || decoded.replicationFactor > MAX_REPLICATION_FACTOR) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' has invalid replicationFactor (must be an integer between 0 and ${MAX_REPLICATION_FACTOR})`,
+      { indexName, replicationFactor: truncateForDisplay(decoded.replicationFactor) }
+    );
+  }
+  if (!isRecord(decoded.constraints)) {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' has invalid constraints`,
+      { indexName }
+    );
+  }
+  const constraints = decoded.constraints;
+  if (constraints.maxShardsPerNode !== void 0 && constraints.maxShardsPerNode !== null && typeof constraints.maxShardsPerNode !== "number") {
+    throw new NarsilError(
+      ErrorCodes.CONTROLLER_METADATA_INVALID,
+      `Index metadata for '${indexName}' has invalid maxShardsPerNode (must be a number or null)`,
+      { indexName, maxShardsPerNode: truncateForDisplay(constraints.maxShardsPerNode) }
+    );
+  }
+  return {
+    indexUuid: decoded.indexUuid,
+    indexName: decoded.indexName,
+    partitionCount: decoded.partitionCount,
+    replicationFactor: decoded.replicationFactor,
+    constraints: {
+      zoneAwareness: constraints.zoneAwareness === true,
+      zoneAttribute: typeof constraints.zoneAttribute === "string" ? constraints.zoneAttribute : "zone",
+      maxShardsPerNode: typeof constraints.maxShardsPerNode === "number" ? constraints.maxShardsPerNode : null
+    }
+  };
+}
+async function putIndexMetadata(coordinator, metadata) {
+  validateIndexName(metadata.indexName);
+  const key = indexConfigKey(metadata.indexName);
+  const encoded = encode(metadata);
+  const bytes = new Uint8Array(encoded);
+  if (await coordinator.compareAndSet(key, null, bytes)) {
+    return true;
+  }
+  const current = await coordinator.get(key);
+  if (current === null || current.byteLength > 0) {
+    return false;
+  }
+  return coordinator.compareAndSet(key, current, bytes);
+}
+async function getIndexMetadata(coordinator, indexName) {
+  validateIndexName(indexName);
+  const key = indexConfigKey(indexName);
+  const raw = await coordinator.get(key);
+  if (raw === null || raw.byteLength === 0) {
+    return null;
+  }
+  const decoded = decode(raw);
+  return validateDecodedMetadata(decoded, indexName);
+}
+
+export { MAX_INDEX_NAME_LENGTH, MAX_PARTITION_COUNT, getIndexMetadata, indexConfigKey, putIndexMetadata, validateIndexName };

package/dist/{client-DQHB_swQ.d.ts → client-BobVnoIK.d.ts}

@@ -1,6 +1,6 @@
+import { V as VectorMaintenanceResult, M as MemoryStats, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult } from './search-DHuXwJYk.js';
+import { P as PartitionConfig, A as AnyDocument, a as InsertOptions } from './schema-ZRbk8BgH.js';
 import { e as TaskRecord, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-CnMLpfk-.js';
-import { P as PartitionConfig, A as AnyDocument, a as InsertOptions } from './schema-emTQfEiX.js';
-import { V as VectorMaintenanceResult, M as MemoryStats, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, i as SuggestParams, j as SuggestResult } from './search-CQ-9bKxo.js';
 
 /**
  * This is the `fetch` implementation the client sends every request through.