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

package/dist/distribution.mjs

@@ -1,7 +1,7 @@
-import { createEngineCore, createNarsilFromCore, runEngineQueryStats, runEngineListDocuments, runEngineSuggest, runEnginePreflight, runEngineQuery, createEngineIndex, applyIndexEntry, applyDeleteEntry, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, now, validateEntryBatchPayload, createAckMessage, validateEntryPayload, validateForwardBatchPayload, createForwardBatchResultMessage, clampLimit, createForwardBatchMessage, validateForwardBatchResultPayload, createForwardMessage, validateReplicationEntry, MAX_SUGGEST_SCATTER_LIMIT, chunkByBudget, WIRE_BATCH_BUDGET, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, createEntryMessage, computeEntryChecksum, createEntryBatchMessage, createInsyncConfirmMessage, validateAckPayload, createInsyncRemoveMessage, validateInsyncConfirmPayload, createInsyncAddMessage } from './chunk-MMSWEEZT.mjs';
+import { createEngineCore, createNarsilFromCore, runEngineQueryStats, runEngineListDocuments, runEngineSuggest, runEnginePreflight, runEngineQuery, createEngineIndex, applyIndexEntry, applyDeleteEntry, DEFAULT_SUGGEST_LIMIT, MAX_SUGGEST_LIMIT, now, listBindingOf, validateEntryBatchPayload, createAckMessage, validateEntryPayload, validateForwardBatchPayload, createForwardBatchResultMessage, queryBindingOf, foldGroupReducer, clampLimit, createForwardBatchMessage, validateForwardBatchResultPayload, createForwardMessage, validateReplicationEntry, MAX_SUGGEST_SCATTER_LIMIT, chunkByBudget, WIRE_BATCH_BUDGET, computeEntryChecksum, dedupePinnedEntries, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, createEntryMessage, createEntryBatchMessage, createInsyncConfirmMessage, validateAckPayload, createInsyncRemoveMessage, validateInsyncConfirmPayload, createInsyncAddMessage } from './chunk-WASNWIEK.mjs';
 import { ReplicationMessageTypes, TransportErrorCodes, ClusterMessageTypes, QueryMessageTypes, TransportError, MAX_MESSAGE_SIZE_BYTES } from './chunk-JQUL2T6I.mjs';
-import { validateIndexName, indexConfigKey, putIndexMetadata, getIndexMetadata, MAX_PARTITION_COUNT, MAX_INDEX_NAME_LENGTH } from './chunk-WU2UZEVD.mjs';
-import { deserializePayloadV2, createPartitionIndex, resolveProjection, clampRowCount, sortSignatureOf, requireMatchingCursor, decodePageCursor, normalizeSort, encodePageCursor, applyProjection, readSortValues, getLanguage, DEFAULT_PAGE_SIZE, requireWithinResultWindow, fnv1a, FILTER_EXPRESSION_KEYS, MAX_CURSOR_LENGTH, mergePartitionStats, FIELD_FILTER_OPERATORS, MAX_NESTING_DEPTH } from './chunk-GRWFY2HI.mjs';
+import { validateIndexName, indexConfigKey, putIndexMetadata, getIndexMetadata, MAX_PARTITION_COUNT, MAX_INDEX_NAME_LENGTH } from './chunk-XWICBGYT.mjs';
+import { deserializePayloadV2, createPartitionIndex, resolveProjection, clampRowCount, sortSignatureOf, requireMatchingCursor, decodePageCursor, normalizeSort, encodePageCursor, applyProjection, readSortValues, getLanguage, DEFAULT_PAGE_SIZE, requireWithinResultWindow, fnv1a, FILTER_EXPRESSION_KEYS, MAX_CURSOR_LENGTH, mergePartitionStats, RESULT_WINDOW, FIELD_FILTER_OPERATORS, MAX_NESTING_DEPTH } from './chunk-XNCJFU2E.mjs';
 import './chunk-TGP5M5R7.mjs';
 import './chunk-OBXS7OZM.mjs';
 import './chunk-WDL632CN.mjs';
@@ -9,7 +9,7 @@ import { crc32 } from './chunk-KMMJMDUA.mjs';
 import './chunk-U2BKYEC7.mjs';
 import { compareCodePoints, toComparableSortValue, compareComparableKeys, compareSortValues } from './chunk-BFIH7OV5.mjs';
 import { generateId } from './chunk-WTONLDU3.mjs';
-import { ErrorCodes, NarsilError, describeError } from './chunk-GB2IIJJG.mjs';
+import { ErrorCodes, NarsilError, describeError } from './chunk-P4ELXVJQ.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/distribution/cluster/controller/types.ts
@@ -4618,7 +4618,7 @@ function batchBytes(entries) {
 function replicaHasFallenOutOfRetention(log, cursor) {
   const oldest = log.oldestSeqNo;
   if (oldest === void 0) {
-    return false;
+    return cursor.appliedSeqNo < log.localLogEnd;
   }
   return cursor.appliedSeqNo + 1 < oldest;
 }
@@ -4844,473 +4844,766 @@ async function writeHeldPartitions(core, indexName, next, indexesBehindOnDisk) {
   indexesBehindOnDisk.delete(indexName);
 }
 
-// src/distribution/cluster-node/local-engine.ts
-async function createClusterLocalEngine(config) {
-  const core = createEngineCore(config);
-  if (core.durability !== null) {
-    await core.durability.manager.recover();
-  }
-  if (core.invalidation !== null) {
-    await core.invalidation.start();
-  }
-  await core.analysisRebuild.reviewStaleIndexes();
-  const engine = createNarsilFromCore(core, config);
-  const heldPartitions = createHeldPartitionRecord(core);
-  return Object.assign(engine, {
-    createIndexWithUuid: (name, indexConfig, indexUuid) => createEngineIndex(core, config, name, indexConfig, indexUuid),
-    indexUuidOf: (indexName) => core.indexRegistry.get(indexName)?.indexUuid,
-    stampIndexUuid: (indexName, indexUuid) => stampIndexUuid(core, indexName, indexUuid),
-    highestPersistedSeqNoOf: (indexName, partitionId) => core.durability?.manager.highestPersistedSeqNo(indexName, partitionId) ?? 0,
-    heldPartitionsOf: (indexName) => heldPartitions.held(indexName),
-    recordHeldPartition: (indexName, partitionId) => heldPartitions.record(indexName, partitionId),
-    forgetHeldPartition: (indexName, partitionId) => heldPartitions.forget(indexName, partitionId),
-    applyReplicationEntry: (entry) => applyReplicationEntry(core, entry),
-    serializeReplicationPartition: (indexName, partitionId) => serializeReplicationPartition(core, indexName, partitionId),
-    restoreReplicationPartition: (indexName, partitionId, bytes, schema, partitionCount) => restoreReplicationPartition(core, engine, indexName, partitionId, bytes, schema, partitionCount),
-    queryPartitions: (indexName, params, partitionIds, globalStats) => runEngineQuery(core, indexName, params, { partitionIds, globalStats }),
-    preflightPartitions: (indexName, params, partitionIds) => runEnginePreflight(core, indexName, params, { partitionIds }),
-    suggestPartitions: (indexName, params, partitionIds) => runEngineSuggest(core, indexName, params, partitionIds),
-    listPartitions: (indexName, params, partitionIds) => runEngineListDocuments(core, indexName, params, partitionIds),
-    collectQueryStats: (indexName, terms, partitionIds) => runEngineQueryStats(core, indexName, terms, partitionIds)
-  });
-}
-async function stampIndexUuid(core, indexName, indexUuid) {
-  const entry = core.indexRegistry.get(indexName);
-  if (entry === void 0 || entry.indexUuid === indexUuid) {
-    return;
-  }
-  core.indexRegistry.set(indexName, { ...entry, indexUuid });
-  if (core.durability !== null) {
-    await core.durability.manager.persistMetadata(indexName);
-  }
-}
-async function serializeReplicationPartition(core, indexName, partitionId) {
-  core.guardShutdown();
-  return core.requireManager(indexName).serializePartitionToBytes(partitionId);
-}
-async function restoreReplicationPartition(core, engine, indexName, partitionId, bytes, schema, partitionCount) {
-  core.guardShutdown();
-  validatePartitionRestoreTarget(indexName, partitionId, partitionCount);
-  let partition;
-  try {
-    partition = deserializePayloadV2(bytes);
-  } catch (err) {
-    const cause = err instanceof Error ? err.message : String(err);
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, `partition snapshot decode failed: ${cause}`, {
-      indexName,
-      partitionId,
-      cause
-    });
-  }
-  validatePartitionSnapshotPayload(indexName, partitionId, partitionCount, schema, partition);
-  const trackPositions = core.indexRegistry.get(indexName)?.config.trackPositions ?? true;
-  createPartitionIndex(partitionId, trackPositions).deserialize(partition, schema);
-  const restoreIndex = await ensureReplicationIndex(core, engine, indexName, schema, partition.language, partitionCount);
-  if (restoreIndex.created) {
-    await core.orchestrator.replicateToWorkers({
-      type: "createIndex",
-      indexName,
-      config: restoreIndex.config,
-      requestId: `replicate-partition-index-${indexName}`
-    });
-  }
-  const manager = core.requireManager(indexName);
-  manager.deserializePartition(partitionId, partition);
-  await core.orchestrator.replicateToWorkers({
-    type: "deserialize",
-    indexName,
-    partitionId,
-    data: partition,
-    requestId: `replicate-partition-restore-${indexName}-${partitionId}`
-  });
-}
-function validatePartitionRestoreTarget(indexName, partitionId, partitionCount) {
-  if (!Number.isInteger(partitionId) || partitionId < 0) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partitionId must be a non-negative integer", {
-      indexName,
-      partitionId
-    });
-  }
-  if (!Number.isInteger(partitionCount) || partitionCount <= 0 || partitionCount > MAX_PARTITION_COUNT) {
-    throw new NarsilError(
-      ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED,
-      `partitionCount must be an integer between 1 and ${MAX_PARTITION_COUNT}`,
-      { indexName, partitionCount }
-    );
-  }
-  if (partitionId >= partitionCount) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partitionId is outside partitionCount", {
-      indexName,
-      partitionId,
-      partitionCount
-    });
-  }
+// src/distribution/replication/types.ts
+var DEFAULT_LOG_RETENTION_BYTES = 268435456;
+
+// src/distribution/replication/log.ts
+var ENTRY_FIXED_OVERHEAD_BYTES2 = 40;
+function estimateEntrySize(entry) {
+  return ENTRY_FIXED_OVERHEAD_BYTES2 + entry.indexName.length + entry.documentId.length + (entry.document?.byteLength ?? 0);
 }
