@delali/narsil 0.2.3 → 0.2.4-next.43

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, dedupePinnedEntries, SUGGEST_OVERSAMPLE_FACTOR, SUGGEST_OVERSAMPLE_PADDING, createEntryMessage, computeEntryChecksum, createEntryBatchMessage, createInsyncConfirmMessage, validateAckPayload, createInsyncRemoveMessage, validateInsyncConfirmPayload, createInsyncAddMessage } from './chunk-KEDL6FFZ.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-O4Q5JYNK.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-YGQMKTKG.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-TLRUUMVE.mjs';
 import { encode, decode } from '@msgpack/msgpack';
 
 // src/distribution/cluster/controller/types.ts
@@ -5748,6 +5748,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 +6229,153 @@ function validateFilterExpression(value, fieldLabel, errorCode = SEARCH_INVALID_
   }
 }
 
+// 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 = Math.ceil(1e3 * 1.5) + 10;
+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 +6427,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]');
+  if (value.metric !== null) {
+    validateVectorMetricParam(value.metric);
   }
-}
-function validateGroupParams(value) {
-  if (!isRecord2(value)) {
-    throwInvalid(CONFIG_INVALID, 'Invalid SearchPayload: "params.group" must be an object');
-  }
-  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 +6573,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 +6841,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 +6984,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 +7037,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 +7186,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 +7265,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 +7298,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 +7317,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 +7327,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 +7351,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 +7374,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 +7384,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);
@@ -7503,6 +7744,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 +7832,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 +7912,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 +9166,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 +9219,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 +9270,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,90 +9421,17 @@ 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;
+// src/distribution/query/merge.ts
+function compareByScoreThenId(a, b) {
+  const aScore = a.score ?? Number.NEGATIVE_INFINITY;
+  const bScore = b.score ?? Number.NEGATIVE_INFINITY;
   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;
-  const bScore = b.score ?? Number.NEGATIVE_INFINITY;
-  if (aScore !== bScore) {
-    return bScore - aScore;
-  }
-  return compareCodePoints(a.docId, b.docId);
-}
-function mergeAndTruncateScoredEntries(arrays, limit) {
-  return mergeAndTruncate(arrays, limit, compareByScoreThenId);
+function mergeAndTruncateScoredEntries(arrays, limit) {
+  return mergeAndTruncate(arrays, limit, compareByScoreThenId);
 }
 function mergeAndTruncateSortedEntries(arrays, limit, directions) {
   const bySortValues = (a, b) => compareSortValues(a.sortValues ?? [], b.sortValues ?? [], directions) || compareCodePoints(a.docId, b.docId);
@@ -9396,6 +9582,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 +9839,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 +9862,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 +9876,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 +9908,7 @@ async function distributedQuery(indexName, params, deps, config, selector) {
   return executeSingleFanOut(
     indexName,
     params,
+    binding,
     limit,
     offset,
     facetShardSize,
@@ -9493,7 +9919,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 +9951,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 +9965,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 +10016,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);
-  }
-  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
-      });
-    }
+
+// 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 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 +10095,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) {
@@ -9841,8 +10257,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 +10322,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 +10450,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 +10458,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