-function validatePartitionSnapshotPayload(indexName, partitionId, partitionCount, schema, partition) {
-  if (partition.indexName !== indexName) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot indexName mismatch", {
-      expectedIndexName: indexName,
-      receivedIndexName: partition.indexName
-    });
-  }
-  if (partition.partitionId !== partitionId) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot partitionId mismatch", {
-      indexName,
-      expectedPartitionId: partitionId,
-      receivedPartitionId: partition.partitionId
-    });
-  }
-  if (partition.totalPartitions !== partitionCount) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot partition count mismatch", {
-      indexName,
-      partitionId,
-      expectedPartitionCount: partitionCount,
-      receivedPartitionCount: partition.totalPartitions
-    });
-  }
-  const expectedSchema = flattenSchema(schema);
-  for (const [field, expectedType] of Object.entries(expectedSchema)) {
-    if (partition.schema[field] !== expectedType) {
-      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot schema mismatch", {
-        indexName,
-        partitionId,
-        field,
-        expected: expectedType,
-        received: partition.schema[field] ?? "(absent)"
-      });
-    }
+var computeChecksum = computeEntryChecksum;
+function createReplicationLog(partitionId, config) {
+  const retentionBytes = config?.logRetentionBytes ?? DEFAULT_LOG_RETENTION_BYTES;
+  let nextSeqNo = config?.startSeqNo ?? 1;
+  let localLogEnd = nextSeqNo - 1;
+  let localLogEndPrimaryTerm = config?.lastPrimaryTerm ?? 0;
+  let commitPoint = nextSeqNo - 1;
+  let entries = [];
+  let headIndex = 0;
+  let totalSizeBytes = 0;
+  function liveCount() {
+    return entries.length - headIndex;
   }
-  for (const field of Object.keys(partition.schema)) {
-    if (!(field in expectedSchema)) {
-      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot schema contains extra field", {
-        indexName,
-        partitionId,
-        field
-      });
+  function compact() {
+    if (headIndex > 0) {
+      entries = entries.slice(headIndex);
+      headIndex = 0;
     }
   }
-}
-async function ensureReplicationIndex(core, engine, indexName, schema, languageName, partitionCount) {
-  const language = getLanguage(languageName);
-  const existing = core.indexRegistry.get(indexName);
-  let created = false;
-  if (existing === void 0) {
-    const indexConfig = {
-      schema,
-      language: language.name,
-      partitions: { maxPartitions: partitionCount }
-    };
-    try {
-      await engine.createIndex(indexName, indexConfig);
-      created = true;
-    } catch (err) {
-      if (!(err instanceof NarsilError) || err.code !== ErrorCodes.INDEX_ALREADY_EXISTS) {
-        throw err;
+  function findIndexBySeqNo(seqNo) {
+    let low = headIndex;
+    let high = entries.length - 1;
+    while (low <= high) {
+      const mid = low + high >>> 1;
+      const midSeqNo = entries[mid].seqNo;
+      if (midSeqNo < seqNo) {
+        low = mid + 1;
+      } else if (midSeqNo > seqNo) {
+        high = mid - 1;
+      } else {
+        return mid;
       }
     }
+    return low;
   }
-  const entry = core.requireIndex(indexName);
-  if (entry.language.name !== language.name) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot language mismatch", {
-      indexName,
-      expectedLanguage: entry.language.name,
-      receivedLanguage: language.name
-    });
-  }
-  validateExistingSchema(indexName, schema, entry.config.schema);
-  const manager = core.requireManager(indexName);
-  if (manager.partitionCount > partitionCount) {
-    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "local index has more partitions than allocation", {
-      indexName,
-      localPartitionCount: manager.partitionCount,
-      allocationPartitionCount: partitionCount
-    });
-  }
-  if (entry.config.partitions === void 0) {
-    entry.config.partitions = { maxPartitions: partitionCount };
-  } else if ((entry.config.partitions.maxPartitions ?? manager.partitionCount) < partitionCount) {
-    entry.config.partitions.maxPartitions = partitionCount;
+  function evictOldEntries() {
+    while (liveCount() > 0 && totalSizeBytes > retentionBytes) {
+      totalSizeBytes -= estimateEntrySize(entries[headIndex]);
+      entries[headIndex] = null;
+      headIndex += 1;
+    }
+    if (totalSizeBytes < 0) {
+      totalSizeBytes = 0;
+    }
+    if (headIndex >= 256 || headIndex > liveCount()) {
+      compact();
+    }
   }
-  while (manager.partitionCount < partitionCount) {
-    manager.addPartition();
+  function assertEntryFitsRetention(entry) {
+    const entrySize = ENTRY_FIXED_OVERHEAD_BYTES2 + entry.indexName.length + entry.documentId.length + (entry.document?.byteLength ?? 0);
+    if (entrySize > retentionBytes) {
+      throw new NarsilError(
+        ErrorCodes.REPLICATION_LOG_FULL,
+        `Replication log entry of ${entrySize} bytes exceeds the log retention limit of ${retentionBytes} bytes and cannot be buffered`,
+        { partitionId, entrySize, retentionBytes, seqNo: entry.seqNo }
+      );
+    }
   }
-  return { config: entry.config, created };
-}
-function validateExistingSchema(indexName, expected, actual) {
-  const expectedSchema = flattenSchema(expected);
-  const actualSchema = flattenSchema(actual);
-  for (const [field, expectedType] of Object.entries(expectedSchema)) {
-    if (actualSchema[field] !== expectedType) {
-      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "local index schema mismatch", {
-        indexName,
-        field,
-        expected: expectedType,
-        received: actualSchema[field] ?? "(absent)"
-      });
+  function storeEntry(entry) {
+    entries.push(entry);
+    if (entry.seqNo >= localLogEnd) {
+      localLogEnd = entry.seqNo;
+      localLogEndPrimaryTerm = entry.primaryTerm;
     }
+    totalSizeBytes += estimateEntrySize(entry);
+    evictOldEntries();
+    return { ...entry };
   }
-  for (const field of Object.keys(actualSchema)) {
-    if (!(field in expectedSchema)) {
-      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "local index schema contains extra field", {
-        indexName,
-        field
-      });
+  function readEntry(seqNo) {
+    if (liveCount() === 0) return void 0;
+    const idx = findIndexBySeqNo(seqNo);
+    if (idx < entries.length && entries[idx].seqNo === seqNo) {
+      return { ...entries[idx] };
     }
+    return void 0;
   }
-}
-function flattenSchema(schema) {
-  const flat = {};
-  flattenSchemaInto(schema, "", flat);
-  return flat;
-}
-function flattenSchemaInto(schema, prefix, flat) {
-  for (const [field, value] of Object.entries(schema)) {
-    const path = prefix.length === 0 ? field : `${prefix}.${field}`;
-    if (isNestedSchema(value)) {
-      flattenSchemaInto(value, path, flat);
-      continue;
-    }
-    flat[path] = value;
+  function verifyEntryChecksum(entry) {
+    const expected = computeChecksum({
+      seqNo: entry.seqNo,
+      primaryTerm: entry.primaryTerm,
+      operation: entry.operation,
+      partitionId: entry.partitionId,
+      indexName: entry.indexName,
+      documentId: entry.documentId,
+      document: entry.document
+    });
+    return expected === entry.checksum;
   }
-}
-function isNestedSchema(value) {
-  return typeof value === "object" && value !== null;
-}
-async function applyReplicationEntry(core, entry) {
-  core.guardShutdown();
-  const indexEntry = core.requireIndex(entry.indexName);
-  const manager = core.requireManager(entry.indexName);
-  const vecIndexes = manager.getVectorIndexes();
-  if (entry.operation === "INDEX") {
-    applyIndexEntry(entry, manager, indexEntry.vectorFieldPaths, vecIndexes);
-    const appliedDocument = manager.get(entry.documentId);
-    if (appliedDocument !== void 0) {
-      await core.orchestrator.replicateToWorkers({
-        type: "insert",
-        indexName: entry.indexName,
-        docId: entry.documentId,
-        document: appliedDocument,
-        requestId: `replicate-entry-insert-${entry.indexName}-${entry.partitionId}-${entry.seqNo}`
-      });
+  return {
+    append(partial) {
+      assertEntryFitsRetention(partial);
+      const seqNo = nextSeqNo;
+      nextSeqNo += 1;
+      const entryWithoutChecksum = {
+        seqNo,
+        primaryTerm: partial.primaryTerm,
+        operation: partial.operation,
+        partitionId,
+        indexName: partial.indexName,
+        documentId: partial.documentId,
+        document: partial.document
+      };
+      const checksum = computeChecksum(entryWithoutChecksum);
+      const entry = { ...entryWithoutChecksum, checksum };
+      return storeEntry(entry);
+    },
+    appendCommitted(entry) {
+      if (!Number.isSafeInteger(entry.seqNo) || entry.seqNo < 1) {
+        throw new NarsilError(
+          ErrorCodes.REPLICATION_ENTRY_INVALID,
+          `Invalid replication sequence number ${entry.seqNo}`,
+          {
+            seqNo: entry.seqNo,
+            partitionId
+          }
+        );
+      }
+      if (entry.partitionId !== partitionId) {
+        throw new NarsilError(
+          ErrorCodes.REPLICATION_ENTRY_INVALID,
+          `Replication entry partition ${entry.partitionId} does not match log partition ${partitionId}`,
+          { entryPartitionId: entry.partitionId, logPartitionId: partitionId }
+        );
+      }
+      const existing = readEntry(entry.seqNo);
+      if (existing !== void 0) {
+        if (existing.checksum !== entry.checksum) {
+          throw new NarsilError(
+            ErrorCodes.REPLICATION_ENTRY_INVALID,
+            `Conflicting replication entry at sequence number ${entry.seqNo}`,
+            { seqNo: entry.seqNo, partitionId }
+          );
+        }
+        return existing;
+      }
+      if (entry.seqNo !== nextSeqNo) {
+        throw new NarsilError(
+          ErrorCodes.REPLICATION_ENTRY_INVALID,
+          `Out-of-order replication entry ${entry.seqNo}; expected ${nextSeqNo}`,
+          { seqNo: entry.seqNo, expectedSeqNo: nextSeqNo, partitionId }
+        );
+      }
+      if (!verifyEntryChecksum(entry)) {
+        throw new NarsilError(
+          ErrorCodes.REPLICATION_ENTRY_CORRUPT,
+          `Invalid checksum for replication entry ${entry.seqNo}`,
+          { seqNo: entry.seqNo, partitionId }
+        );
+      }
+      assertEntryFitsRetention(entry);
+      nextSeqNo = entry.seqNo + 1;
+      return storeEntry({ ...entry });
+    },
+    getEntriesFrom(fromSeqNo) {
+      if (liveCount() === 0) return [];
+      const idx = findIndexBySeqNo(fromSeqNo);
+      if (idx >= entries.length) return [];
+      return entries.slice(idx).map((e) => ({ ...e }));
+    },
+    getEntry(seqNo) {
+      return readEntry(seqNo);
+    },
+    verifyChecksum(entry) {
+      return verifyEntryChecksum(entry);
+    },
+    get localLogEnd() {
+      return localLogEnd;
+    },
+    get localLogEndPrimaryTerm() {
+      return localLogEndPrimaryTerm;
+    },
+    get commitPoint() {
+      return commitPoint;
+    },
+    advanceCommitPoint(seqNo) {
+      const bounded = Math.min(seqNo, localLogEnd);
+      if (bounded > commitPoint) {
+        commitPoint = bounded;
+      }
+    },
+    get oldestSeqNo() {
+      if (liveCount() === 0) return void 0;
+      return entries[headIndex].seqNo;
+    },
+    get newestSeqNo() {
+      if (liveCount() === 0) return void 0;
+      return entries[entries.length - 1].seqNo;
+    },
+    get entryCount() {
+      return liveCount();
+    },
+    get sizeBytes() {
+      return totalSizeBytes;
+    },
+    clear() {
+      entries = [];
+      headIndex = 0;
+      totalSizeBytes = 0;
+      localLogEnd = nextSeqNo - 1;
+      commitPoint = nextSeqNo - 1;
     }
-    return;
-  }
-  applyDeleteEntry(entry, manager, vecIndexes);
-  await core.orchestrator.replicateToWorkers({
-    type: "remove",
-    indexName: entry.indexName,
-    docId: entry.documentId,
-    requestId: `replicate-entry-remove-${entry.indexName}-${entry.partitionId}-${entry.seqNo}`
-  });
+  };
 }
 
-// src/distribution/cluster-node/local-index-reconcile.ts
-async function reconcileLocalIndexes(deps) {
-  const dispositions = /* @__PURE__ */ new Map();
-  for (const index of deps.engine.listIndexes()) {
-    const disposition = await reconcileOne(deps, index.name);
-    dispositions.set(index.name, disposition);
-  }
-  return dispositions;
+// src/distribution/cluster-node/replication-logs.ts
+function replicationLogKey(indexName, partitionId) {
+  return `${indexName}:${partitionId}`;
 }
-async function adoptClusterIdentity(engine, coordinator, indexName) {
-  if (engine.indexUuidOf(indexName) !== null) {
-    return;
-  }
-  const metadata = await getIndexMetadata(coordinator, indexName);
-  if (metadata === null) {
-    return;
+function getReplicationLog(replicationLogs, indexName, partitionId, replicationConfig) {
+  const key = replicationLogKey(indexName, partitionId);
+  let log = replicationLogs.get(key);
+  if (log === void 0) {
+    log = createReplicationLog(partitionId, { logRetentionBytes: replicationConfig?.logRetentionBytes });
+    replicationLogs.set(key, log);
   }
-  await engine.stampIndexUuid(indexName, metadata.indexUuid);
+  return log;
 }
-function orphanedIndexError(nodeId, indexName) {
-  return new NarsilError(
-    ErrorCodes.INDEX_ORPHANED,
-    `Node '${nodeId}' holds a local copy of index '${indexName}' the cluster does not claim, so it answers nothing for that name. Drop it to reclaim the space`,
-    { indexName, nodeId }
+function seedReplicationLog(replicationLogs, indexName, partitionId, startSeqNo, lastPrimaryTerm = 0, replicationConfig) {
+  replicationLogs.set(
+    replicationLogKey(indexName, partitionId),
+    createReplicationLog(partitionId, {
+      startSeqNo,
+      lastPrimaryTerm,
+      logRetentionBytes: replicationConfig?.logRetentionBytes
+    })
   );
 }
-async function reconcileOne(deps, indexName) {
-  const localUuid = deps.engine.indexUuidOf(indexName);
-  let clusterUuid;
-  try {
-    clusterUuid = (await getIndexMetadata(deps.coordinator, indexName))?.indexUuid ?? null;
-  } catch (error) {
-    report(deps, indexName, `its metadata could not be read: ${describeError(error)}`);
-    return "orphaned";
-  }
-  if (clusterUuid === null) {
-    report(deps, indexName, "the coordinator holds no metadata for that name");
-    return "orphaned";
-  }
-  if (localUuid === clusterUuid) {
-    return "adopted";
+function deleteIndexReplicationLogs(replicationLogs, indexName) {
+  const prefix = `${indexName}:`;
+  for (const key of replicationLogs.keys()) {
+    if (key.startsWith(prefix)) replicationLogs.delete(key);
   }
-  if (localUuid === null || localUuid === void 0) {
-    await deps.engine.stampIndexUuid(indexName, clusterUuid);
-    return "adopted";
+}
+
+// src/distribution/cluster-node/local-replication.ts
+async function seedReopenedPrimaryLogs(input) {
+  const allocation = await input.coordinator.getAllocation(input.indexName);
+  if (allocation === null) return;
+  for (const partitionId of input.engine.heldPartitionsOf(input.indexName) ?? []) {
+    const assignment = allocation.assignments.get(partitionId);
+    if (assignment?.primary !== input.nodeId) continue;
+    const floor = Math.max(input.engine.highestPersistedSeqNoOf(input.indexName, partitionId), assignment.commitPoint);
+    seedReplicationLog(
+      input.replicationLogs,
+      input.indexName,
+      partitionId,
+      floor + 1,
+      assignment.primaryTerm,
+      input.replicationConfig
+    );
   }
-  await deps.engine.dropIndex(indexName);
-  return "superseded";
 }
-function report(deps, indexName, reason) {
-  if (deps.onError === void 0) {
-    return;
+async function applyLocalReplicationEntry(core, entry) {
+  core.guardShutdown();
+  const release = await core.indexState.acquire(entry.indexName);
+  try {
+    const indexEntry = core.requireIndex(entry.indexName);
+    const manager = core.requireManager(entry.indexName);
+    const vecIndexes = manager.getVectorIndexes();
+    if (entry.operation === "INDEX") {
+      applyIndexEntry(entry, manager, indexEntry.vectorFieldPaths, vecIndexes);
+      const appliedDocument = manager.get(entry.documentId);
+      if (appliedDocument !== void 0) {
+        await core.orchestrator.replicateToWorkers({
+          type: "insert",
+          indexName: entry.indexName,
+          docId: entry.documentId,
+          document: appliedDocument,
+          requestId: `replicate-entry-insert-${entry.indexName}-${entry.partitionId}-${entry.seqNo}`
+        });
+      }
+      return;
+    }
+    applyDeleteEntry(entry, manager, vecIndexes);
+    await core.orchestrator.replicateToWorkers({
+      type: "remove",
+      indexName: entry.indexName,
+      docId: entry.documentId,
+      requestId: `replicate-entry-remove-${entry.indexName}-${entry.partitionId}-${entry.seqNo}`
+    });
+  } finally {
+    release();
   }
-  deps.onError(
-    new NarsilError(
-      ErrorCodes.INDEX_ORPHANED,
-      `Node '${deps.nodeId}' holds a local copy of index '${indexName}' the cluster does not claim, because ${reason}. The node keeps the data and serves none of it until an operator drops it.`,
-      { indexName, nodeId: deps.nodeId }
-    )
-  );
 }
 
-// src/distribution/cluster-node/snapshot-auth.ts
-var BOOTSTRAPPABLE_STATES = /* @__PURE__ */ new Set(["ACTIVE", "INITIALISING", "MIGRATING"]);
-async function authorizeSnapshotRequest(coordinator, indexName, sourceId) {
-  let allocation;
-  try {
-    allocation = await coordinator.getAllocation(indexName);
-  } catch (err) {
-    const errMessage = err instanceof Error ? err.message : String(err);
-    return {
-      outcome: "denied",
-      code: ErrorCodes.SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE,
-      reason: `allocation lookup failed: ${errMessage}`
-    };
+// src/distribution/cluster-node/local-engine.ts
+async function createClusterLocalEngine(config, hooks) {
+  const core = createEngineCore(config, hooks);
+  if (core.durability !== null) {
+    await core.durability.manager.recover(config?.lifecycle !== void 0);
   }
-  if (allocation === null) {
-    return {
-      outcome: "denied",
-      code: ErrorCodes.SNAPSHOT_SYNC_UNAUTHORIZED,
-      reason: `index '${indexName}' has no allocation`
-    };
+  if (core.invalidation !== null) {
+    await core.invalidation.start();
   }
-  let sawAssignment = false;
-  for (const assignment of allocation.assignments.values()) {
-    const isAssigned = assignment.primary === sourceId || assignment.replicas.includes(sourceId);
-    if (!isAssigned) {
-      continue;
-    }
-    sawAssignment = true;
-    if (!BOOTSTRAPPABLE_STATES.has(assignment.state)) {
-      continue;
+  if (config?.lifecycle === void 0) await core.analysisRebuild.reviewStaleIndexes();
+  const engine = createNarsilFromCore(core, config);
+  const heldPartitions = createHeldPartitionRecord(core);
+  return Object.assign(engine, {
+    createIndexWithUuid: (name, indexConfig, indexUuid) => createEngineIndex(core, config, name, indexConfig, indexUuid),
+    acquireIndexForReplication: (indexName) => core.indexState.acquire(indexName, false),
+    indexUuidOf: (indexName) => core.indexRegistry.get(indexName)?.indexUuid,
+    stampIndexUuid: (indexName, indexUuid) => stampIndexUuid(core, indexName, indexUuid),
+    highestPersistedSeqNoOf: (indexName, partitionId) => core.durability?.manager.highestPersistedSeqNo(indexName, partitionId) ?? 0,
+    heldPartitionsOf: (indexName) => heldPartitions.held(indexName),
+    recordHeldPartition: (indexName, partitionId) => heldPartitions.record(indexName, partitionId),
+    forgetHeldPartition: (indexName, partitionId) => heldPartitions.forget(indexName, partitionId),
+    applyReplicationEntry: (entry) => applyLocalReplicationEntry(core, entry),
+    serializeReplicationPartition: (indexName, partitionId) => serializeReplicationPartition(core, indexName, partitionId),
+    restoreReplicationPartition: (indexName, partitionId, bytes, schema, partitionCount) => restoreReplicationPartition(core, engine, indexName, partitionId, bytes, schema, partitionCount),
+    queryPartitions: (indexName, params, partitionIds, globalStats) => runEngineQuery(core, indexName, params, { partitionIds, globalStats }),
+    preflightPartitions: (indexName, params, partitionIds) => runEnginePreflight(core, indexName, params, { partitionIds }),
+    suggestPartitions: (indexName, params, partitionIds) => runEngineSuggest(core, indexName, params, partitionIds),
+    listPartitions: (indexName, params, partitionIds) => runEngineListDocuments(core, indexName, params, partitionIds),
+    collectQueryStats: (indexName, terms, partitionIds) => runEngineQueryStats(core, indexName, terms, partitionIds),
+    partitionStatsForRead: async (indexName) => {
+      const release = await core.indexState.acquire(indexName);
+      try {
+        return core.requireManager(indexName).getPartitionStats();
+      } finally {
+        release();
+      }
     }
-    return { outcome: "authorized" };
+  });
+}
+async function stampIndexUuid(core, indexName, indexUuid) {
+  const entry = core.indexRegistry.get(indexName);
+  if (entry === void 0 || entry.indexUuid === indexUuid) {
+    return;
   }
-  if (sawAssignment) {
-    return {
-      outcome: "denied",
-      code: ErrorCodes.SNAPSHOT_SYNC_NOT_ASSIGNED,
-      reason: `node '${sourceId}' is listed for index '${indexName}' but not in a bootstrappable state`
-    };
+  core.indexRegistry.set(indexName, { ...entry, indexUuid });
+  if (core.durability !== null) {
+    await core.durability.manager.persistMetadata(indexName);
   }
-  return {
-    outcome: "denied",
-    code: ErrorCodes.SNAPSHOT_SYNC_UNAUTHORIZED,
-    reason: `node '${sourceId}' is not an assigned replica for index '${indexName}'`
-  };
 }
-
-// src/distribution/cluster-node/snapshot-cache.ts
-var DEFAULT_MAX_CONCURRENT_SNAPSHOTS = 2;
-var DEFAULT_MAX_PER_SOURCE_SNAPSHOTS = 1;
-var DEFAULT_MAX_STREAMS_PER_INDEX = 4;
-function createSnapshotCacheState(maxConcurrent = DEFAULT_MAX_CONCURRENT_SNAPSHOTS, maxPerSource = DEFAULT_MAX_PER_SOURCE_SNAPSHOTS, maxStreamsPerIndex = DEFAULT_MAX_STREAMS_PER_INDEX) {
-  if (!Number.isInteger(maxConcurrent) || maxConcurrent <= 0) {
-    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "maxConcurrent must be a positive integer", {
-      maxConcurrent
-    });
+async function serializeReplicationPartition(core, indexName, partitionId) {
+  core.guardShutdown();
+  const release = await core.indexState.acquire(indexName, false);
+  try {
+    return core.requireManager(indexName).serializePartitionToBytes(partitionId);
+  } finally {
+    release();
   }
-  if (!Number.isInteger(maxPerSource) || maxPerSource <= 0) {
-    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "maxPerSource must be a positive integer", {
-      maxPerSource
+}
+async function restoreReplicationPartition(core, engine, indexName, partitionId, bytes, schema, partitionCount) {
+  core.guardShutdown();
+  validatePartitionRestoreTarget(indexName, partitionId, partitionCount);
+  let partition;
+  try {
+    partition = deserializePayloadV2(bytes);
+  } catch (err) {
+    const cause = err instanceof Error ? err.message : String(err);
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, `partition snapshot decode failed: ${cause}`, {
+      indexName,
+      partitionId,
+      cause
     });
   }
-  if (!Number.isInteger(maxStreamsPerIndex) || maxStreamsPerIndex <= 0) {
-    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "maxStreamsPerIndex must be a positive integer", {
-      maxStreamsPerIndex
+  validatePartitionSnapshotPayload(indexName, partitionId, partitionCount, schema, partition);
+  const trackPositions = core.indexRegistry.get(indexName)?.config.trackPositions ?? true;
+  createPartitionIndex(partitionId, trackPositions).deserialize(partition, schema);
+  let release = core.indexRegistry.has(indexName) ? await core.indexState.acquire(indexName, false) : null;
+  try {
+    const restoreIndex = await ensureReplicationIndex(
+      core,
+      engine,
+      indexName,
+      schema,
+      partition.language,
+      partitionCount
+    );
+    if (release === null) release = await core.indexState.acquire(indexName, false);
+    if (restoreIndex.created) {
+      await core.orchestrator.replicateToWorkers({
+        type: "createIndex",
+        indexName,
+        config: restoreIndex.config,
+        requestId: `replicate-partition-index-${indexName}`
+      });
+    }
+    const manager = core.requireManager(indexName);
+    manager.deserializePartition(partitionId, partition);
+    await core.orchestrator.replicateToWorkers({
+      type: "deserialize",
+      indexName,
+      partitionId,
+      data: partition,
+      requestId: `replicate-partition-restore-${indexName}-${partitionId}`
     });
+  } finally {
+    release?.();
   }
-  return {
-    cache: /* @__PURE__ */ new Map(),
-    active: 0,
-    perSource: /* @__PURE__ */ new Map(),
-    streamActive: /* @__PURE__ */ new Map(),
-    maxConcurrent,
-    maxPerSource,
-    maxStreamsPerIndex
-  };
-}
-function sourceSlotKey(sourceId, indexName) {
-  return `${sourceId}\0${indexName}`;
 }
-function acquireSourceSlot(state, sourceId, indexName) {
-  const key = sourceSlotKey(sourceId, indexName);
-  const current = state.perSource.get(key) ?? 0;
-  if (current >= state.maxPerSource) {
+function validatePartitionRestoreTarget(indexName, partitionId, partitionCount) {
+  if (!Number.isInteger(partitionId) || partitionId < 0) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partitionId must be a non-negative integer", {
+      indexName,
+      partitionId
+    });
+  }
+  if (!Number.isInteger(partitionCount) || partitionCount <= 0 || partitionCount > MAX_PARTITION_COUNT) {
     throw new NarsilError(
-      ErrorCodes.SNAPSHOT_SYNC_CAPACITY_EXHAUSTED,
-      `snapshot producer per-source cap reached for '${sourceId}' index '${indexName}'`,
-      { sourceId, indexName, cap: state.maxPerSource }
+      ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED,
+      `partitionCount must be an integer between 1 and ${MAX_PARTITION_COUNT}`,
+      { indexName, partitionCount }
     );
   }
-  state.perSource.set(key, current + 1);
-  return { key, released: false };
+  if (partitionId >= partitionCount) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partitionId is outside partitionCount", {
+      indexName,
+      partitionId,
+      partitionCount
+    });
+  }
 }
-function releaseSourceSlot(state, handle) {
-  if (handle.released) {
-    return;
+function validatePartitionSnapshotPayload(indexName, partitionId, partitionCount, schema, partition) {
+  if (partition.indexName !== indexName) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot indexName mismatch", {
+      expectedIndexName: indexName,
+      receivedIndexName: partition.indexName
+    });
   }
-  handle.released = true;
-  const current = state.perSource.get(handle.key);
-  if (current === void 0) {
-    return;
+  if (partition.partitionId !== partitionId) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot partitionId mismatch", {
+      indexName,
+      expectedPartitionId: partitionId,
+      receivedPartitionId: partition.partitionId
+    });
   }
-  if (current <= 1) {
-    state.perSource.delete(handle.key);
-    return;
+  if (partition.totalPartitions !== partitionCount) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot partition count mismatch", {
+      indexName,
+      partitionId,
+      expectedPartitionCount: partitionCount,
+      receivedPartitionCount: partition.totalPartitions
+    });
   }
-  state.perSource.set(handle.key, current - 1);
-}
-function acquireStreamSlot(state, indexName) {
-  const current = state.streamActive.get(indexName) ?? 0;
-  if (current >= state.maxStreamsPerIndex) {
-    throw new NarsilError(
-      ErrorCodes.SNAPSHOT_SYNC_CAPACITY_EXHAUSTED,
-      `snapshot stream fan-out cap reached for index '${indexName}'`,
-      { indexName, cap: state.maxStreamsPerIndex }
-    );
+  const expectedSchema = flattenSchema(schema);
+  for (const [field, expectedType] of Object.entries(expectedSchema)) {
+    if (partition.schema[field] !== expectedType) {
+      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot schema mismatch", {
+        indexName,
+        partitionId,
+        field,
+        expected: expectedType,
+        received: partition.schema[field] ?? "(absent)"
+      });
+    }
+  }
+  for (const field of Object.keys(partition.schema)) {
+    if (!(field in expectedSchema)) {
+      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot schema contains extra field", {
+        indexName,
+        partitionId,
+        field
+      });
+    }
   }
-  state.streamActive.set(indexName, current + 1);
-  return { indexName, released: false };
 }
-function releaseStreamSlot(state, handle) {
-  if (handle.released) {
-    return;
+async function ensureReplicationIndex(core, engine, indexName, schema, languageName, partitionCount) {
+  const language = getLanguage(languageName);
+  const existing = core.indexRegistry.get(indexName);
+  let created = false;
+  if (existing === void 0) {
+    const indexConfig = {
+      schema,
+      language: language.name,
+      partitions: { maxPartitions: partitionCount }
+    };
+    try {
+      await engine.createIndex(indexName, indexConfig);
+      created = true;
+    } catch (err) {
+      if (!(err instanceof NarsilError) || err.code !== ErrorCodes.INDEX_ALREADY_EXISTS) {
+        throw err;
+      }
+    }
   }
-  handle.released = true;
-  const current = state.streamActive.get(handle.indexName);
-  if (current === void 0) {
-    return;
+  const entry = core.requireIndex(indexName);
+  if (entry.language.name !== language.name) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "partition snapshot language mismatch", {
+      indexName,
+      expectedLanguage: entry.language.name,
+      receivedLanguage: language.name
+    });
   }
-  if (current <= 1) {
-    state.streamActive.delete(handle.indexName);
-    return;
+  validateExistingSchema(indexName, schema, entry.config.schema);
+  const manager = core.requireManager(indexName);
+  if (manager.partitionCount > partitionCount) {
+    throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "local index has more partitions than allocation", {
+      indexName,
+      localPartitionCount: manager.partitionCount,
+      allocationPartitionCount: partitionCount
+    });
   }
-  state.streamActive.set(handle.indexName, current - 1);
-}
-async function acquireSnapshotBuild(state, indexName, builder) {
-  const existing = state.cache.get(indexName);
-  if (existing !== void 0) {
-    return existing.promise;
+  if (entry.config.partitions === void 0) {
+    entry.config.partitions = { maxPartitions: partitionCount };
+  } else if ((entry.config.partitions.maxPartitions ?? manager.partitionCount) < partitionCount) {
+    entry.config.partitions.maxPartitions = partitionCount;
   }
-  if (state.active >= state.maxConcurrent) {
-    throw new NarsilError(
-      ErrorCodes.SNAPSHOT_SYNC_CAPACITY_EXHAUSTED,
-      "snapshot producer capacity exhausted; retry later",
-      { active: state.active, max: state.maxConcurrent }
+  while (manager.partitionCount < partitionCount) {
+    manager.addPartition();
+  }
+  return { config: entry.config, created };
+}
+function validateExistingSchema(indexName, expected, actual) {
+  const expectedSchema = flattenSchema(expected);
+  const actualSchema = flattenSchema(actual);
+  for (const [field, expectedType] of Object.entries(expectedSchema)) {
+    if (actualSchema[field] !== expectedType) {
+      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "local index schema mismatch", {
+        indexName,
+        field,
+        expected: expectedType,
+        received: actualSchema[field] ?? "(absent)"
+      });
+    }
+  }
+  for (const field of Object.keys(actualSchema)) {
+    if (!(field in expectedSchema)) {
+      throw new NarsilError(ErrorCodes.SNAPSHOT_SYNC_RESTORE_FAILED, "local index schema contains extra field", {
+        indexName,
+        field
+      });
+    }
+  }
+}
+function flattenSchema(schema) {
+  const flat = {};
+  flattenSchemaInto(schema, "", flat);
+  return flat;
+}
+function flattenSchemaInto(schema, prefix, flat) {
+  for (const [field, value] of Object.entries(schema)) {
+    const path = prefix.length === 0 ? field : `${prefix}.${field}`;
+    if (isNestedSchema(value)) {
+      flattenSchemaInto(value, path, flat);
+      continue;
+    }
+    flat[path] = value;
+  }
+}
+function isNestedSchema(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/distribution/cluster-node/local-index-reconcile.ts
+async function reconcileLocalIndexes(deps) {
+  const dispositions = /* @__PURE__ */ new Map();
+  for (const index of deps.engine.listIndexes()) {
+    const disposition = await reconcileOne(deps, index.name);
+    dispositions.set(index.name, disposition);
+  }
+  return dispositions;
+}
+async function adoptClusterIdentity(engine, coordinator, indexName) {
+  if (engine.indexUuidOf(indexName) !== null) {
+    return;
+  }
+  const metadata = await getIndexMetadata(coordinator, indexName);
+  if (metadata === null) {
+    return;
+  }
+  await engine.stampIndexUuid(indexName, metadata.indexUuid);
+}
+function orphanedIndexError(nodeId, indexName) {
+  return new NarsilError(
+    ErrorCodes.INDEX_ORPHANED,
+    `Node '${nodeId}' holds a local copy of index '${indexName}' the cluster does not claim, so it answers nothing for that name. Drop it to reclaim the space`,
+    { indexName, nodeId }
+  );
+}
+async function reconcileOne(deps, indexName) {
+  const localUuid = deps.engine.indexUuidOf(indexName);
+  let clusterUuid;
+  try {
+    clusterUuid = (await getIndexMetadata(deps.coordinator, indexName))?.indexUuid ?? null;
+  } catch (error) {
+    report(deps, indexName, `its metadata could not be read: ${describeError(error)}`);
+    return "orphaned";
+  }
+  if (clusterUuid === null) {
+    report(deps, indexName, "the coordinator holds no metadata for that name");
+    return "orphaned";
+  }
+  if (localUuid === clusterUuid) {
+    return "adopted";
+  }
+  if (localUuid === null || localUuid === void 0) {
+    await deps.engine.stampIndexUuid(indexName, clusterUuid);
+    return "adopted";
+  }
+  await deps.engine.dropIndex(indexName);
+  return "superseded";
+}
+function report(deps, indexName, reason) {
+  if (deps.onError === void 0) {
+    return;
+  }
+  deps.onError(
+    new NarsilError(
+      ErrorCodes.INDEX_ORPHANED,
+      `Node '${deps.nodeId}' holds a local copy of index '${indexName}' the cluster does not claim, because ${reason}. The node keeps the data and serves none of it until an operator drops it.`,
+      { indexName, nodeId: deps.nodeId }
+    )
+  );
+}
+
+// src/distribution/cluster-node/snapshot-auth.ts
+var BOOTSTRAPPABLE_STATES = /* @__PURE__ */ new Set(["ACTIVE", "INITIALISING", "MIGRATING"]);
+async function authorizeSnapshotRequest(coordinator, indexName, sourceId) {
+  let allocation;
+  try {
+    allocation = await coordinator.getAllocation(indexName);
+  } catch (err) {
+    const errMessage = err instanceof Error ? err.message : String(err);
+    return {
+      outcome: "denied",
+      code: ErrorCodes.SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE,
+      reason: `allocation lookup failed: ${errMessage}`
+    };
+  }
+  if (allocation === null) {
+    return {
+      outcome: "denied",
+      code: ErrorCodes.SNAPSHOT_SYNC_UNAUTHORIZED,
+      reason: `index '${indexName}' has no allocation`
+    };
+  }
+  let sawAssignment = false;
+  for (const assignment of allocation.assignments.values()) {
+    const isAssigned = assignment.primary === sourceId || assignment.replicas.includes(sourceId);
+    if (!isAssigned) {
+      continue;
+    }
+    sawAssignment = true;
+    if (!BOOTSTRAPPABLE_STATES.has(assignment.state)) {
+      continue;
+    }
+    return { outcome: "authorized" };
+  }
+  if (sawAssignment) {
+    return {
+      outcome: "denied",
+      code: ErrorCodes.SNAPSHOT_SYNC_NOT_ASSIGNED,
+      reason: `node '${sourceId}' is listed for index '${indexName}' but not in a bootstrappable state`
+    };
+  }
+  return {
+    outcome: "denied",
+    code: ErrorCodes.SNAPSHOT_SYNC_UNAUTHORIZED,
+    reason: `node '${sourceId}' is not an assigned replica for index '${indexName}'`
+  };
+}
+
+// src/distribution/cluster-node/snapshot-cache.ts
+var DEFAULT_MAX_CONCURRENT_SNAPSHOTS = 2;
+var DEFAULT_MAX_PER_SOURCE_SNAPSHOTS = 1;
+var DEFAULT_MAX_STREAMS_PER_INDEX = 4;
+function createSnapshotCacheState(maxConcurrent = DEFAULT_MAX_CONCURRENT_SNAPSHOTS, maxPerSource = DEFAULT_MAX_PER_SOURCE_SNAPSHOTS, maxStreamsPerIndex = DEFAULT_MAX_STREAMS_PER_INDEX) {
+  if (!Number.isInteger(maxConcurrent) || maxConcurrent <= 0) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "maxConcurrent must be a positive integer", {
+      maxConcurrent
+    });
+  }
+  if (!Number.isInteger(maxPerSource) || maxPerSource <= 0) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "maxPerSource must be a positive integer", {
+      maxPerSource
+    });
+  }
+  if (!Number.isInteger(maxStreamsPerIndex) || maxStreamsPerIndex <= 0) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, "maxStreamsPerIndex must be a positive integer", {
+      maxStreamsPerIndex
+    });
+  }
+  return {
+    cache: /* @__PURE__ */ new Map(),
+    active: 0,
+    perSource: /* @__PURE__ */ new Map(),
+    streamActive: /* @__PURE__ */ new Map(),
+    maxConcurrent,
+    maxPerSource,
+    maxStreamsPerIndex
+  };
+}
+function sourceSlotKey(sourceId, indexName) {
+  return `${sourceId}\0${indexName}`;
+}
+function acquireSourceSlot(state, sourceId, indexName) {
+  const key = sourceSlotKey(sourceId, indexName);
+  const current = state.perSource.get(key) ?? 0;
+  if (current >= state.maxPerSource) {
+    throw new NarsilError(
+      ErrorCodes.SNAPSHOT_SYNC_CAPACITY_EXHAUSTED,
+      `snapshot producer per-source cap reached for '${sourceId}' index '${indexName}'`,
+      { sourceId, indexName, cap: state.maxPerSource }
+    );
+  }
+  state.perSource.set(key, current + 1);
+  return { key, released: false };
+}
+function releaseSourceSlot(state, handle) {
+  if (handle.released) {
+    return;
+  }
+  handle.released = true;
+  const current = state.perSource.get(handle.key);
+  if (current === void 0) {
+    return;
+  }
+  if (current <= 1) {
+    state.perSource.delete(handle.key);
+    return;
+  }
+  state.perSource.set(handle.key, current - 1);
+}
+function acquireStreamSlot(state, indexName) {
+  const current = state.streamActive.get(indexName) ?? 0;
+  if (current >= state.maxStreamsPerIndex) {
+    throw new NarsilError(
+      ErrorCodes.SNAPSHOT_SYNC_CAPACITY_EXHAUSTED,
+      `snapshot stream fan-out cap reached for index '${indexName}'`,
+      { indexName, cap: state.maxStreamsPerIndex }
+    );
+  }
+  state.streamActive.set(indexName, current + 1);
+  return { indexName, released: false };
+}
+function releaseStreamSlot(state, handle) {
+  if (handle.released) {
+    return;
+  }
+  handle.released = true;
+  const current = state.streamActive.get(handle.indexName);
+  if (current === void 0) {
+    return;
+  }
+  if (current <= 1) {
+    state.streamActive.delete(handle.indexName);
+    return;
+  }
+  state.streamActive.set(handle.indexName, current - 1);
+}
+async function acquireSnapshotBuild(state, indexName, builder) {
+  const existing = state.cache.get(indexName);
+  if (existing !== void 0) {
+    return existing.promise;
+  }
+  if (state.active >= state.maxConcurrent) {
+    throw new NarsilError(
+      ErrorCodes.SNAPSHOT_SYNC_CAPACITY_EXHAUSTED,
+      "snapshot producer capacity exhausted; retry later",
+      { active: state.active, max: state.maxConcurrent }
     );
   }
   state.active += 1;
@@ -5748,6 +6041,11 @@ var MAX_LIMIT = 1e4;
 var MAX_OFFSET = 1e4;
 var MAX_HYBRID_K = 1e4;
 var MIN_HYBRID_K = 1;
+var MAX_PREFIX_LENGTH = 1024;
+var MAX_PINNED_ENTRIES = 1e3;
+var MAX_PINNED_POSITION = RESULT_WINDOW;
+var MAX_EF_SEARCH = 1e4;
+var MAX_GROUP_FIELDS = 64;
 var NULL_BYTE = String.fromCharCode(0);
 function throwInvalid(code, message, details) {
   throw new NarsilError(code, message, details);
@@ -6224,13 +6522,153 @@ function validateFilterExpression(value, fieldLabel, errorCode = SEARCH_INVALID_
   }
 }
 
-// src/distribution/query/validators/search.ts
-var MAX_FACET_SHARD_SIZE = Math.ceil(1e3 * 1.5) + 10;
-var MAX_VECTOR_DIMENSION = 8192;
-var MAX_VECTOR_TEXT_LENGTH = 16384;
+// src/distribution/query/oversample.ts
+function oversampledShardSize(size) {
+  return Math.ceil(size * 1.5) + 10;
+}
+
+// src/distribution/query/validators/search-options.ts
+var ALLOWED_MODES = ["fulltext", "vector", "hybrid"];
+var ALLOWED_METRICS = ["cosine", "dotProduct", "euclidean"];
+var ALLOWED_HYBRID_STRATEGIES = ["rrf", "linear"];
+function validateHybridParams(value) {
+  if (!isRecord2(value)) {
+    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.hybrid" must be an object');
+  }
+  if (value.strategy !== null && !ALLOWED_HYBRID_STRATEGIES.includes(value.strategy)) {
+    throwInvalid(
+      SEARCH_INVALID_MODE,
+      `Invalid SearchPayload: "params.hybrid.strategy" must be one of: ${ALLOWED_HYBRID_STRATEGIES.join(", ")}, or null`
+    );
+  }
+  if (value.k !== null && (!isInteger(value.k) || value.k < MIN_HYBRID_K || value.k > MAX_HYBRID_K)) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: "params.hybrid.k" must be an integer between ${MIN_HYBRID_K} and ${MAX_HYBRID_K}, or null`
+    );
+  }
+  if (value.alpha !== null && (!isFiniteNumber(value.alpha) || value.alpha < 0 || value.alpha > 1)) {
+    throwInvalid(
+      CONFIG_INVALID,
+      'Invalid SearchPayload: "params.hybrid.alpha" must be a finite number in [0, 1], or null'
+    );
+  }
+}
+function validateGroupParams(value) {
+  if (!isRecord2(value)) {
+    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.group" must be an object');
+  }
+  const fields = validateStringArray(
+    value.fields,
+    "params.group.fields",
+    MAX_GROUP_FIELDS,
+    MAX_FIELD_NAME_LENGTH,
+    SEARCH_INVALID_FIELD
+  );
+  if (fields.length === 0) {
+    throwInvalid(SEARCH_INVALID_FIELD, 'Invalid SearchPayload: "params.group.fields" must name at least one field');
+  }
+  if (!isInteger(value.maxPerGroup) || value.maxPerGroup <= 0 || value.maxPerGroup > MAX_LIMIT) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: "params.group.maxPerGroup" must be a positive integer at most ${MAX_LIMIT}`
+    );
+  }
+  if (value.limit !== null && (!isInteger(value.limit) || value.limit < 0 || value.limit > MAX_LIMIT)) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: "params.group.limit" must be a non-negative integer at most ${MAX_LIMIT}, or null`
+    );
+  }
+}
+function validateTermMatchParam(value) {
+  if (value === "all" || value === "any") {
+    return;
+  }
+  if (typeof value === "string") {
+    throwInvalid(SEARCH_INVALID_MODE, 'Invalid SearchPayload: "params.termMatch" must be "all", "any", or a count');
+  }
+  if (!isInteger(value) || value < 1 || value > MAX_TERMS_COUNT) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: a "params.termMatch" count must be an integer between 1 and ${MAX_TERMS_COUNT}`
+    );
+  }
+}
+function validatePrefixLengthParam(value) {
+  if (!isInteger(value) || value < 0 || value > MAX_PREFIX_LENGTH) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: "params.prefixLength" must be a non-negative integer at most ${MAX_PREFIX_LENGTH}`
+    );
+  }
+}
+function validateBooleanParam(value, fieldLabel) {
+  if (typeof value !== "boolean") {
+    throwInvalid(CONFIG_INVALID, `Invalid SearchPayload: "params.${fieldLabel}" must be a boolean or null`);
+  }
+}
+function validatePinnedParam(value) {
+  if (!Array.isArray(value)) {
+    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.pinned" must be an array or null');
+  }
+  if (value.length > MAX_PINNED_ENTRIES) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: "params.pinned" exceeds maximum length of ${MAX_PINNED_ENTRIES}`,
+      { length: value.length, limit: MAX_PINNED_ENTRIES }
+    );
+  }
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    if (!isRecord2(entry)) {
+      throwInvalid(CONFIG_INVALID, `Invalid SearchPayload: "params.pinned[${i}]" must be an object`);
+    }
+    if (typeof entry.docId !== "string" || entry.docId.length === 0 || entry.docId.length > MAX_DOC_ID_LENGTH) {
+      throwInvalid(
+        CONFIG_INVALID,
+        `Invalid SearchPayload: "params.pinned[${i}].docId" must be a string of 1 to ${MAX_DOC_ID_LENGTH} characters`
+      );
+    }
+    if (!isInteger(entry.position) || entry.position < 0 || entry.position > MAX_PINNED_POSITION) {
+      throwInvalid(
+        CONFIG_INVALID,
+        `Invalid SearchPayload: "params.pinned[${i}].position" must be an integer between 0 and ${MAX_PINNED_POSITION}`
+      );
+    }
+  }
+}
+function validateModeParam(value) {
+  if (!ALLOWED_MODES.includes(value)) {
+    throwInvalid(
+      SEARCH_INVALID_MODE,
+      `Invalid SearchPayload: "params.mode" must be one of: ${ALLOWED_MODES.join(", ")}`
+    );
+  }
+}
+function validateVectorMetricParam(value) {
+  if (!ALLOWED_METRICS.includes(value)) {
+    throwInvalid(
+      SEARCH_INVALID_MODE,
+      `Invalid SearchPayload: "params.vector.metric" must be one of: ${ALLOWED_METRICS.join(", ")}`
+    );
+  }
+}
+function validateEfSearchParam(value) {
+  if (!isInteger(value) || value < 1 || value > MAX_EF_SEARCH) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchPayload: "params.vector.efSearch" must be an integer between 1 and ${MAX_EF_SEARCH}`
+    );
+  }
+}
+
+// src/distribution/query/validators/search.ts
+var MAX_FACET_SHARD_SIZE = oversampledShardSize(1e3);
+var MAX_VECTOR_DIMENSION = 8192;
+var MAX_VECTOR_TEXT_LENGTH = 16384;
 var ALLOWED_SCORING = ["local", "dfs", "broadcast"];
 var ALLOWED_SORT_DIRECTIONS = ["asc", "desc"];
-var ALLOWED_HYBRID_STRATEGIES = ["rrf", "linear"];
 function validateIndexNameField2(value, fieldLabel) {
   if (typeof value !== "string") {
     throwInvalid(CONFIG_INVALID, `Invalid SearchPayload: "${fieldLabel}" must be a string`);
@@ -6282,37 +6720,11 @@ function validateVectorParams(value) {
       throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.vector.similarity" must be a finite number or null');
     }
   }
-}
-function validateHybridParams(value) {
-  if (!isRecord2(value)) {
-    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.hybrid" must be an object');
-  }
-  if (!ALLOWED_HYBRID_STRATEGIES.includes(value.strategy)) {
-    throwInvalid(
-      SEARCH_INVALID_MODE,
-      `Invalid SearchPayload: "params.hybrid.strategy" must be one of: ${ALLOWED_HYBRID_STRATEGIES.join(", ")}`
-    );
-  }
-  if (!isInteger(value.k) || value.k < MIN_HYBRID_K || value.k > MAX_HYBRID_K) {
-    throwInvalid(
-      CONFIG_INVALID,
-      `Invalid SearchPayload: "params.hybrid.k" must be an integer between ${MIN_HYBRID_K} and ${MAX_HYBRID_K}`
-    );
-  }
-  if (!isFiniteNumber(value.alpha) || value.alpha < 0 || value.alpha > 1) {
-    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.hybrid.alpha" must be a finite number in [0, 1]');
-  }
-}
-function validateGroupParams(value) {
-  if (!isRecord2(value)) {
-    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.group" must be an object');
+  if (value.metric !== null) {
+    validateVectorMetricParam(value.metric);
   }
-  validateFieldName(value.field, "params.group.field", SEARCH_INVALID_FIELD);
-  if (!isInteger(value.maxPerGroup) || value.maxPerGroup <= 0 || value.maxPerGroup > MAX_LIMIT) {
-    throwInvalid(
-      CONFIG_INVALID,
-      `Invalid SearchPayload: "params.group.maxPerGroup" must be a positive integer at most ${MAX_LIMIT}`
-    );
+  if (value.efSearch !== null) {
+    validateEfSearchParam(value.efSearch);
   }
 }
 function validateSortParams(value) {
@@ -6454,6 +6866,24 @@ function validateParams(params) {
       `Invalid SearchPayload: "params.scoring" must be one of: ${ALLOWED_SCORING.join(", ")}`
     );
   }
+  if (params.termMatch !== null) {
+    validateTermMatchParam(params.termMatch);
+  }
+  if (params.prefixLength !== null) {
+    validatePrefixLengthParam(params.prefixLength);
+  }
+  if (params.prefix !== null) {
+    validateBooleanParam(params.prefix, "prefix");
+  }
+  if (params.exact !== null) {
+    validateBooleanParam(params.exact, "exact");
+  }
+  if (params.pinned !== null) {
+    validatePinnedParam(params.pinned);
+  }
+  if (params.mode !== null) {
+    validateModeParam(params.mode);
+  }
   if (params.vector !== null) {
     validateVectorParams(params.vector);
   }
@@ -6704,6 +7134,7 @@ var MAX_SORT_VALUES = 8;
 var MAX_FACET_FIELDS = 64;
 var MAX_FACET_BUCKETS = 1e4;
 var MAX_FACET_VALUE_LENGTH = 1024;
+var MAX_GROUPS_PER_RESPONSE = 65536;
 function validateScoredEntry(value, fieldLabel) {
   if (!isRecord2(value)) {
     throwInvalid(CONFIG_INVALID, `Invalid SearchResultPayload: "${fieldLabel}" must be an object`);
@@ -6846,6 +7277,43 @@ function validateFacetErrorBounds(value) {
     }
   }
 }
+function validateGroupEntries(value) {
+  if (!Array.isArray(value)) {
+    throwInvalid(CONFIG_INVALID, 'Invalid SearchResultPayload: "groups" must be an array or null');
+  }
+  if (value.length > MAX_GROUPS_PER_RESPONSE) {
+    throwInvalid(
+      CONFIG_INVALID,
+      `Invalid SearchResultPayload: "groups" exceeds maximum length of ${MAX_GROUPS_PER_RESPONSE}`,
+      { length: value.length, limit: MAX_GROUPS_PER_RESPONSE }
+    );
+  }
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    if (!isRecord2(entry) || !isRecord2(entry.values)) {
+      throwInvalid(CONFIG_INVALID, `Invalid SearchResultPayload: "groups[${i}]" must hold a values object`);
+    }
+    if (Object.keys(entry.values).length > MAX_FACET_FIELDS) {
+      throwInvalid(
+        CONFIG_INVALID,
+        `Invalid SearchResultPayload: "groups[${i}].values" exceeds maximum field count of ${MAX_FACET_FIELDS}`
+      );
+    }
+    if (!Array.isArray(entry.scored)) {
+      throwInvalid(CONFIG_INVALID, `Invalid SearchResultPayload: "groups[${i}].scored" must be an array`);
+    }
+    if (entry.scored.length > MAX_RESULTS_PER_PARTITION) {
+      throwInvalid(
+        CONFIG_INVALID,
+        `Invalid SearchResultPayload: "groups[${i}].scored" exceeds maximum length of ${MAX_RESULTS_PER_PARTITION}`,
+        { length: entry.scored.length, limit: MAX_RESULTS_PER_PARTITION }
+      );
+    }
+    for (let j = 0; j < entry.scored.length; j++) {
+      validateScoredEntry(entry.scored[j], `groups[${i}].scored[${j}]`);
+    }
+  }
+}
 function validateSearchResultPayload(decoded) {
   if (!isRecord2(decoded)) {
     throwInvalid(CONFIG_INVALID, "Invalid SearchResultPayload: expected an object");
@@ -6862,6 +7330,9 @@ function validateSearchResultPayload(decoded) {
   if (decoded.facetErrorBounds !== null && decoded.facetErrorBounds !== void 0) {
     validateFacetErrorBounds(decoded.facetErrorBounds);
   }
+  if (decoded.groups !== null && decoded.groups !== void 0) {
+    validateGroupEntries(decoded.groups);
+  }
   return decoded;
 }
 
@@ -7008,21 +7479,52 @@ function wireParamsToLocal(wire, facetShardSize) {
     tolerance: wire.tolerance ?? void 0,
     minScore: wire.threshold ?? void 0,
     includeScores: wire.includeScores ?? void 0,
+    termMatch: wire.termMatch ?? void 0,
+    prefixLength: wire.prefixLength ?? void 0,
+    prefix: wire.prefix ?? void 0,
+    exact: wire.exact ?? void 0,
+    pinned: wire.pinned !== null ? wire.pinned.map((entry) => ({ docId: entry.docId, position: entry.position })) : void 0,
+    mode: wire.mode ?? void 0,
     limit: wire.limit,
     offset: wire.offset,
     searchAfter: wire.searchAfter ?? void 0,
     sort: convertWireSortToLocal(wire.sort),
-    group: wire.group !== null ? { fields: [wire.group.field], maxPerGroup: wire.group.maxPerGroup } : void 0,
+    group: convertWireGroupToLocal(wire.group),
     facets: convertWireFacetConfigToLocal(wire.facets, facetShardSize ?? wire.facetSize),
-    vector: wire.vector !== null ? {
-      field: wire.vector.field,
-      value: wire.vector.value ?? void 0,
-      text: wire.vector.text ?? void 0,
-      similarity: wire.vector.similarity ?? void 0
-    } : void 0,
-    hybrid: wire.hybrid !== null ? { strategy: wire.hybrid.strategy, k: wire.hybrid.k, alpha: wire.hybrid.alpha } : void 0
+    vector: convertWireVectorToLocal(wire.vector),
+    hybrid: convertWireHybridToLocal(wire.hybrid)
   };
 }
+function convertWireGroupToLocal(group) {
+  if (group === null) {
+    return void 0;
+  }
+  const local = { fields: [...group.fields], maxPerGroup: group.maxPerGroup };
+  if (group.limit !== null) local.limit = group.limit;
+  return local;
+}
+function convertWireVectorToLocal(vector) {
+  if (vector === null) {
+    return void 0;
+  }
+  const local = { field: vector.field };
+  if (vector.value !== null) local.value = vector.value;
+  if (vector.text !== null) local.text = vector.text;
+  if (vector.similarity !== null) local.similarity = vector.similarity;
+  if (vector.metric !== null) local.metric = vector.metric;
+  if (vector.efSearch !== null) local.efSearch = vector.efSearch;
+  return local;
+}
+function convertWireHybridToLocal(hybrid) {
+  if (hybrid === null) {
+    return void 0;
+  }
+  const local = {};
+  if (hybrid.strategy !== null) local.strategy = hybrid.strategy;
+  if (hybrid.k !== null) local.k = hybrid.k;
+  if (hybrid.alpha !== null) local.alpha = hybrid.alpha;
+  return local;
+}
 function convertWireSortToLocal(wireSort) {
   if (wireSort === null || wireSort.length === 0) {
     return void 0;
@@ -7056,6 +7558,12 @@ function localParamsToWire(params) {
     threshold: params.minScore ?? null,
     includeScores: params.includeScores ?? null,
     scoring: params.scoring ?? "local",
+    termMatch: params.termMatch ?? null,
+    prefixLength: params.prefixLength ?? null,
+    prefix: params.prefix ?? null,
+    exact: params.exact ?? null,
+    pinned: params.pinned !== void 0 ? params.pinned.map((entry) => ({ docId: entry.docId, position: entry.position })) : null,
+    mode: params.mode ?? null,
     vector: convertLocalVectorToWire(params.vector),
     hybrid: convertLocalHybridToWire(params.hybrid)
   };
@@ -7083,8 +7591,9 @@ function convertLocalGroupToWire(group) {
     return null;
   }
   return {
-    field: group.fields[0],
-    maxPerGroup: group.maxPerGroup ?? 1
+    fields: [...group.fields],
+    maxPerGroup: group.maxPerGroup ?? 1,
+    limit: group.limit ?? null
   };
 }
 function convertLocalFacetsToWire(facets) {
@@ -7101,7 +7610,9 @@ function convertLocalVectorToWire(vector) {
     field: vector.field,
     value: vector.value === void 0 ? null : Array.from(vector.value),
     text: vector.text ?? null,
-    similarity: vector.similarity ?? null
+    similarity: vector.similarity ?? null,
+    metric: vector.metric ?? null,
+    efSearch: vector.efSearch ?? null
   };
 }
 function convertLocalHybridToWire(hybrid) {
@@ -7109,9 +7620,9 @@ function convertLocalHybridToWire(hybrid) {
     return null;
   }
   return {
-    strategy: hybrid.strategy ?? "rrf",
-    k: hybrid.k ?? 60,
-    alpha: hybrid.alpha ?? 0.5
+    strategy: hybrid.strategy ?? null,
+    k: hybrid.k ?? null,
+    alpha: hybrid.alpha ?? null
   };
 }
 function convertWireFacetsToLocal(wireFacets, errorBounds) {
@@ -7133,6 +7644,9 @@ async function handleSearch(message, respond, deps) {
   const decoded = decode(message.payload);
   const payload = validateSearchPayload(decoded);
   const queryParams = wireParamsToLocal(payload.params, payload.facetShardSize);
+  if (queryParams.group?.limit !== void 0) {
+    queryParams.group = { ...queryParams.group, limit: oversampledShardSize(queryParams.group.limit) };
+  }
   const queryResult = await deps.engine.queryPartitions(
     payload.indexName,
     queryParams,
@@ -7153,7 +7667,8 @@ async function handleSearch(message, respond, deps) {
   const resultPayload = {
     results,
     facets: convertLocalFacetsToWire2(queryResult.facets),
-    facetErrorBounds: convertLocalFacetBoundsToWire(queryResult.facets)
+    facetErrorBounds: convertLocalFacetBoundsToWire(queryResult.facets),
+    groups: await convertLocalGroupsToWire(queryResult.groups, sortFields, deps, payload.indexName)
   };
   await respond({
     type: QueryMessageTypes.SEARCH_RESULT,
@@ -7162,6 +7677,25 @@ async function handleSearch(message, respond, deps) {
     payload: encode(resultPayload)
   });
 }
+async function convertLocalGroupsToWire(groups, sortFields, deps, indexName) {
+  if (groups === void 0) {
+    return null;
+  }
+  const wireGroups = [];
+  for (const group of groups) {
+    const scored = [];
+    for (const hit of group.hits) {
+      let sortValues = null;
+      if (sortFields !== null) {
+        const document = hit.document ?? await deps.engine.get(indexName, hit.id);
+        sortValues = readSortValues(document, sortFields).map(toWireSortValue);
+      }
+      scored.push({ docId: hit.id, score: hit.score ?? null, sortValues });
+    }
+    wireGroups.push({ values: group.values, scored });
+  }
+  return wireGroups;
+}
 async function handleFetch(message, respond, deps) {
   const decoded = decode(message.payload);
   const payload = validateFetchPayload(decoded);
@@ -7188,7 +7722,7 @@ async function handleFetch(message, respond, deps) {
 async function handleStats(message, respond, deps) {
   const decoded = decode(message.payload);
   const payload = validateStatsPayload(decoded);
-  const resultPayload = deps.engine.collectQueryStats(
+  const resultPayload = await deps.engine.collectQueryStats(
     payload.indexName,
     payload.terms,
     payload.partitionIds
@@ -7229,7 +7763,7 @@ function convertLocalFacetsToWire2(facets) {
 async function handleCount(message, respond, deps) {
   const payload = validateCountPayload(decode(message.payload));
   const requested = new Set(payload.partitionIds);
-  const partitions = deps.engine.getPartitionStats(payload.indexName).filter((partition) => requested.has(partition.partitionId)).map((partition) => ({
+  const partitions = (await deps.engine.partitionStatsForRead(payload.indexName)).filter((partition) => requested.has(partition.partitionId)).map((partition) => ({
     partitionId: partition.partitionId,
     documentCount: partition.documentCount,
     estimatedMemoryBytes: partition.estimatedMemoryBytes
@@ -7379,59 +7913,65 @@ async function handleSyncRequestMessage(message, respond, deps) {
       }
     );
   }
-  if (!deps.engine.listIndexes().some((index) => index.name === request.indexName)) {
+  const localIndex = deps.engine.listIndexes().find((index) => index.name === request.indexName);
+  if (localIndex === void 0) {
     throw new NarsilError(
       ErrorCodes.SNAPSHOT_SYNC_INDEX_NOT_FOUND,
       `Node '${deps.nodeId}' holds no copy of index '${request.indexName}' yet, so it cannot serve a sync for partition ${request.partitionId}`,
       { indexName: request.indexName, partitionId: request.partitionId, primaryNodeId: deps.nodeId }
     );
   }
-  if (message.sourceId !== deps.nodeId) {
-    recordReplicaPosition(
-      deps.writeDeps.catchUp,
-      request.indexName,
-      request.partitionId,
-      message.sourceId,
-      request.lastSeqNo
-    );
-  }
-  const log = deps.writeDeps.getReplicationLog(request.indexName, request.partitionId);
-  const tier = decideSyncTier(log, request.lastSeqNo);
-  if (tier === "incremental") {
-    await sendSyncEntriesResponse(message, respond, deps, log.getEntriesFrom(request.lastSeqNo + 1));
-    return;
-  }
-  const snapshotSeqNo = log.localLogEnd;
-  const sink = createSingleResponseSink(respond);
-  await streamValidatedSnapshotRequest(
-    message,
-    sink,
-    { indexName: request.indexName, partitionId: request.partitionId },
-    {
-      nodeId: deps.nodeId,
-      engine: deps.engine,
-      coordinator: deps.coordinator,
-      state: deps.snapshotSyncState,
-      resolveHeaderMetadata: deps.resolveHeaderMetadata
-    },
-    {
-      metadata: {
-        partitionId: request.partitionId,
-        lastSeqNo: snapshotSeqNo,
-        primaryTerm: assignment.primaryTerm
-      },
-      closeOnEnd: false,
-      disableBuildCache: true,
-      buildSnapshot: async () => {
-        const bytes = await deps.engine.serializeReplicationPartition(request.indexName, request.partitionId);
-        return { bytes, checksum: crc32(bytes) };
+  const release = await deps.engine.acquireIndexForReplication(request.indexName);
+  try {
+    if (message.sourceId !== deps.nodeId) {
+      recordReplicaPosition(
+        deps.writeDeps.catchUp,
+        request.indexName,
+        request.partitionId,
+        message.sourceId,
+        request.lastSeqNo
+      );
+    }
+    const log = deps.writeDeps.getReplicationLog(request.indexName, request.partitionId);
+    const tier = decideSyncTier(log, request.lastSeqNo);
+    if (tier === "incremental") {
+      await sendSyncEntriesResponse(message, respond, deps, log.getEntriesFrom(request.lastSeqNo + 1));
+      return;
+    }
+    const snapshotSeqNo = log.localLogEnd;
+    const sink = createSingleResponseSink(respond);
+    await streamValidatedSnapshotRequest(
+      message,
+      sink,
+      { indexName: request.indexName, partitionId: request.partitionId },
+      {
+        nodeId: deps.nodeId,
+        engine: deps.engine,
+        coordinator: deps.coordinator,
+        state: deps.snapshotSyncState,
+        resolveHeaderMetadata: deps.resolveHeaderMetadata
       },
-      afterSnapshot: async (trailingSink) => {
-        const entries = log.getEntriesFrom(snapshotSeqNo + 1);
-        await sendSyncEntriesResponse(message, trailingSink, deps, entries);
+      {
+        metadata: {
+          partitionId: request.partitionId,
+          lastSeqNo: snapshotSeqNo,
+          primaryTerm: assignment.primaryTerm
+        },
+        closeOnEnd: false,
+        disableBuildCache: true,
+        buildSnapshot: async () => {
+          const bytes = await deps.engine.serializeReplicationPartition(request.indexName, request.partitionId);
+          return { bytes, checksum: crc32(bytes) };
+        },
+        afterSnapshot: async (trailingSink) => {
+          const entries = log.getEntriesFrom(snapshotSeqNo + 1);
+          await sendSyncEntriesResponse(message, trailingSink, deps, entries);
+        }
       }
-    }
-  );
+    );
+  } finally {
+    release();
+  }
 }
 async function sendSyncEntriesResponse(message, respond, deps, entries) {
   const payload = {
@@ -7503,6 +8043,37 @@ var DEFAULT_CAPACITY = {
   cpuCores: 4,
   diskBytes: null
 };
+
+// src/distribution/cluster-node/transport-failure.ts
+var FAILURE_CODE_BY_TRANSPORT_CODE = {
+  [TransportErrorCodes.CONNECT_FAILED]: ErrorCodes.QUERY_NO_ACTIVE_REPLICA,
+  [TransportErrorCodes.PEER_UNAVAILABLE]: ErrorCodes.QUERY_NO_ACTIVE_REPLICA,
+  [TransportErrorCodes.TIMEOUT]: ErrorCodes.QUERY_NODE_TIMEOUT,
+  [TransportErrorCodes.MESSAGE_TOO_LARGE]: ErrorCodes.QUERY_ROUTING_FAILED,
+  [TransportErrorCodes.DECODE_FAILED]: ErrorCodes.QUERY_ROUTING_FAILED
+};
+function narsilErrorFromTransportFailure(error, message, details) {
+  return new NarsilError(FAILURE_CODE_BY_TRANSPORT_CODE[error.code], message, {
+    ...details,
+    transportCode: error.code
+  });
+}
+async function sendThroughTargets(targets, send, failure) {
+  let lastError;
+  for (const target of targets) {
+    try {
+      return await send(target);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  if (lastError instanceof TransportError) {
+    throw narsilErrorFromTransportFailure(lastError, failure.message, failure.details ?? {});
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+// src/distribution/cluster-node/write-routing/forwarding.ts
 function assertForwardResponse(response, indexName, primaryNodeId) {
   const decoded = decode(response.payload);
   if (response.type.endsWith(".error") || response.type === "error" || decoded.error === true) {
@@ -7560,15 +8131,10 @@ async function forwardRemoveToRemote(indexName, docId, primaryNodeId, deps) {
 }
 async function sendToNode(nodeId, message, deps) {
   const targets = await resolveNodeTargets(nodeId, deps);
-  let lastError;
-  for (const target of targets) {
-    try {
-      return await deps.transport.send(target, message);
-    } catch (error) {
-      lastError = error;
-    }
-  }
-  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+  return sendThroughTargets(targets, (target) => deps.transport.send(target, message), {
+    message: `Node '${nodeId}' did not answer a forwarded write`,
+    details: { targetNodeId: nodeId }
+  });
 }
 async function assertPrimaryWriteAuthority(entry, deps) {
   const table = await deps.coordinator.getAllocation(entry.indexName);
@@ -7645,24 +8211,15 @@ async function removeFailedReplicasFromInsync(entry, failedReplicas, deps) {
 }
 async function requestInsyncRemovalWithTargets(indexName, partitionId, replicaNodeId, primaryTerm, controllerNodeId, deps) {
   const targets = await resolveNodeTargets(controllerNodeId, deps);
-  let lastError;
-  for (const target of targets) {
-    try {
-      const result = await requestInsyncRemoval(
-        indexName,
-        partitionId,
-        replicaNodeId,
-        primaryTerm,
-        target,
-        deps.transport,
-        deps.nodeId
-      );
-      return result.accepted;
-    } catch (error) {
-      lastError = error;
+  const result = await sendThroughTargets(
+    targets,
+    (target) => requestInsyncRemoval(indexName, partitionId, replicaNodeId, primaryTerm, target, deps.transport, deps.nodeId),
+    {
+      message: `Controller '${controllerNodeId}' did not answer an in-sync removal request for index '${indexName}' partition ${partitionId}`,
+      details: { indexName, partitionId, replicaNodeId, controllerNodeId }
     }
-  }
-  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+  );
+  return result.accepted;
 }
 async function replicateEntry(entry, assignment, deps) {
   const pending = getPendingAdmissions(deps.catchUp, entry.indexName, entry.partitionId);
@@ -8908,17 +9465,12 @@ async function resolveNodeTargets2(config, targetNodeId) {
   }
   return targets;
 }
-async function sendToNode2(config, targetNodeId, message) {
+async function sendToNode2(config, targetNodeId, message, failure) {
   const targets = await resolveNodeTargets2(config, targetNodeId);
-  let lastError;
-  for (const target of targets) {
-    try {
-      return await config.transport.send(target, message);
-    } catch (error) {
-      lastError = error;
-    }
-  }
-  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+  return sendThroughTargets(targets, (target) => config.transport.send(target, message), {
+    message: failure?.message ?? `Node '${targetNodeId}' did not answer a cluster request`,
+    details: { targetNodeId, ...failure?.details }
+  });
 }
 function fetchFieldsFor(projection) {
   if (projection.kind !== "fields" || projection.include === null) return null;
@@ -8966,7 +9518,10 @@ async function fetchDistributedDocuments(config, nodeId, engine, indexName, resu
       },
       nodeId
     );
-    const response = await sendToNode2(config, targetNodeId, fetchMessage);
+    const response = await sendToNode2(config, targetNodeId, fetchMessage, {
+      message: `Node '${targetNodeId}' did not answer a document fetch for index '${indexName}'`,
+      details: { indexName }
+    });
     const decoded = decode(response.payload);
     const payload = validateFetchResultPayload(decoded);
     for (const fetched of payload.documents) {
@@ -9014,7 +9569,10 @@ async function readDistributedDocuments(config, nodeId, engine, indexName, docId
       continue;
     }
     const fetchMessage = createFetchMessage({ indexName, documentIds, fields: null, highlight: null }, nodeId);
-    const response = await sendToNode2(config, targetNodeId, fetchMessage);
+    const response = await sendToNode2(config, targetNodeId, fetchMessage, {
+      message: `Node '${targetNodeId}' did not answer a document fetch for index '${indexName}'`,
+      details: { indexName }
+    });
     const payload = validateFetchResultPayload(decode(response.payload));
     for (const fetched of payload.documents) {
       documents.set(fetched.docId, fetched.document);
@@ -9162,79 +9720,6 @@ function isTimeoutError(error) {
   return error instanceof TransportError && error.code === "TRANSPORT_TIMEOUT";
 }
 
-// src/distribution/query/fusion.ts
-function clampAlpha(alpha) {
-  if (!Number.isFinite(alpha)) return 0.5;
-  if (alpha < 0) return 0;
-  if (alpha > 1) return 1;
-  return alpha;
-}
-function compareFusedEntries(a, b) {
-  const aScore = a.score ?? 0;
-  const bScore = b.score ?? 0;
-  if (aScore !== bScore) {
-    return bScore - aScore;
-  }
-  return compareCodePoints(a.docId, b.docId);
-}
-function distributedRRF(lists, options) {
-  const k = options.k > 0 ? options.k : 60;
-  const scores = /* @__PURE__ */ new Map();
-  for (const list of lists) {
-    for (let rank = 0; rank < list.length; rank++) {
-      const entry = list[rank];
-      const rrfContribution = 1 / (k + rank + 1);
-      scores.set(entry.docId, (scores.get(entry.docId) ?? 0) + rrfContribution);
-    }
-  }
-  const result = [];
-  for (const [docId, score] of scores) {
-    result.push({ docId, score, sortValues: null });
-  }
-  result.sort(compareFusedEntries);
-  return result;
-}
-function distributedLinearCombination(textResults, vectorResults, options) {
-  const { alpha } = options;
-  const normalizedText = minMaxNormalizeScoredEntries(textResults);
-  const normalizedVector = minMaxNormalizeScoredEntries(vectorResults);
-  const textScoreMap = /* @__PURE__ */ new Map();
-  for (const entry of normalizedText) {
-    textScoreMap.set(entry.docId, entry.score);
-  }
-  const vectorScoreMap = /* @__PURE__ */ new Map();
-  for (const entry of normalizedVector) {
-    vectorScoreMap.set(entry.docId, entry.score);
-  }
-  const allDocIds = /* @__PURE__ */ new Set();
-  for (const entry of textResults) allDocIds.add(entry.docId);
-  for (const entry of vectorResults) allDocIds.add(entry.docId);
-  const result = [];
-  for (const docId of allDocIds) {
-    const tScore = textScoreMap.get(docId) ?? 0;
-    const vScore = vectorScoreMap.get(docId) ?? 0;
-    const combined = alpha * vScore + (1 - alpha) * tScore;
-    result.push({ docId, score: combined, sortValues: null });
-  }
-  result.sort(compareFusedEntries);
-  return result;
-}
-function minMaxNormalizeScoredEntries(entries) {
-  if (entries.length === 0) return [];
-  let min = entries[0].score ?? 0;
-  let max = entries[0].score ?? 0;
-  for (let i = 1; i < entries.length; i++) {
-    const score = entries[i].score ?? 0;
-    if (score < min) min = score;
-    if (score > max) max = score;
-  }
-  const range = max - min;
-  if (range === 0) {
-    return entries.map((e) => ({ docId: e.docId, score: 1 }));
-  }
-  return entries.map((e) => ({ docId: e.docId, score: ((e.score ?? 0) - min) / range }));
-}
-
 // src/distribution/query/merge.ts
 function compareByScoreThenId(a, b) {
   const aScore = a.score ?? Number.NEGATIVE_INFINITY;
@@ -9396,6 +9881,241 @@ function mergeDistributedFacets(allFacets, allBounds, maxBuckets = DEFAULT_MAX_F
   return { facets, errorBounds };
 }
 
+// src/distribution/query/group-merge.ts
+function mergeDistributedGroups(perNode, fields, maxPerGroup, limit, sortDirections) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const groups of perNode) {
+    for (const group of groups) {
+      const key = JSON.stringify(fields.map((field) => group.values[field]));
+      const existing = byKey.get(key);
+      if (existing === void 0) {
+        byKey.set(key, { values: group.values, lists: [group.scored] });
+      } else {
+        existing.lists.push(group.scored);
+      }
+    }
+  }
+  const merged = [];
+  for (const entry of byKey.values()) {
+    const scored = sortDirections !== null ? mergeAndTruncateSortedEntries(entry.lists, maxPerGroup, sortDirections) : mergeAndTruncateScoredEntries(entry.lists, maxPerGroup);
+    merged.push({ values: entry.values, scored });
+  }
+  merged.sort((a, b) => {
+    const aScore = a.scored.length > 0 ? a.scored[0].score ?? 0 : 0;
+    const bScore = b.scored.length > 0 ? b.scored[0].score ?? 0 : 0;
+    if (aScore !== bScore) return bScore - aScore;
+    const aId = a.scored.length > 0 ? a.scored[0].docId : "";
+    const bId = b.scored.length > 0 ? b.scored[0].docId : "";
+    return compareCodePoints(aId, bId);
+  });
+  if (limit !== null && merged.length > limit) {
+    merged.length = limit;
+  }
+  return merged;
+}
+function mergeGroupsFor(params, allGroups, sortFields) {
+  if (params.group === null || allGroups.length === 0) {
+    return null;
+  }
+  return mergeDistributedGroups(
+    allGroups,
+    params.group.fields,
+    params.group.maxPerGroup,
+    params.group.limit,
+    sortFields !== null ? sortFields.map((field) => field.direction) : null
+  );
+}
+
+// src/distribution/query/fusion.ts
+function clampAlpha(alpha) {
+  if (!Number.isFinite(alpha)) return 0.5;
+  if (alpha < 0) return 0;
+  if (alpha > 1) return 1;
+  return alpha;
+}
+function compareFusedEntries(a, b) {
+  const aScore = a.score ?? 0;
+  const bScore = b.score ?? 0;
+  if (aScore !== bScore) {
+    return bScore - aScore;
+  }
+  return compareCodePoints(a.docId, b.docId);
+}
+function distributedRRF(lists, options) {
+  const k = options.k > 0 ? options.k : 60;
+  const scores = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const entry = list[rank];
+      const rrfContribution = 1 / (k + rank + 1);
+      scores.set(entry.docId, (scores.get(entry.docId) ?? 0) + rrfContribution);
+    }
+  }
+  const result = [];
+  for (const [docId, score] of scores) {
+    result.push({ docId, score, sortValues: null });
+  }
+  result.sort(compareFusedEntries);
+  return result;
+}
+function distributedLinearCombination(textResults, vectorResults, options) {
+  const { alpha } = options;
+  const normalizedText = minMaxNormalizeScoredEntries(textResults);
+  const normalizedVector = minMaxNormalizeScoredEntries(vectorResults);
+  const textScoreMap = /* @__PURE__ */ new Map();
+  for (const entry of normalizedText) {
+    textScoreMap.set(entry.docId, entry.score);
+  }
+  const vectorScoreMap = /* @__PURE__ */ new Map();
+  for (const entry of normalizedVector) {
+    vectorScoreMap.set(entry.docId, entry.score);
+  }
+  const allDocIds = /* @__PURE__ */ new Set();
+  for (const entry of textResults) allDocIds.add(entry.docId);
+  for (const entry of vectorResults) allDocIds.add(entry.docId);
+  const result = [];
+  for (const docId of allDocIds) {
+    const tScore = textScoreMap.get(docId) ?? 0;
+    const vScore = vectorScoreMap.get(docId) ?? 0;
+    const combined = alpha * vScore + (1 - alpha) * tScore;
+    result.push({ docId, score: combined, sortValues: null });
+  }
+  result.sort(compareFusedEntries);
+  return result;
+}
+function minMaxNormalizeScoredEntries(entries) {
+  if (entries.length === 0) return [];
+  let min = entries[0].score ?? 0;
+  let max = entries[0].score ?? 0;
+  for (let i = 1; i < entries.length; i++) {
+    const score = entries[i].score ?? 0;
+    if (score < min) min = score;
+    if (score > max) max = score;
+  }
+  const range = max - min;
+  if (range === 0) {
+    return entries.map((e) => ({ docId: e.docId, score: 1 }));
+  }
+  return entries.map((e) => ({ docId: e.docId, score: ((e.score ?? 0) - min) / range }));
+}
+
+// src/distribution/query/pinning.ts
+function lastOrganicEntry(page, pinned) {
+  if (pinned === null) {
+    return page.length > 0 ? page[page.length - 1] : void 0;
+  }
+  const pinnedIds = new Set(pinned.map((entry) => entry.docId));
+  for (let i = page.length - 1; i >= 0; i--) {
+    if (!pinnedIds.has(page[i].docId)) return page[i];
+  }
+  return void 0;
+}
+function placePinnedEntries(merged, pinned, depth, allMatchesPresent) {
+  const deduped = dedupePinnedEntries(pinned);
+  const pinnedIds = new Set(deduped.map((entry) => entry.docId));
+  const removed = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const entry of merged) {
+    if (pinnedIds.has(entry.docId)) {
+      removed.set(entry.docId, entry);
+    } else {
+      result.push(entry);
+    }
+  }
+  const ordered = deduped.sort((a, b) => a.position - b.position);
+  for (const entry of ordered) {
+    if (!allMatchesPresent && entry.position >= depth) continue;
+    const organic = removed.get(entry.docId);
+    const placed = { docId: entry.docId, score: 0, sortValues: organic?.sortValues ?? null };
+    result.splice(Math.max(0, Math.min(entry.position, result.length)), 0, placed);
+  }
+  return result;
+}
+
+// src/distribution/query/hybrid.ts
+async function executeHybridQuery(indexName, params, limit, offset, facetShardSize, facetSize, totalPartitions, routing, deps, config) {
+  const depth = limit + offset;
+  const textParams = { ...params, vector: null, hybrid: null, mode: null, limit: depth, offset: 0 };
+  const vectorParams = {
+    ...params,
+    term: null,
+    hybrid: null,
+    mode: null,
+    group: null,
+    limit: depth,
+    offset: 0
+  };
+  let textGlobalStats = null;
+  if (params.scoring === "dfs") {
+    textGlobalStats = await collectDistributedStats(indexName, textParams, routing.nodeToPartitions, deps, config);
+  }
+  const [textOutcomes, vectorOutcomes] = await Promise.all([
+    fanOutSearch(indexName, textParams, textGlobalStats, facetShardSize, routing.nodeToPartitions, deps, config),
+    fanOutSearch(indexName, vectorParams, null, null, routing.nodeToPartitions, deps, config)
+  ]);
+  const coverage = buildCoverage(totalPartitions, routing.unavailablePartitions, textOutcomes, vectorOutcomes);
+  if (!config.allowPartialResults) {
+    const failedCount = coverage.timedOutPartitions + coverage.failedPartitions;
+    if (failedCount > 0) {
+      throw new NarsilError(ErrorCodes.QUERY_PARTIAL_FAILURE, "One or more partitions failed during hybrid query", {
+        coverage
+      });
+    }
+  }
+  const textScored = [];
+  const vectorScored = [];
+  const allFacets = [];
+  const allFacetBounds = [];
+  const allGroups = [];
+  let totalHits = 0;
+  for (const outcome of textOutcomes) {
+    if (outcome.status !== "success" || outcome.results === null) continue;
+    for (const partitionResult of outcome.results.results) {
+      totalHits += partitionResult.totalHits;
+      if (partitionResult.scored.length > 0) {
+        textScored.push(partitionResult.scored);
+      }
+    }
+    if (outcome.results.facets !== null) {
+      allFacets.push(outcome.results.facets);
+      allFacetBounds.push(outcome.results.facetErrorBounds);
+    }
+    if (outcome.results.groups !== null && outcome.results.groups !== void 0) {
+      allGroups.push(outcome.results.groups);
+    }
+  }
+  for (const outcome of vectorOutcomes) {
+    if (outcome.status !== "success" || outcome.results === null) continue;
+    for (const partitionResult of outcome.results.results) {
+      if (partitionResult.scored.length > 0) {
+        vectorScored.push(partitionResult.scored);
+      }
+    }
+  }
+  const mergedText = mergeAndTruncateScoredEntries(textScored, depth);
+  const mergedVector = mergeAndTruncateScoredEntries(vectorScored, depth);
+  const hybrid = params.hybrid;
+  let fused;
+  if ((hybrid?.strategy ?? "rrf") === "rrf") {
+    fused = distributedRRF([mergedText, mergedVector], { k: hybrid?.k ?? 60 });
+  } else {
+    fused = distributedLinearCombination(mergedText, mergedVector, { alpha: clampAlpha(hybrid?.alpha ?? 0.5) });
+  }
+  const allMatchesPresent = coverage.queriedPartitions === coverage.totalPartitions && totalHits <= mergedText.length && mergedVector.length < depth;
+  const fusedWithPinned = params.pinned !== null ? placePinnedEntries(fused, params.pinned, depth, allMatchesPresent) : fused;
+  const truncated = fusedWithPinned.slice(offset, depth);
+  const mergedFacets = allFacets.length > 0 ? mergeDistributedFacets(allFacets, allFacetBounds, facetSize) : null;
+  return {
+    scored: truncated,
+    totalHits,
+    facets: mergedFacets?.facets ?? null,
+    facetErrorBounds: mergedFacets?.errorBounds ?? null,
+    groups: mergeGroupsFor(params, allGroups, null),
+    cursor: null,
+    coverage
+  };
+}
+
 // src/distribution/query/types.ts
 var DEFAULT_QUERY_CONFIG = {
   allowPartialResults: true,
@@ -9418,16 +10138,17 @@ async function distributedQuery(indexName, params, deps, config, selector) {
     ...DEFAULT_QUERY_CONFIG,
     ...config
   };
+  const binding = queryBindingOf(wireParamsToLocal(params));
   if (params.searchAfter !== null) {
     const decoded = decodePageCursor(params.searchAfter);
-    requireMatchingCursor(decoded, params.searchAfter, wireSortSignature(params.sort), true);
+    requireMatchingCursor(decoded, params.searchAfter, wireSortSignature(params.sort), true, binding);
   }
   const limit = Math.max(params.limit, 0);
   const offset = Math.max(params.offset, 0);
   requireWithinResultWindow(limit, offset);
   const hasFacets = params.facets !== null && params.facets.length > 0;
   const facetSize = resolveAndClampFacetSize(params.facetSize, resolvedConfig.defaultFacetSize);
-  const facetShardSize = hasFacets ? Math.ceil(facetSize * 1.5) + 10 : null;
+  const facetShardSize = hasFacets ? oversampledShardSize(facetSize) : null;
   const allocationTable = await deps.getAllocation(indexName);
   if (allocationTable === null) {
     throw new NarsilError(ErrorCodes.QUERY_ROUTING_FAILED, `No allocation table found for index '${indexName}'`, {
@@ -9440,6 +10161,7 @@ async function distributedQuery(indexName, params, deps, config, selector) {
       totalHits: 0,
       facets: null,
       facetErrorBounds: null,
+      groups: null,
       cursor: null,
       coverage: { totalPartitions: 0, queriedPartitions: 0, timedOutPartitions: 0, failedPartitions: 0 }
     };
@@ -9453,11 +10175,13 @@ async function distributedQuery(indexName, params, deps, config, selector) {
       { unavailablePartitions: routing.unavailablePartitions }
     );
   }
-  const isHybrid = params.hybrid !== null && params.term !== null && params.vector !== null;
+  const isHybrid = params.vector !== null && (params.term !== null || params.mode === "hybrid");
   if (isHybrid && params.searchAfter !== null) {
-    throw new NarsilError(ErrorCodes.QUERY_ROUTING_FAILED, "Cursor pagination is not supported for hybrid queries", {
-      indexName
-    });
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_CURSOR,
+      "Cursor pagination is not supported for hybrid queries, because fused ranks do not seek",
+      { indexName }
+    );
   }
   if (isHybrid && params.sort !== null && params.sort.length > 0) {
     throw new NarsilError(
@@ -9483,6 +10207,7 @@ async function distributedQuery(indexName, params, deps, config, selector) {
   return executeSingleFanOut(
     indexName,
     params,
+    binding,
     limit,
     offset,
     facetShardSize,
@@ -9493,7 +10218,7 @@ async function distributedQuery(indexName, params, deps, config, selector) {
     resolvedConfig
   );
 }
-async function executeSingleFanOut(indexName, params, limit, offset, facetShardSize, facetSize, totalPartitions, routing, deps, config) {
+async function executeSingleFanOut(indexName, params, binding, limit, offset, facetShardSize, facetSize, totalPartitions, routing, deps, config) {
   let globalStats = null;
   if (params.scoring === "dfs") {
     globalStats = await collectDistributedStats(indexName, params, routing.nodeToPartitions, deps, config);
@@ -9525,6 +10250,7 @@ async function executeSingleFanOut(indexName, params, limit, offset, facetShardS
   const allScored = [];
   const allFacets = [];
   const allFacetBounds = [];
+  const allGroups = [];
   let totalHits = 0;
   for (const outcome of outcomes) {
     if (outcome.status !== "success" || outcome.results === null) continue;
@@ -9538,29 +10264,43 @@ async function executeSingleFanOut(indexName, params, limit, offset, facetShardS
       allFacets.push(outcome.results.facets);
       allFacetBounds.push(outcome.results.facetErrorBounds);
     }
+    if (outcome.results.groups !== null && outcome.results.groups !== void 0) {
+      allGroups.push(outcome.results.groups);
+    }
   }
   const merged = sortFields !== null ? mergeAndTruncateSortedEntries(
     allScored,
     depth,
     sortFields.map((field) => field.direction)
   ) : mergeAndTruncateScoredEntries(allScored, depth);
-  const mergedScored = offset > 0 ? merged.slice(offset) : merged;
+  const allMatchesPresent = coverage.queriedPartitions === coverage.totalPartitions && totalHits <= merged.length;
+  const placed = params.pinned !== null && params.searchAfter === null ? placePinnedEntries(merged, params.pinned, depth, allMatchesPresent) : merged;
+  const mergedScored = placed.slice(offset, depth);
   const mergedFacets = allFacets.length > 0 ? mergeDistributedFacets(allFacets, allFacetBounds, facetSize) : null;
+  const mergedGroups = mergeGroupsFor(params, allGroups, sortFields);
   let cursor = null;
-  if (mergedScored.length > 0) {
-    const lastEntry = mergedScored[mergedScored.length - 1];
+  const lastEntry = lastOrganicEntry(mergedScored, params.searchAfter === null ? params.pinned : null);
+  if (lastEntry !== void 0) {
     cursor = sortFields !== null ? encodePageCursor({
       anchor: lastEntry.docId,
       score: null,
       sortKey: (lastEntry.sortValues ?? []).map(toComparableSortValue),
-      sortSignature: wireSortSignature(sortFields)
-    }) : encodePageCursor({ anchor: lastEntry.docId, score: lastEntry.score, sortKey: null, sortSignature: null });
+      sortSignature: wireSortSignature(sortFields),
+      binding
+    }) : encodePageCursor({
+      anchor: lastEntry.docId,
+      score: lastEntry.score,
+      sortKey: null,
+      sortSignature: null,
+      binding
+    });
   }
   return {
     scored: mergedScored,
     totalHits,
     facets: mergedFacets?.facets ?? null,
     facetErrorBounds: mergedFacets?.errorBounds ?? null,
+    groups: mergedGroups,
     cursor,
     coverage
   };
@@ -9575,79 +10315,73 @@ function failOutcomesMissingSortValues(outcomes) {
     }
   }
 }
-async function executeHybridQuery(indexName, params, limit, offset, facetShardSize, facetSize, totalPartitions, routing, deps, config) {
-  const depth = limit + offset;
-  const textParams = { ...params, vector: null, hybrid: null, limit: depth, offset: 0 };
-  const vectorParams = { ...params, term: null, hybrid: null, limit: depth, offset: 0 };
-  let textGlobalStats = null;
-  if (params.scoring === "dfs") {
-    textGlobalStats = await collectDistributedStats(indexName, textParams, routing.nodeToPartitions, deps, config);
+
+// src/distribution/cluster-node/reads/groups.ts
+async function assembleDistributedGroups(deps, indexName, params, distributed, allocation, projection) {
+  const wireGroups = distributed.groups;
+  const group = params.group;
+  if (wireGroups === null || group === void 0) {
+    return void 0;
   }
-  const [textOutcomes, vectorOutcomes] = await Promise.all([
-    fanOutSearch(indexName, textParams, textGlobalStats, facetShardSize, routing.nodeToPartitions, deps, config),
-    fanOutSearch(indexName, vectorParams, null, null, routing.nodeToPartitions, deps, config)
-  ]);
-  const coverage = buildCoverage(totalPartitions, routing.unavailablePartitions, textOutcomes, vectorOutcomes);
-  if (!config.allowPartialResults) {
-    const failedCount = coverage.timedOutPartitions + coverage.failedPartitions;
-    if (failedCount > 0) {
-      throw new NarsilError(ErrorCodes.QUERY_PARTIAL_FAILURE, "One or more partitions failed during hybrid query", {
-        coverage
-      });
-    }
-  }
-  const textScored = [];
-  const vectorScored = [];
-  const allFacets = [];
-  const allFacetBounds = [];
-  let totalHits = 0;
-  for (const outcome of textOutcomes) {
-    if (outcome.status !== "success" || outcome.results === null) continue;
-    for (const partitionResult of outcome.results.results) {
-      totalHits += partitionResult.totalHits;
-      if (partitionResult.scored.length > 0) {
-        textScored.push(partitionResult.scored);
+  const reduce = group.reduce;
+  const needsDocuments = reduce !== void 0 || projection.kind !== "none";
+  const groupDocIds = [...new Set(wireGroups.flatMap((entry) => entry.scored.map((scored) => scored.docId)))];
+  const documents = needsDocuments && groupDocIds.length > 0 ? await readDistributedDocuments(deps.config, deps.nodeId, deps.engine, indexName, groupDocIds, allocation) : /* @__PURE__ */ new Map();
+  return wireGroups.map((entry) => {
+    const hits = entry.scored.map((scored) => ({
+      id: scored.docId,
+      score: scored.score ?? void 0,
+      document: projectedGroupDocument(documents.get(scored.docId), projection)
+    }));
+    const result = { values: entry.values, hits };
+    if (reduce !== void 0) {
+      const folded = foldGroupReducer(
+        reduce,
+        entry.scored.map((scored) => ({ document: documents.get(scored.docId), score: scored.score ?? 0 }))
+      );
+      if (folded.reducerError !== void 0) {
+        result.reducerError = folded.reducerError;
+      } else {
+        result.reduced = folded.reduced;
       }
     }
-    if (outcome.results.facets !== null) {
-      allFacets.push(outcome.results.facets);
-      allFacetBounds.push(outcome.results.facetErrorBounds);
-    }
+    return result;
+  });
+}
+function projectedGroupDocument(document, projection) {
+  if (document === void 0 || projection.kind === "none") {
+    return {};
   }
-  for (const outcome of vectorOutcomes) {
-    if (outcome.status !== "success" || outcome.results === null) continue;
-    for (const partitionResult of outcome.results.results) {
-      if (partitionResult.scored.length > 0) {
-        vectorScored.push(partitionResult.scored);
-      }
+  return applyProjection(document, projection);
+}
+
+// src/distribution/cluster-node/reads/pinned.ts
+function splitPinnedByReachability(pinnedIds, allocation) {
+  const partitionCount = allocation.assignments.size;
+  const verifiable = [];
+  const unverifiable = /* @__PURE__ */ new Set();
+  for (const docId of pinnedIds) {
+    const partitionId = resolvePartitionId(docId, partitionCount);
+    const assignment = allocation.assignments.get(partitionId);
+    const nodeId = assignment === void 0 ? null : selectReplica(assignment, void 0, partitionId);
+    if (nodeId === null) {
+      unverifiable.add(docId);
+    } else {
+      verifiable.push(docId);
     }
   }
-  const mergedText = mergeAndTruncateScoredEntries(textScored, depth);
-  const mergedVector = mergeAndTruncateScoredEntries(vectorScored, depth);
-  const hybrid = params.hybrid;
-  let fused;
-  if (hybrid !== null && hybrid.strategy === "rrf") {
-    fused = distributedRRF([mergedText, mergedVector], { k: hybrid.k });
-  } else if (hybrid !== null) {
-    fused = distributedLinearCombination(mergedText, mergedVector, { alpha: clampAlpha(hybrid.alpha) });
-  } else {
-    fused = mergedText;
-  }
-  const truncated = fused.slice(offset, depth);
-  const mergedFacets = allFacets.length > 0 ? mergeDistributedFacets(allFacets, allFacetBounds, facetSize) : null;
-  let cursor = null;
-  if (truncated.length > 0) {
-    const lastEntry = truncated[truncated.length - 1];
-    cursor = encodePageCursor({ anchor: lastEntry.docId, score: lastEntry.score, sortKey: null, sortSignature: null });
+  return { verifiable, unverifiable };
+}
+async function dropUnstoredPinnedEntries(deps, indexName, params, distributed, allocation, projection, documents) {
+  if (params.pinned === void 0 || params.searchAfter !== void 0) {
+    return distributed.scored;
   }
-  return {
-    scored: truncated,
-    totalHits,
-    facets: mergedFacets?.facets ?? null,
-    facetErrorBounds: mergedFacets?.errorBounds ?? null,
-    cursor,
-    coverage
-  };
+  const pinnedIds = new Set(params.pinned.map((entry) => entry.docId));
+  const { verifiable, unverifiable } = splitPinnedByReachability(pinnedIds, allocation);
+  const stored = projection.kind === "none" ? await readDistributedDocuments(deps.config, deps.nodeId, deps.engine, indexName, verifiable, allocation) : documents;
+  return distributed.scored.filter(
+    (entry) => !pinnedIds.has(entry.docId) || unverifiable.has(entry.docId) || stored.has(entry.docId)
+  );
 }
 function strictScatterGroups(allocation, indexName) {
   const routing = selectReplicasForQuery(allocation, randomSelector);
@@ -9660,29 +10394,10 @@ function strictScatterGroups(allocation, indexName) {
   }
   return Array.from(routing.nodeToPartitions.entries(), ([nodeId, partitionIds]) => ({ nodeId, partitionIds }));
 }
-var READ_FAILURE_BY_TRANSPORT_CODE = {
-  [TransportErrorCodes.CONNECT_FAILED]: ErrorCodes.QUERY_NO_ACTIVE_REPLICA,
-  [TransportErrorCodes.PEER_UNAVAILABLE]: ErrorCodes.QUERY_NO_ACTIVE_REPLICA,
-  [TransportErrorCodes.TIMEOUT]: ErrorCodes.QUERY_NODE_TIMEOUT,
-  [TransportErrorCodes.MESSAGE_TOO_LARGE]: ErrorCodes.QUERY_ROUTING_FAILED,
-  [TransportErrorCodes.DECODE_FAILED]: ErrorCodes.QUERY_ROUTING_FAILED
-};
-function readFailure(error, targetNodeId, indexName) {
-  if (error instanceof NarsilError) {
-    return error;
-  }
-  if (error instanceof TransportError) {
-    return new NarsilError(
-      READ_FAILURE_BY_TRANSPORT_CODE[error.code],
-      `Node '${targetNodeId}' did not answer a read request for index '${indexName}'`,
-      { indexName, targetNodeId, transportCode: error.code }
-    );
-  }
-  return error;
-}
 async function sendReadRequest(deps, targetNodeId, message, indexName, validate) {
-  const response = await sendToNode2(deps.config, targetNodeId, message).catch((error) => {
-    throw readFailure(error, targetNodeId, indexName);
+  const response = await sendToNode2(deps.config, targetNodeId, message, {
+    message: `Node '${targetNodeId}' did not answer a read request for index '${indexName}'`,
+    details: { indexName }
   });
   const decoded = decode(response.payload);
   if (response.type.endsWith(".error") || response.type === "error" || decoded.error === true) {
@@ -9704,7 +10419,7 @@ async function gatherPartitionCounts(deps, indexName, allocation) {
     groups.map(async (group) => {
       if (group.nodeId === deps.nodeId) {
         const requested = new Set(group.partitionIds);
-        const partitions = deps.engine.getPartitionStats(indexName).filter((partition) => requested.has(partition.partitionId)).map((partition) => ({
+        const partitions = (await deps.engine.partitionStatsForRead(indexName)).filter((partition) => requested.has(partition.partitionId)).map((partition) => ({
           partitionId: partition.partitionId,
           documentCount: partition.documentCount,
           estimatedMemoryBytes: partition.estimatedMemoryBytes
@@ -9782,7 +10497,7 @@ async function statsCluster(deps, indexName) {
 async function partitionStatsCluster(deps, indexName) {
   const allocation = await routableAllocation(deps.config.coordinator, indexName);
   if (allocation === null) {
-    return deps.engine.getPartitionStats(indexName);
+    return deps.engine.partitionStatsForRead(indexName);
   }
   const { countsByPartition } = await gatherPartitionCounts(deps, indexName, allocation);
   return Array.from(countsByPartition.entries()).map(([partitionId, entry]) => ({
@@ -9841,8 +10556,9 @@ async function listCluster(deps, indexName, params) {
   const startTime = now();
   const limit = clampListLimit(params.limit);
   const signature = sortSignatureOf(params.sort);
+  const binding = listBindingOf(params.filters);
   if (params.cursor !== void 0) {
-    requireMatchingCursor(decodePageCursor(params.cursor), params.cursor, signature, false);
+    requireMatchingCursor(decodePageCursor(params.cursor), params.cursor, signature, false, binding);
   }
   const normalizedSort = normalizeSort(params.sort);
   const sortFieldNames = normalizedSort.length === 0 ? null : normalizedSort.map((entry) => entry.field);
@@ -9905,7 +10621,8 @@ async function listCluster(deps, indexName, params) {
       anchor: last.entry.docId,
       score: null,
       sortKey: sortFieldNames === null ? null : [...last.key ?? []],
-      sortSignature: signature
+      sortSignature: signature,
+      binding
     });
   }
   const documents = page.map((item) => ({
@@ -10032,6 +10749,7 @@ async function queryCluster(deps, indexName, params) {
     resolveNodeTargets: deps.resolveNodeTargets
   };
   const distributed = await distributedQuery(indexName, wireParams, queryDeps, routingConfig(deps.config.query));
+  const projection = resolveProjection(params.document);
   const documents = await fetchDistributedDocuments(
     deps.config,
     deps.nodeId,
@@ -10039,9 +10757,23 @@ async function queryCluster(deps, indexName, params) {
     indexName,
     distributed,
     allocation,
-    resolveProjection(params.document)
+    projection
   );
-  return distributedResultToLocal(distributed, documents);
+  const scored = await dropUnstoredPinnedEntries(
+    deps,
+    indexName,
+    params,
+    distributed,
+    allocation,
+    projection,
+    documents
+  );
+  const result = distributedResultToLocal({ ...distributed, scored }, documents);
+  const groups = await assembleDistributedGroups(deps, indexName, params, distributed, allocation, projection);
+  if (groups !== void 0) {
+    result.groups = groups;
+  }
+  return result;
 }
 
 // src/distribution/cluster-node/clear.ts
@@ -10053,391 +10785,234 @@ async function clearCluster(readDeps, writeDeps, indexName) {
   }
   for (; ; ) {
     const page = await listCluster(readDeps, indexName, { limit: CLEAR_PAGE_SIZE, document: false });
-    if (page.documents.length === 0) {
-      return;
-    }
-    const result = await routeRemoveBatch(
-      indexName,
-      page.documents.map((listed) => listed.id),
-      writeDeps
-    );
-    if (result.succeeded.length === 0) {
-      const firstFailure = result.failed[0];
-      throw new NarsilError(
-        ErrorCodes.QUERY_ROUTING_FAILED,
-        `Clearing index '${indexName}' stalled: no document in the current page could be removed`,
-        {
-          indexName,
-          remaining: page.total,
-          firstFailureDocId: firstFailure?.docId,
-          firstFailureCode: firstFailure?.error.code,
-          firstFailureMessage: firstFailure?.error.message
-        }
-      );
-    }
-  }
-}
-
-// src/distribution/cluster-node/node-operations.ts
-function createClusterNodeOperations(deps) {
-  const { trackOp, readDeps, writeDeps, engine, coordinator } = deps;
-  return {
-    async createIndex(name, indexConfig, options) {
-      return trackOp(name, () => routeCreateIndex(name, indexConfig, options, coordinator, engine));
-    },
-    async insert(indexName, document, docId, options) {
-      return trackOp(indexName, () => routeInsert(indexName, document, docId, writeDeps, options));
-    },
-    async insertBatch(indexName, documents, options) {
-      return trackOp(indexName, () => routeInsertBatch(indexName, documents, writeDeps, options));
-    },
-    async remove(indexName, docId) {
-      return trackOp(indexName, () => routeRemove(indexName, docId, writeDeps));
-    },
-    async removeBatch(indexName, docIds) {
-      return trackOp(indexName, () => routeRemoveBatch(indexName, docIds, writeDeps));
-    },
-    async update(indexName, docId, document) {
-      return trackOp(indexName, () => routeUpdate(indexName, docId, document, writeDeps));
-    },
-    async updateBatch(indexName, updates) {
-      return trackOp(indexName, () => routeUpdateBatch(indexName, updates, writeDeps));
-    },
-    async dropIndex(name) {
-      return trackOp(null, async () => {
-        await routeDropIndex(name, coordinator, engine);
-        deps.forgetIndex(name);
-      });
-    },
-    async clear(indexName) {
-      return trackOp(indexName, () => clearCluster(readDeps, writeDeps, indexName));
-    },
-    async countDocuments(indexName) {
-      return trackOp(indexName, () => countCluster(readDeps, indexName));
-    },
-    async listDocuments(indexName, params) {
-      return trackOp(indexName, () => listCluster(readDeps, indexName, params ?? {}));
-    },
-    async suggest(indexName, params) {
-      return trackOp(indexName, () => suggestCluster(readDeps, indexName, params));
-    },
-    async preflight(indexName, params) {
-      return trackOp(indexName, () => preflightCluster(readDeps, indexName, params));
-    },
-    async getStats(indexName) {
-      return trackOp(indexName, () => statsCluster(readDeps, indexName));
-    },
-    async getPartitionStats(indexName) {
-      return trackOp(indexName, () => partitionStatsCluster(readDeps, indexName));
-    },
-    async checkpoint(indexName) {
-      return trackOp(indexName, () => engine.checkpoint(indexName));
-    },
-    async getMemoryStats() {
-      return trackOp(null, () => engine.getMemoryStats());
-    },
-    on(event, handler) {
-      engine.on(event, handler);
-    },
-    off(event, handler) {
-      engine.off(event, handler);
-    },
-    async query(indexName, params) {
-      return trackOp(indexName, () => queryCluster(readDeps, indexName, params));
-    },
-    async get(indexName, docId) {
-      return trackOp(indexName, async () => (await readClusterDocuments(readDeps, indexName, [docId])).get(docId));
-    },
-    async getMultiple(indexName, docIds) {
-      return trackOp(indexName, () => readClusterDocuments(readDeps, indexName, docIds));
-    },
-    async has(indexName, docId) {
-      return trackOp(indexName, async () => (await readClusterDocuments(readDeps, indexName, [docId])).has(docId));
-    }
-  };
-}
-
-// src/distribution/cluster-node/primary-partition.ts
-async function preparePrimaryPartition(indexName, partitionId, deps) {
-  const schema = await deps.coordinator.getSchema(indexName);
-  if (schema === null) {
-    return false;
-  }
-  const allocation = await deps.coordinator.getAllocation(indexName);
-  if (allocation === null || allocation.assignments.size === 0) {
-    return false;
-  }
-  const existing = deps.engine.listIndexes().find((index) => index.name === indexName);
-  if (existing === void 0) {
-    try {
-      await deps.engine.createIndex(indexName, {
-        schema,
-        partitions: { maxPartitions: allocation.assignments.size }
-      });
-    } catch (error) {
-      if (!(error instanceof NarsilError) || error.code !== ErrorCodes.INDEX_ALREADY_EXISTS) {
-        deps.onError(error);
-        return false;
-      }
-    }
-  } else {
-    const schemaError = validateRestoredSchema(deps.engine, indexName, deps.nodeId, schema);
-    if (schemaError !== null) {
-      deps.onError(schemaError);
-      return false;
-    }
-  }
-  resumeNumberingAboveOwnCopy(indexName, partitionId, allocation.assignments.get(partitionId), deps);
-  return true;
-}
-function resumeNumberingAboveOwnCopy(indexName, partitionId, assignment, deps) {
-  if (assignment === void 0) {
-    return;
-  }
-  if (deps.replicationLogPosition(indexName, partitionId) > 0) {
-    return;
-  }
-  const floor = Math.max(deps.engine.highestPersistedSeqNoOf(indexName, partitionId), assignment.commitPoint);
-  if (floor <= 0) {
-    return;
-  }
-  deps.seedReplicationLog(indexName, partitionId, floor + 1, assignment.primaryTerm);
-}
-
-// src/distribution/replication/types.ts
-var DEFAULT_LOG_RETENTION_BYTES = 268435456;
-
-// src/distribution/replication/log.ts
-var ENTRY_FIXED_OVERHEAD_BYTES2 = 40;
-function estimateEntrySize(entry) {
-  return ENTRY_FIXED_OVERHEAD_BYTES2 + entry.indexName.length + entry.documentId.length + (entry.document?.byteLength ?? 0);
-}
-var computeChecksum = computeEntryChecksum;
-function createReplicationLog(partitionId, config) {
-  const retentionBytes = config?.logRetentionBytes ?? DEFAULT_LOG_RETENTION_BYTES;
-  let nextSeqNo = config?.startSeqNo ?? 1;
-  let localLogEnd = nextSeqNo - 1;
-  let localLogEndPrimaryTerm = config?.lastPrimaryTerm ?? 0;
-  let commitPoint = nextSeqNo - 1;
-  let entries = [];
-  let headIndex = 0;
-  let totalSizeBytes = 0;
-  function liveCount() {
-    return entries.length - headIndex;
-  }
-  function compact() {
-    if (headIndex > 0) {
-      entries = entries.slice(headIndex);
-      headIndex = 0;
-    }
-  }
-  function findIndexBySeqNo(seqNo) {
-    let low = headIndex;
-    let high = entries.length - 1;
-    while (low <= high) {
-      const mid = low + high >>> 1;
-      const midSeqNo = entries[mid].seqNo;
-      if (midSeqNo < seqNo) {
-        low = mid + 1;
-      } else if (midSeqNo > seqNo) {
-        high = mid - 1;
-      } else {
-        return mid;
-      }
-    }
-    return low;
-  }
-  function evictOldEntries() {
-    while (liveCount() > 0 && totalSizeBytes > retentionBytes) {
-      totalSizeBytes -= estimateEntrySize(entries[headIndex]);
-      entries[headIndex] = null;
-      headIndex += 1;
-    }
-    if (totalSizeBytes < 0) {
-      totalSizeBytes = 0;
-    }
-    if (headIndex >= 256 || headIndex > liveCount()) {
-      compact();
-    }
-  }
-  function assertEntryFitsRetention(entry) {
-    const entrySize = ENTRY_FIXED_OVERHEAD_BYTES2 + entry.indexName.length + entry.documentId.length + (entry.document?.byteLength ?? 0);
-    if (entrySize > retentionBytes) {
-      throw new NarsilError(
-        ErrorCodes.REPLICATION_LOG_FULL,
-        `Replication log entry of ${entrySize} bytes exceeds the log retention limit of ${retentionBytes} bytes and cannot be buffered`,
-        { partitionId, entrySize, retentionBytes, seqNo: entry.seqNo }
-      );
-    }
-  }
-  function storeEntry(entry) {
-    entries.push(entry);
-    if (entry.seqNo >= localLogEnd) {
-      localLogEnd = entry.seqNo;
-      localLogEndPrimaryTerm = entry.primaryTerm;
-    }
-    totalSizeBytes += estimateEntrySize(entry);
-    evictOldEntries();
-    return { ...entry };
-  }
-  function readEntry(seqNo) {
-    if (liveCount() === 0) return void 0;
-    const idx = findIndexBySeqNo(seqNo);
-    if (idx < entries.length && entries[idx].seqNo === seqNo) {
-      return { ...entries[idx] };
-    }
-    return void 0;
-  }
-  function verifyEntryChecksum(entry) {
-    const expected = computeChecksum({
-      seqNo: entry.seqNo,
-      primaryTerm: entry.primaryTerm,
-      operation: entry.operation,
-      partitionId: entry.partitionId,
-      indexName: entry.indexName,
-      documentId: entry.documentId,
-      document: entry.document
-    });
-    return expected === entry.checksum;
-  }
-  return {
-    append(partial) {
-      assertEntryFitsRetention(partial);
-      const seqNo = nextSeqNo;
-      nextSeqNo += 1;
-      const entryWithoutChecksum = {
-        seqNo,
-        primaryTerm: partial.primaryTerm,
-        operation: partial.operation,
-        partitionId,
-        indexName: partial.indexName,
-        documentId: partial.documentId,
-        document: partial.document
-      };
-      const checksum = computeChecksum(entryWithoutChecksum);
-      const entry = { ...entryWithoutChecksum, checksum };
-      return storeEntry(entry);
-    },
-    appendCommitted(entry) {
-      if (!Number.isSafeInteger(entry.seqNo) || entry.seqNo < 1) {
-        throw new NarsilError(
-          ErrorCodes.REPLICATION_ENTRY_INVALID,
-          `Invalid replication sequence number ${entry.seqNo}`,
-          {
-            seqNo: entry.seqNo,
-            partitionId
-          }
-        );
-      }
-      if (entry.partitionId !== partitionId) {
-        throw new NarsilError(
-          ErrorCodes.REPLICATION_ENTRY_INVALID,
-          `Replication entry partition ${entry.partitionId} does not match log partition ${partitionId}`,
-          { entryPartitionId: entry.partitionId, logPartitionId: partitionId }
-        );
-      }
-      const existing = readEntry(entry.seqNo);
-      if (existing !== void 0) {
-        if (existing.checksum !== entry.checksum) {
-          throw new NarsilError(
-            ErrorCodes.REPLICATION_ENTRY_INVALID,
-            `Conflicting replication entry at sequence number ${entry.seqNo}`,
-            { seqNo: entry.seqNo, partitionId }
-          );
+    if (page.documents.length === 0) {
+      return;
+    }
+    const result = await routeRemoveBatch(
+      indexName,
+      page.documents.map((listed) => listed.id),
+      writeDeps
+    );
+    if (result.succeeded.length === 0) {
+      const firstFailure = result.failed[0];
+      throw new NarsilError(
+        ErrorCodes.QUERY_ROUTING_FAILED,
+        `Clearing index '${indexName}' stalled: no document in the current page could be removed`,
+        {
+          indexName,
+          remaining: page.total,
+          firstFailureDocId: firstFailure?.docId,
+          firstFailureCode: firstFailure?.error.code,
+          firstFailureMessage: firstFailure?.error.message
         }
-        return existing;
-      }
-      if (entry.seqNo !== nextSeqNo) {
-        throw new NarsilError(
-          ErrorCodes.REPLICATION_ENTRY_INVALID,
-          `Out-of-order replication entry ${entry.seqNo}; expected ${nextSeqNo}`,
-          { seqNo: entry.seqNo, expectedSeqNo: nextSeqNo, partitionId }
-        );
-      }
-      if (!verifyEntryChecksum(entry)) {
-        throw new NarsilError(
-          ErrorCodes.REPLICATION_ENTRY_CORRUPT,
-          `Invalid checksum for replication entry ${entry.seqNo}`,
-          { seqNo: entry.seqNo, partitionId }
-        );
-      }
-      assertEntryFitsRetention(entry);
-      nextSeqNo = entry.seqNo + 1;
-      return storeEntry({ ...entry });
+      );
+    }
+  }
+}
+
+// src/distribution/cluster-node/node-operations.ts
+function createClusterNodeOperations(deps) {
+  const { trackOp, readDeps, writeDeps, engine, coordinator } = deps;
+  return {
+    async createIndex(name, indexConfig, options) {
+      return trackOp(name, () => routeCreateIndex(name, indexConfig, options, coordinator, engine));
     },
-    getEntriesFrom(fromSeqNo) {
-      if (liveCount() === 0) return [];
-      const idx = findIndexBySeqNo(fromSeqNo);
-      if (idx >= entries.length) return [];
-      return entries.slice(idx).map((e) => ({ ...e }));
+    async insert(indexName, document, docId, options) {
+      return trackOp(indexName, () => routeInsert(indexName, document, docId, writeDeps, options));
     },
-    getEntry(seqNo) {
-      return readEntry(seqNo);
+    async insertBatch(indexName, documents, options) {
+      return trackOp(indexName, () => routeInsertBatch(indexName, documents, writeDeps, options));
     },
-    verifyChecksum(entry) {
-      return verifyEntryChecksum(entry);
+    async remove(indexName, docId) {
+      return trackOp(indexName, () => routeRemove(indexName, docId, writeDeps));
     },
-    get localLogEnd() {
-      return localLogEnd;
+    async removeBatch(indexName, docIds) {
+      return trackOp(indexName, () => routeRemoveBatch(indexName, docIds, writeDeps));
     },
-    get localLogEndPrimaryTerm() {
-      return localLogEndPrimaryTerm;
+    async update(indexName, docId, document) {
+      return trackOp(indexName, () => routeUpdate(indexName, docId, document, writeDeps));
     },
-    get commitPoint() {
-      return commitPoint;
+    async updateBatch(indexName, updates) {
+      return trackOp(indexName, () => routeUpdateBatch(indexName, updates, writeDeps));
     },
-    advanceCommitPoint(seqNo) {
-      const bounded = Math.min(seqNo, localLogEnd);
-      if (bounded > commitPoint) {
-        commitPoint = bounded;
-      }
+    async dropIndex(name) {
+      return deps.transitionIndex(name, async () => {
+        await routeDropIndex(name, coordinator, engine);
+        deps.forgetIndex(name);
+      });
     },
-    get oldestSeqNo() {
-      if (liveCount() === 0) return void 0;
-      return entries[headIndex].seqNo;
+    async clear(indexName) {
+      return trackOp(indexName, () => clearCluster(readDeps, writeDeps, indexName));
     },
-    get newestSeqNo() {
-      if (liveCount() === 0) return void 0;
-      return entries[entries.length - 1].seqNo;
+    async countDocuments(indexName) {
+      return trackOp(indexName, () => countCluster(readDeps, indexName));
     },
-    get entryCount() {
-      return liveCount();
+    async listDocuments(indexName, params) {
+      return trackOp(indexName, () => listCluster(readDeps, indexName, params ?? {}));
     },
-    get sizeBytes() {
-      return totalSizeBytes;
+    async suggest(indexName, params) {
+      return trackOp(indexName, () => suggestCluster(readDeps, indexName, params));
     },
-    clear() {
-      entries = [];
-      headIndex = 0;
-      totalSizeBytes = 0;
-      localLogEnd = nextSeqNo - 1;
-      commitPoint = nextSeqNo - 1;
+    async preflight(indexName, params) {
+      return trackOp(indexName, () => preflightCluster(readDeps, indexName, params));
+    },
+    async getStats(indexName) {
+      return trackOp(indexName, () => statsCluster(readDeps, indexName));
+    },
+    async getPartitionStats(indexName) {
+      return trackOp(indexName, () => partitionStatsCluster(readDeps, indexName));
+    },
+    async checkpoint(indexName) {
+      return trackOp(indexName, () => engine.checkpoint(indexName));
+    },
+    async getMemoryStats() {
+      return trackOp(null, () => engine.getMemoryStats());
+    },
+    on(event, handler) {
+      engine.on(event, handler);
+    },
+    off(event, handler) {
+      engine.off(event, handler);
+    },
+    async query(indexName, params) {
+      return trackOp(indexName, () => queryCluster(readDeps, indexName, params));
+    },
+    async get(indexName, docId) {
+      return trackOp(indexName, async () => (await readClusterDocuments(readDeps, indexName, [docId])).get(docId));
+    },
+    async getMultiple(indexName, docIds) {
+      return trackOp(indexName, () => readClusterDocuments(readDeps, indexName, docIds));
+    },
+    async has(indexName, docId) {
+      return trackOp(indexName, async () => (await readClusterDocuments(readDeps, indexName, [docId])).has(docId));
     }
   };
 }
 
-// src/distribution/cluster-node/replication-logs.ts
-function replicationLogKey(indexName, partitionId) {
-  return `${indexName}:${partitionId}`;
+// src/distribution/cluster-node/operation-tracker.ts
+function createClusterOperationTracker(config) {
+  let activeOperations = 0;
+  let drainResolve = null;
+  const activeByIndex = /* @__PURE__ */ new Map();
+  const indexDrainResolvers = /* @__PURE__ */ new Map();
+  const transitions = /* @__PURE__ */ new Map();
+  function releaseIndex(indexName) {
+    const remaining = (activeByIndex.get(indexName) ?? 1) - 1;
+    if (remaining > 0) {
+      activeByIndex.set(indexName, remaining);
+      return;
+    }
+    activeByIndex.delete(indexName);
+    for (const resolve of indexDrainResolvers.get(indexName) ?? []) resolve();
+    indexDrainResolvers.delete(indexName);
+  }
+  async function track(indexName, action) {
+    config.guard();
+    if (indexName !== null) config.assertIndex(indexName);
+    activeOperations += 1;
+    let indexCounted = false;
+    try {
+      if (indexName !== null) {
+        const transition2 = transitions.get(indexName);
+        if (transition2 !== void 0) await transition2;
+        config.assertIndex(indexName);
+        activeByIndex.set(indexName, (activeByIndex.get(indexName) ?? 0) + 1);
+        indexCounted = true;
+      }
+      return await action();
+    } finally {
+      if (indexName !== null && indexCounted) releaseIndex(indexName);
+      activeOperations -= 1;
+      if (activeOperations === 0 && drainResolve !== null) {
+        drainResolve();
+        drainResolve = null;
+      }
+    }
+  }
+  async function waitForIndexDrain(indexName) {
+    if ((activeByIndex.get(indexName) ?? 0) === 0) return;
+    await new Promise((resolve) => {
+      let resolvers = indexDrainResolvers.get(indexName);
+      if (resolvers === void 0) {
+        resolvers = /* @__PURE__ */ new Set();
+        indexDrainResolvers.set(indexName, resolvers);
+      }
+      resolvers.add(resolve);
+    });
+  }
+  function transition(indexName, action) {
+    return track(null, async () => {
+      const previous = transitions.get(indexName) ?? Promise.resolve();
+      const run = previous.catch(() => void 0).then(async () => {
+        await waitForIndexDrain(indexName);
+        return action();
+      });
+      const tail = run.then(
+        () => void 0,
+        () => void 0
+      );
+      transitions.set(indexName, tail);
+      try {
+        return await run;
+      } finally {
+        if (transitions.get(indexName) === tail) transitions.delete(indexName);
+      }
+    });
+  }
+  async function drain() {
+    if (activeOperations === 0) return;
+    await new Promise((resolve) => {
+      drainResolve = resolve;
+    });
+  }
+  return { track, transition, drain };
 }
-function getReplicationLog(replicationLogs, indexName, partitionId, replicationConfig) {
-  const key = replicationLogKey(indexName, partitionId);
-  let log = replicationLogs.get(key);
-  if (log === void 0) {
-    log = createReplicationLog(partitionId, { logRetentionBytes: replicationConfig?.logRetentionBytes });
-    replicationLogs.set(key, log);
+
+// src/distribution/cluster-node/primary-partition.ts
+async function preparePrimaryPartition(indexName, partitionId, deps) {
+  const schema = await deps.coordinator.getSchema(indexName);
+  if (schema === null) {
+    return false;
   }
-  return log;
+  const allocation = await deps.coordinator.getAllocation(indexName);
+  if (allocation === null || allocation.assignments.size === 0) {
+    return false;
+  }
+  const existing = deps.engine.listIndexes().find((index) => index.name === indexName);
+  if (existing === void 0) {
+    try {
+      await deps.engine.createIndex(indexName, {
+        schema,
+        partitions: { maxPartitions: allocation.assignments.size }
+      });
+    } catch (error) {
+      if (!(error instanceof NarsilError) || error.code !== ErrorCodes.INDEX_ALREADY_EXISTS) {
+        deps.onError(error);
+        return false;
+      }
+    }
+  } else {
+    const schemaError = validateRestoredSchema(deps.engine, indexName, deps.nodeId, schema);
+    if (schemaError !== null) {
+      deps.onError(schemaError);
+      return false;
+    }
+  }
+  resumeNumberingAboveOwnCopy(indexName, partitionId, allocation.assignments.get(partitionId), deps);
+  return true;
 }
-function seedReplicationLog(replicationLogs, indexName, partitionId, startSeqNo, lastPrimaryTerm = 0, replicationConfig) {
-  replicationLogs.set(
-    replicationLogKey(indexName, partitionId),
-    createReplicationLog(partitionId, {
-      startSeqNo,
-      lastPrimaryTerm,
-      logRetentionBytes: replicationConfig?.logRetentionBytes
-    })
-  );
+function resumeNumberingAboveOwnCopy(indexName, partitionId, assignment, deps) {
+  if (assignment === void 0) {
+    return;
+  }
+  if (deps.replicationLogPosition(indexName, partitionId) > 0) {
+    return;
+  }
+  const floor = Math.max(deps.engine.highestPersistedSeqNoOf(indexName, partitionId), assignment.commitPoint);
+  if (floor <= 0) {
+    return;
+  }
+  deps.seedReplicationLog(indexName, partitionId, floor + 1, assignment.primaryTerm);
 }
 var CONTROLLER_MESSAGE_TYPES = /* @__PURE__ */ new Set([
   ReplicationMessageTypes.INSYNC_ADD,
@@ -10608,10 +11183,25 @@ async function createClusterNode(config) {
   const nodeId = config.nodeId ?? generateId();
   const roles = config.roles ?? ["data", "coordinator", "controller"];
   const capacity = config.capacity ?? DEFAULT_CAPACITY;
-  const engine = await createClusterLocalEngine(config.engine);
   const bootstrapSyncState = createBootstrapSyncState();
   const snapshotSyncHandlerState = createSnapshotSyncHandlerState();
   const replicationLogs = /* @__PURE__ */ new Map();
+  let localEngine = null;
+  const engine = await createClusterLocalEngine(config.engine, {
+    async onIndexOpen(indexName) {
+      if (localEngine === null) return;
+      await seedReopenedPrimaryLogs({
+        indexName,
+        nodeId,
+        engine: localEngine,
+        coordinator: config.coordinator,
+        replicationLogs,
+        replicationConfig: config.replication
+      });
+    },
+    onIndexClose: (indexName) => deleteIndexReplicationLogs(replicationLogs, indexName)
+  });
+  localEngine = engine;
   function replicationLogKey2(indexName, partitionId) {
     return replicationLogKey(indexName, partitionId);
   }
@@ -10661,8 +11251,6 @@ async function createClusterNode(config) {
   let unregisterNotReadyHandler = null;
   let serving = false;
   let isShutdown = false;
-  let activeOps = 0;
-  let drainResolve = null;
   const bootstrapSyncDeps = {
     engine,
     coordinator: config.coordinator,
@@ -10735,22 +11323,14 @@ async function createClusterNode(config) {
       throw new NarsilError(ErrorCodes.NODE_NOT_JOINED, `Cluster node '${nodeId}' has been shut down`, { nodeId });
     }
   }
-  async function trackOp(indexName, fn) {
-    guardShutdown();
-    if (indexName !== null && orphanedIndexes.has(indexName)) {
-      throw orphanedIndexError(nodeId, indexName);
-    }
-    activeOps++;
-    try {
-      return await fn();
-    } finally {
-      activeOps--;
-      if (activeOps === 0 && drainResolve !== null) {
-        drainResolve();
-        drainResolve = null;
-      }
+  const operationTracker = createClusterOperationTracker({
+    guard: guardShutdown,
+    assertIndex(indexName) {
+      if (orphanedIndexes.has(indexName)) throw orphanedIndexError(nodeId, indexName);
     }
-  }
+  });
+  const trackOp = operationTracker.track;
+  const transitionIndex = operationTracker.transition;
   const readDeps = { config, nodeId, engine, resolveNodeTargets: resolveNodeTargets3 };
   const cluster = createClusterNamespace({
     nodeId,
@@ -10769,13 +11349,17 @@ async function createClusterNode(config) {
     get roles() {
       return roles;
     },
+    open: (indexName) => trackOp(indexName, () => engine.open(indexName)),
+    close: (indexName) => transitionIndex(indexName, () => engine.close(indexName)),
     ...createClusterNodeOperations({
       trackOp,
+      transitionIndex,
       readDeps,
       writeDeps,
       engine,
       coordinator: config.coordinator,
       forgetIndex: (indexName) => {
+        deleteIndexReplicationLogs(replicationLogs, indexName);
         if (engine.listIndexes().every((index) => index.name !== indexName)) {
           orphanedIndexes.delete(indexName);
         }
@@ -10825,11 +11409,7 @@ async function createClusterNode(config) {
       }
       isShutdown = true;
       serving = false;
-      if (activeOps > 0) {
-        await new Promise((resolve) => {
-          drainResolve = resolve;
-        });
-      }
+      await operationTracker.drain();
       if (unregisterHandler !== null) {
         unregisterHandler();
         unregisterHandler = null;
@@ -10852,14 +11432,20 @@ async function createClusterNode(config) {
     if (partitionId === null) {
       return fallback;
     }
-    const allocation = await config.coordinator.getAllocation(indexName);
-    const assignment = allocation?.assignments.get(partitionId);
-    const log = getReplicationLog2(indexName, partitionId);
-    return {
-      partitionId,
-      primaryTerm: assignment?.primaryTerm ?? fallback.primaryTerm,
-      lastSeqNo: log.newestSeqNo ?? 0
-    };
+    const localIndex = engine.listIndexes().find((index) => index.name === indexName);
+    const release = localIndex !== void 0 ? await engine.acquireIndexForReplication(indexName) : null;
+    try {
+      const allocation = await config.coordinator.getAllocation(indexName);
+      const assignment = allocation?.assignments.get(partitionId);
+      const log = getReplicationLog2(indexName, partitionId);
+      return {
+        partitionId,
+        primaryTerm: assignment?.primaryTerm ?? fallback.primaryTerm,
+        lastSeqNo: log.newestSeqNo ?? 0
+      };
+    } finally {
+      release?.();
+    }
   }
 }
 
@@ -10873,6 +11459,12 @@ function unsupported(operation) {
 }
 function clusterNodeEngine(node, options) {
   return {
+    open(indexName) {
+      return node.open(indexName);
+    },
+    close(indexName) {
+      return node.close(indexName);
+    },
     async createIndex(name, config) {
       return node.createIndex(name, config, options?.createIndex);
     },