@agenr/agenr-plugin 2.0.1 → 2.1.0

package/dist/{chunk-MEHOGUZE.js → chunk-6T5RXGIR.js}

@@ -1,3 +1,176 @@
+// src/core/recall/cross-encoder.ts
+var DEFAULT_CROSS_ENCODER_TOP_K = 10;
+var DEFAULT_CROSS_ENCODER_ALPHA = 0.6;
+async function applyCrossEncoderRerank(options) {
+  const candidates = [...options.candidates];
+  const k = resolveTopK(options.topK, candidates.length);
+  const alpha = resolveAlpha(options.alpha);
+  const startedAt = Date.now();
+  const passthrough = (degradedReason) => ({
+    applied: false,
+    k,
+    alpha,
+    latencyMs: elapsedMs(startedAt),
+    ...degradedReason ? { degradedReason } : {},
+    candidates: candidates.map((candidate) => ({
+      candidate: candidate.candidate,
+      score: candidate.score
+    })),
+    rescoredIds: []
+  });
+  if (options.disabled === true) {
+    return passthrough("disabled");
+  }
+  if (!options.port) {
+    return passthrough("not_configured");
+  }
+  if (candidates.length === 0) {
+    return passthrough("no_candidates");
+  }
+  const shortlist = candidates.slice(0, k);
+  const tail = candidates.slice(k);
+  const query = options.query.trim();
+  if (query.length === 0 || shortlist.length === 0) {
+    return passthrough("no_candidates");
+  }
+  let scores;
+  try {
+    scores = await options.port.rank(
+      query,
+      shortlist.map((candidate) => ({ id: candidate.id, text: candidate.text }))
+    );
+  } catch {
+    return passthrough("provider_error");
+  }
+  if (!Array.isArray(scores)) {
+    return passthrough("provider_error");
+  }
+  const scoreById = /* @__PURE__ */ new Map();
+  for (const entry of scores) {
+    if (!entry || typeof entry.id !== "string" || typeof entry.score !== "number" || !Number.isFinite(entry.score)) {
+      continue;
+    }
+    scoreById.set(entry.id, clampUnit(entry.score));
+  }
+  if (scoreById.size === 0) {
+    return passthrough("provider_error");
+  }
+  const rescoredIds = [];
+  const rescoredShortlist = shortlist.map((candidate) => {
+    const crossEncoderScore = scoreById.get(candidate.id);
+    if (crossEncoderScore === void 0) {
+      return {
+        candidate: candidate.candidate,
+        score: candidate.score,
+        id: candidate.id,
+        rescored: false
+      };
+    }
+    const nextScore = clampUnit(alpha * crossEncoderScore + (1 - alpha) * candidate.score);
+    if (nextScore !== candidate.score) {
+      rescoredIds.push(candidate.id);
+    }
+    return {
+      candidate: candidate.candidate,
+      score: nextScore,
+      crossEncoderScore,
+      id: candidate.id,
+      rescored: true
+    };
+  });
+  const reorderedShortlist = [...rescoredShortlist].sort((left, right) => {
+    if (left.score !== right.score) {
+      return right.score - left.score;
+    }
+    return shortlist.findIndex((candidate) => candidate.id === left.id) - shortlist.findIndex((candidate) => candidate.id === right.id);
+  });
+  const shortlistOutput = reorderedShortlist.map(({ candidate, score, crossEncoderScore }) => ({
+    candidate,
+    score,
+    ...typeof crossEncoderScore === "number" ? { crossEncoderScore } : {}
+  }));
+  const tailOutput = tail.map((candidate) => ({
+    candidate: candidate.candidate,
+    score: candidate.score
+  }));
+  return {
+    applied: true,
+    k,
+    alpha,
+    latencyMs: elapsedMs(startedAt),
+    candidates: [...shortlistOutput, ...tailOutput],
+    rescoredIds
+  };
+}
+function resolveTopK(value, total) {
+  if (total <= 0) {
+    return 0;
+  }
+  const raw = typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : DEFAULT_CROSS_ENCODER_TOP_K;
+  return Math.max(1, Math.min(total, raw));
+}
+function resolveAlpha(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_CROSS_ENCODER_ALPHA;
+  }
+  return clampUnit(value);
+}
+function clampUnit(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return value >= 1 ? 1 : value;
+}
+function elapsedMs(startedAt) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+// src/core/recall/fusion.ts
+var DEFAULT_RRF_RANK_CONSTANT = 60;
+var DEFAULT_RRF_SMALL_POOL_RANK_CONSTANT = 8;
+var SMALL_POOL_RRF_POOL_SIZE = 4;
+function rrfFuse(channels, rankConstant = DEFAULT_RRF_RANK_CONSTANT) {
+  const k = sanitizeRankConstant(rankConstant);
+  const nonEmptyChannels = channels.filter((channel) => channel.length > 0);
+  const scores = /* @__PURE__ */ new Map();
+  if (nonEmptyChannels.length === 0) {
+    return scores;
+  }
+  for (const channel of nonEmptyChannels) {
+    const seenInChannel = /* @__PURE__ */ new Set();
+    let compactedRank = 0;
+    for (const id of channel) {
+      if (id === void 0 || seenInChannel.has(id)) {
+        continue;
+      }
+      seenInChannel.add(id);
+      const contribution = 1 / (compactedRank + k);
+      scores.set(id, (scores.get(id) ?? 0) + contribution);
+      compactedRank += 1;
+    }
+  }
+  const normalizationDenominator = nonEmptyChannels.length * (1 / k);
+  for (const [id, score] of scores) {
+    scores.set(id, clampUnit2(score / normalizationDenominator));
+  }
+  return scores;
+}
+function rrfFuseVectorLexical(vectorRanks, lexicalRanks, rankConstant = DEFAULT_RRF_RANK_CONSTANT) {
+  return rrfFuse([vectorRanks, lexicalRanks], rankConstant);
+}
+function sanitizeRankConstant(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return DEFAULT_RRF_RANK_CONSTANT;
+  }
+  return value;
+}
+function clampUnit2(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return value >= 1 ? 1 : value;
+}
+
 // src/core/recall/lexical.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "the",
@@ -205,7 +378,7 @@ function recencyScore(createdAt, expiry, now = /* @__PURE__ */ new Date()) {
   }
   const halfLifeDays = expiry === "permanent" ? 365 : 30;
   const daysOld = Math.max(0, (nowDate.getTime() - createdDate.getTime()) / DAY_IN_MILLISECONDS);
-  return clampUnit(Math.pow(0.5, daysOld / halfLifeDays));
+  return clampUnit3(Math.pow(0.5, daysOld / halfLifeDays));
 }
 function gaussianRecency(createdAt, aroundDate, radiusDays) {
   const createdDate = asValidDate(createdAt);
@@ -218,27 +391,19 @@ function gaussianRecency(createdAt, aroundDate, radiusDays) {
     return createdDate.getTime() === anchorDate.getTime() ? 1 : 0;
   }
   const daysDelta = Math.abs(createdDate.getTime() - anchorDate.getTime()) / DAY_IN_MILLISECONDS;
-  return clampUnit(Math.exp(-0.5 * (daysDelta / normalizedRadius) ** 2));
+  return clampUnit3(Math.exp(-0.5 * (daysDelta / normalizedRadius) ** 2));
 }
 function importanceScore(importance) {
   const clampedImportance = clampRange(sanitizeNonNegative(importance), 1, 10);
-  return clampUnit(IMPORTANCE_FLOOR + (clampedImportance - 1) / 9 * (1 - IMPORTANCE_FLOOR));
-}
-function combinedRelevance(vectorSim, lexical) {
-  const normalizedVector = clampUnit(sanitizeNonNegative(vectorSim));
-  const normalizedLexical = clampUnit(sanitizeNonNegative(lexical));
-  if (normalizedVector > 0 && normalizedLexical > 0) {
-    return clampUnit(normalizedVector * 0.6 + normalizedLexical * 0.4);
-  }
-  return Math.max(normalizedVector, normalizedLexical);
+  return clampUnit3(IMPORTANCE_FLOOR + (clampedImportance - 1) / 9 * (1 - IMPORTANCE_FLOOR));
 }
 function scoreCandidate(params) {
-  const vector = clampUnit(sanitizeNonNegative(params.vectorSim));
-  const lexical = clampUnit(sanitizeNonNegative(params.lexical));
-  const recency = clampUnit(sanitizeNonNegative(params.recency));
-  const importance = clampUnit(sanitizeNonNegative(params.importance));
-  const relevance = combinedRelevance(vector, lexical);
-  const score = clampUnit(relevance * RELEVANCE_WEIGHT + recency * RECENCY_WEIGHT + importance * IMPORTANCE_WEIGHT);
+  const vector = clampUnit3(sanitizeNonNegative(params.vectorSim));
+  const lexical = clampUnit3(sanitizeNonNegative(params.lexical));
+  const recency = clampUnit3(sanitizeNonNegative(params.recency));
+  const importance = clampUnit3(sanitizeNonNegative(params.importance));
+  const relevance = clampUnit3(sanitizeNonNegative(params.relevance));
+  const score = clampUnit3(relevance * RELEVANCE_WEIGHT + recency * RECENCY_WEIGHT + importance * IMPORTANCE_WEIGHT);
   return {
     score,
     scores: {
@@ -268,17 +433,269 @@ function cosineSimilarity(left, right) {
   if (leftNorm <= 0 || rightNorm <= 0) {
     return 0;
   }
-  return clampUnit(dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm)));
+  return clampUnit3(dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm)));
 }
 var asValidDate = (value) => {
   const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
   return Number.isNaN(date.getTime()) ? null : date;
 };
-var clampUnit = (value) => clampRange(sanitizeNonNegative(value), 0, 1);
+var clampUnit3 = (value) => clampRange(sanitizeNonNegative(value), 0, 1);
 var clampRange = (value, min, max) => Math.min(max, Math.max(min, value));
 var sanitizeFinite = (value) => typeof value === "number" && Number.isFinite(value) ? value : 0;
 var sanitizeNonNegative = (value) => Math.max(0, sanitizeFinite(value));
 
+// src/core/recall/mmr.ts
+var DEFAULT_MMR_LAMBDA = 0.7;
+var DEFAULT_MMR_MIN_POOL_SIZE = 4;
+var NEAR_DUPLICATE_SIMILARITY = 0.95;
+function maximalMarginalRelevance(options) {
+  const lambda = clampUnit4(sanitizeNumber(options.lambda, DEFAULT_MMR_LAMBDA));
+  const inputIds = options.candidates.map((candidate) => candidate.id);
+  const limit = resolveLimit(options.limit, inputIds.length);
+  const minPoolSize = resolveMinPoolSize(options.minPoolSize);
+  const embeddedCandidates = options.candidates.filter((candidate) => hasUsableEmbedding(candidate.embedding));
+  const unembeddedIds = options.candidates.filter((candidate) => !hasUsableEmbedding(candidate.embedding)).map((candidate) => candidate.id);
+  const poolBelowGate = minPoolSize > 0 && options.candidates.length <= minPoolSize;
+  const canApplyMmr = !poolBelowGate && options.queryVector.length > 0 && embeddedCandidates.length >= 2;
+  if (!canApplyMmr) {
+    return {
+      applied: false,
+      lambda,
+      orderedIds: sliceOrDefault(inputIds, limit),
+      droppedDuplicateCount: 0,
+      reorderedIds: []
+    };
+  }
+  const relevanceById = /* @__PURE__ */ new Map();
+  for (const candidate of embeddedCandidates) {
+    const overriddenRelevance = sanitizeUnit(candidate.relevance);
+    const derivedRelevance = overriddenRelevance ?? cosineSimilarity(options.queryVector, candidate.embedding ?? []);
+    relevanceById.set(candidate.id, derivedRelevance);
+  }
+  const pairwiseMaxById = computePairwiseMaxSimilarity(embeddedCandidates);
+  const mmrScoreById = /* @__PURE__ */ new Map();
+  for (const candidate of embeddedCandidates) {
+    const relevance = relevanceById.get(candidate.id) ?? 0;
+    const maxPairwise = pairwiseMaxById.get(candidate.id) ?? 0;
+    mmrScoreById.set(candidate.id, lambda * relevance - (1 - lambda) * maxPairwise);
+  }
+  const rankedEmbeddedIds = [...embeddedCandidates].sort((left, right) => {
+    const leftScore = mmrScoreById.get(left.id) ?? 0;
+    const rightScore = mmrScoreById.get(right.id) ?? 0;
+    if (leftScore !== rightScore) {
+      return rightScore - leftScore;
+    }
+    return inputIds.indexOf(left.id) - inputIds.indexOf(right.id);
+  }).map((candidate) => candidate.id);
+  const orderedIds = sliceOrDefault([...rankedEmbeddedIds, ...unembeddedIds], limit);
+  const reorderedIds = inputIds.filter((id, index) => orderedIds[index] !== id);
+  const droppedDuplicateCount = countDroppedDuplicates(rankedEmbeddedIds, inputIds, pairwiseMaxById);
+  return {
+    applied: true,
+    lambda,
+    orderedIds,
+    droppedDuplicateCount,
+    reorderedIds
+  };
+}
+function computePairwiseMaxSimilarity(embeddedCandidates) {
+  const result = /* @__PURE__ */ new Map();
+  for (const candidate of embeddedCandidates) {
+    result.set(candidate.id, 0);
+  }
+  for (let outer = 0; outer < embeddedCandidates.length; outer += 1) {
+    for (let inner = outer + 1; inner < embeddedCandidates.length; inner += 1) {
+      const left = embeddedCandidates[outer];
+      const right = embeddedCandidates[inner];
+      const similarity = cosineSimilarity(left.embedding ?? [], right.embedding ?? []);
+      if (similarity > (result.get(left.id) ?? 0)) {
+        result.set(left.id, similarity);
+      }
+      if (similarity > (result.get(right.id) ?? 0)) {
+        result.set(right.id, similarity);
+      }
+    }
+  }
+  return result;
+}
+function countDroppedDuplicates(rankedEmbeddedIds, inputIds, pairwiseMaxById) {
+  const inputRankById = /* @__PURE__ */ new Map();
+  inputIds.forEach((id, index) => inputRankById.set(id, index));
+  let droppedDuplicates = 0;
+  rankedEmbeddedIds.forEach((id, mmrRank) => {
+    const inputRank = inputRankById.get(id);
+    if (inputRank === void 0 || mmrRank <= inputRank) {
+      return;
+    }
+    const maxSimilarity = pairwiseMaxById.get(id) ?? 0;
+    if (maxSimilarity >= NEAR_DUPLICATE_SIMILARITY) {
+      droppedDuplicates += 1;
+    }
+  });
+  return droppedDuplicates;
+}
+function sliceOrDefault(ids, limit) {
+  if (limit === null || limit >= ids.length) {
+    return [...ids];
+  }
+  return ids.slice(0, limit);
+}
+function resolveLimit(value, totalCandidates) {
+  if (value === void 0 || !Number.isFinite(value) || value <= 0) {
+    return null;
+  }
+  return Math.min(totalCandidates, Math.floor(value));
+}
+function hasUsableEmbedding(embedding) {
+  return Array.isArray(embedding) && embedding.length > 0;
+}
+function clampUnit4(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return value >= 1 ? 1 : value;
+}
+function resolveMinPoolSize(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_MMR_MIN_POOL_SIZE;
+  }
+  if (value < 0) {
+    return DEFAULT_MMR_MIN_POOL_SIZE;
+  }
+  return Math.floor(value);
+}
+function sanitizeNumber(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return value;
+}
+function sanitizeUnit(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return null;
+  }
+  return clampUnit4(value);
+}
+
+// src/core/recall/neighborhood.ts
+var DEFAULT_NEIGHBORHOOD_BUDGET = 24;
+var DEFAULT_STRONG_SEED_TOP_N = 3;
+var DEFAULT_STRONG_SEED_SCORE_GAP = 0.05;
+var DEFAULT_SEEDED_RERANK_WEIGHT = 0.03;
+function selectStrongSeeds(candidates, options = {}) {
+  if (candidates.length === 0) {
+    return [];
+  }
+  const topN = Math.max(1, sanitizeInteger(options.topN, DEFAULT_STRONG_SEED_TOP_N));
+  const floor = sanitizeUnit2(options.scoreGapFloor ?? DEFAULT_STRONG_SEED_SCORE_GAP);
+  const ordered = [...candidates].sort((left, right) => right.score - left.score);
+  const leader = ordered[0];
+  if (!leader || leader.score <= 0) {
+    return [];
+  }
+  const followerScore = ordered[topN]?.score ?? 0;
+  if (leader.score - followerScore < floor) {
+    return [];
+  }
+  const cutoff = Math.max(leader.score - floor, followerScore);
+  return ordered.slice(0, topN).filter((candidate) => candidate.score >= cutoff);
+}
+function seededRerank(candidates, seeds, sharesLineage, options = {}) {
+  const boostedIds = [];
+  if (candidates.length === 0 || seeds.length === 0) {
+    return { candidates: [...candidates], boostedIds };
+  }
+  const weight = sanitizeUnit2(options.weight ?? DEFAULT_SEEDED_RERANK_WEIGHT);
+  if (weight <= 0) {
+    return { candidates: [...candidates], boostedIds };
+  }
+  const seedIds = new Set(seeds.map((seed) => seed.id));
+  const reranked = candidates.map((candidate) => {
+    if (seedIds.has(candidate.id)) {
+      return candidate;
+    }
+    const match = seeds.find((seed) => seed.id !== candidate.id && sharesLineage(candidate, seed));
+    if (!match) {
+      return candidate;
+    }
+    boostedIds.push(candidate.id);
+    return {
+      ...candidate,
+      score: clampUnit5(candidate.score + weight)
+    };
+  });
+  return { candidates: reranked, boostedIds };
+}
+function sharesEntryLineage(candidate, seed) {
+  if (candidate.id === seed.id) {
+    return false;
+  }
+  if (candidate.claim_key && seed.claim_key && candidate.claim_key === seed.claim_key) {
+    return true;
+  }
+  if (candidate.superseded_by === seed.id || seed.superseded_by === candidate.id) {
+    return true;
+  }
+  return sharesTopicPrefix(candidate.subject, seed.subject);
+}
+function sharesEpisodeLineage(candidate, seed) {
+  if (candidate.id === seed.id) {
+    return false;
+  }
+  if (candidate.source === seed.source && candidate.sourceId !== void 0 && candidate.sourceId === seed.sourceId) {
+    return true;
+  }
+  if (candidate.transcriptHash && seed.transcriptHash && candidate.transcriptHash === seed.transcriptHash) {
+    return true;
+  }
+  return false;
+}
+function sharesProcedureLineage(candidate, seed) {
+  if (candidate.id === seed.id) {
+    return false;
+  }
+  return candidate.procedure_key === seed.procedure_key;
+}
+var TOPIC_PREFIX_SHARED_MIN = 2;
+var TOPIC_PREFIX_COVERAGE_MIN = 0.6;
+function sharesTopicPrefix(leftSubject, rightSubject) {
+  const leftTokens = tokenize(leftSubject);
+  const rightTokens = tokenize(rightSubject);
+  if (leftTokens.length === 0 || rightTokens.length === 0) {
+    return false;
+  }
+  const length = Math.min(leftTokens.length, rightTokens.length);
+  let shared = 0;
+  for (let index = 0; index < length; index += 1) {
+    if (leftTokens[index] !== rightTokens[index]) {
+      break;
+    }
+    shared += 1;
+  }
+  if (shared < TOPIC_PREFIX_SHARED_MIN) {
+    return false;
+  }
+  return shared / length >= TOPIC_PREFIX_COVERAGE_MIN;
+}
+function clampUnit5(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return value >= 1 ? 1 : value;
+}
+function sanitizeUnit2(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return Math.min(1, value);
+}
+function sanitizeInteger(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
 // src/core/claim-key.ts
 var UNKNOWN_SEGMENT = "unknown";
 var SELF_REFERENTIAL_ENTITIES = /* @__PURE__ */ new Set(["i", "me", "myself", "the_user", "user", "we", "our_team", "the_project", "this_project"]);
@@ -887,11 +1304,14 @@ function createNoopRecallTraceSink() {
 }
 
 // src/core/recall/search.ts
+var HISTORICAL_NEIGHBORHOOD_FAMILIES = ["supersession_chain", "claim_key_sibling", "topic_family"];
 var MIN_VECTOR_ONLY_EVIDENCE = 0.3;
 var HISTORICAL_STATE_FLAT_RECENCY = 0.5;
 var HISTORICAL_PREDECESSOR_BOOST = 0.08;
 var HISTORICAL_RETIRED_PREDECESSOR_BOOST = 0.06;
 var HISTORICAL_OLDER_STATE_BOOST = 0.08;
+var HISTORICAL_LINEAGE_GAP_MARGIN = 0.02;
+var HISTORICAL_LINEAGE_MAX_BONUS = 0.45;
 var HISTORICAL_TOPIC_SHARED_PREFIX_MIN = 2;
 var HISTORICAL_TOPIC_PREFIX_OF_CANDIDATE_MIN = 0.6;
 var CLAIM_KEY_TENTATIVE_CURRENT_PENALTY = 0.08;
@@ -899,6 +1319,28 @@ var CLAIM_KEY_REDUNDANT_TRUSTED_SLOT_PENALTY = 0.05;
 var CLAIM_KEY_REDUNDANT_TRUSTED_SLOT_MAX_PENALTY = 0.15;
 var QUERY_EMBEDDING_FAILURE_NOTICE = "Embeddings failed during recall, so Agenr fell back to lexical-only entry ranking.";
 var VECTOR_SEARCH_FAILURE_NOTICE = "Vector search failed during recall, so Agenr continued with lexical entry candidates only.";
+var ENTITY_ATTRIBUTE_IDENTITY_WRAPPERS = /* @__PURE__ */ new Set(["identity", "profile", "bio", "biography", "summary"]);
+var WEAK_QUERY_GROUNDING_TOKENS = /* @__PURE__ */ new Set([
+  "earlier",
+  "last",
+  "mention",
+  "mentioned",
+  "number",
+  "order",
+  "remember",
+  "remind",
+  "reminder",
+  "run",
+  "runs",
+  "thing",
+  "time",
+  "use",
+  "uses",
+  "using"
+]);
+var WEAKLY_GROUNDED_REMINDER_PATTERN = /\b(earlier|last time|mention(?:ed)?|remember|remind(?:er)?)\b/iu;
+var MIN_VECTOR_WITHOUT_GROUNDED_LEXICAL_SUPPORT = 0.45;
+var GROUNDING_SORT_MAX_SCORE_GAP = 0.03;
 async function recall(query, ports, options = {}) {
   const text = query.text.trim();
   const limit = normalizeLimit(query.limit);
@@ -970,39 +1412,47 @@ async function recall(query, ports, options = {}) {
     ];
     summary.degraded.lexicalOnly = summary.degraded.active && queryEmbedding.length === 0;
     const mergeStartedAt = Date.now();
-    const mergedCandidates = mergeCandidates(vectorCandidates, ftsCandidates);
-    await expandHistoricalCandidates(mergedCandidates, queryEmbedding, ports, {
-      activeEntryIds: Array.from(mergedCandidates.keys()),
-      rankingProfile: query.rankingProfile
+    const mergeOutcome = mergeCandidates(vectorCandidates, ftsCandidates);
+    const neighborhoodEnabled = options.rankingPolicy?.neighborhood !== "disabled";
+    const expansionRanks = neighborhoodEnabled ? await expandEntryNeighborhood(mergeOutcome.merged, queryEmbedding, ports, {
+      rankingProfile: query.rankingProfile,
+      neighborhoodTrace: summary.neighborhood
+    }) : [];
+    const relevanceByEntryId = resolveEntryRelevance({
+      vectorRanks: mergeOutcome.vectorRanks,
+      ftsRanks: mergeOutcome.ftsRanks,
+      expansionRanks,
+      policy: options.rankingPolicy,
+      trace: summary.rrf
     });
-    summary.candidateCounts.merged = mergedCandidates.size;
-    summary.timings.mergeCandidatesMs = elapsedMs(mergeStartedAt);
+    summary.candidateCounts.merged = mergeOutcome.merged.size;
+    summary.timings.mergeCandidatesMs = elapsedMs2(mergeStartedAt);
     const scoreStartedAt = Date.now();
-    const scored = applyClaimKeyResultShaping(
-      applyHistoricalLineageBoosts(
-        Array.from(mergedCandidates.values()).map(
-          (candidate) => scoreMergedCandidate(candidate, text, queryEmbedding, {
-            asOfDate,
-            aroundDate,
-            aroundRadius: query.aroundRadius,
-            rankingProfile: query.rankingProfile
-          })
-        ),
-        {
+    const historicallyBoosted = applyHistoricalLineageBoosts(
+      Array.from(mergeOutcome.merged.values()).map(
+        (candidate) => scoreMergedCandidate(candidate, text, queryEmbedding, relevanceByEntryId.get(candidate.entry.id) ?? 0, {
+          asOfDate,
           aroundDate,
+          aroundRadius: query.aroundRadius,
           rankingProfile: query.rankingProfile
-        },
-        summary.claimKey,
-        slotPolicyConfig
+        })
       ),
+      {
+        aroundDate,
+        rankingProfile: query.rankingProfile
+      },
       summary.claimKey,
       slotPolicyConfig
-    ).sort((left, right) => right.score - left.score);
-    summary.timings.scoreCandidatesMs = elapsedMs(scoreStartedAt);
+    );
+    const rerankedCandidates = neighborhoodEnabled ? applySeededEntryRerank(historicallyBoosted, summary.neighborhood) : historicallyBoosted;
+    const shaped = applyClaimKeyResultShaping(rerankedCandidates, summary.claimKey, slotPolicyConfig).sort((left, right) => right.score - left.score);
+    const diversified = applyMmrDiversification(shaped, queryEmbedding, options.rankingPolicy, summary.mmr);
+    const scored = await applyEntryCrossEncoderRerank(diversified, text, ports.crossEncoder, options.rankingPolicy, summary.crossEncoder);
+    summary.timings.scoreCandidatesMs = elapsedMs2(scoreStartedAt);
     const thresholdStartedAt = Date.now();
-    const thresholded = scored.filter((result) => hasSufficientReturnEvidence(result) && result.score >= threshold);
+    const thresholded = scored.filter((result) => hasSufficientReturnEvidence(result, query) && result.score >= threshold);
     summary.candidateCounts.thresholdQualified = thresholded.length;
-    summary.timings.thresholdMs = elapsedMs(thresholdStartedAt);
+    summary.timings.thresholdMs = elapsedMs2(thresholdStartedAt);
     if (thresholded.length === 0) {
       reportTrace(resolveNoResultReason(summary, scored.length === 0 ? "no_candidates" : "below_threshold"));
       return [];
@@ -1010,8 +1460,8 @@ async function recall(query, ports, options = {}) {
     const budgetStartedAt = Date.now();
     const budgeted = budget === null ? thresholded : applyBudget(thresholded, budget);
     summary.candidateCounts.budgetAccepted = budgeted.length;
-    summary.timings.budgetMs = budget === null ? 0 : elapsedMs(budgetStartedAt);
-    const ranked = budgeted.slice(0, limit);
+    summary.timings.budgetMs = budget === null ? 0 : elapsedMs2(budgetStartedAt);
+    const ranked = sortAcceptedCandidates(budgeted.slice(0, limit), text, query.rankingProfile);
     summary.candidateCounts.finalRanked = ranked.length;
     if (ranked.length === 0) {
       reportTrace("limit_zero");
@@ -1034,7 +1484,7 @@ async function recall(query, ports, options = {}) {
       ];
     });
     summary.candidateCounts.returned = results.length;
-    summary.timings.shapeResultsMs = elapsedMs(shapeStartedAt);
+    summary.timings.shapeResultsMs = elapsedMs2(shapeStartedAt);
     if (results.length === 0) {
       reportTrace(resolveNoResultReason(summary, "hydrate_missing"));
       return [];
@@ -1089,6 +1539,36 @@ function buildRecallTraceSummary(params) {
       trustPenalized: 0,
       redundancyPenalized: 0
     },
+    rrf: {
+      applied: false,
+      channelCount: 0,
+      rankConstant: DEFAULT_RRF_RANK_CONSTANT,
+      fusedCandidateCount: 0,
+      maxFusedScore: 0
+    },
+    neighborhood: {
+      expansionRequested: false,
+      expansionAvailable: false,
+      familiesRequested: [],
+      includeRetired: false,
+      seedIds: [],
+      expansionCandidates: 0,
+      strongSeedIds: [],
+      rerankBoostedIds: []
+    },
+    mmr: {
+      applied: false,
+      lambda: DEFAULT_MMR_LAMBDA,
+      droppedDuplicateCount: 0,
+      reorderedIds: []
+    },
+    crossEncoder: {
+      applied: false,
+      k: 0,
+      alpha: DEFAULT_CROSS_ENCODER_ALPHA,
+      latencyMs: 0,
+      rescoredIds: []
+    },
     timings: {
       mergeCandidatesMs: 0,
       scoreCandidatesMs: 0,
@@ -1131,12 +1611,13 @@ function resolveNoResultReason(summary, reason) {
   }
   return reason;
 }
-function scoreMergedCandidate(candidate, queryText, queryEmbedding, params) {
+function scoreMergedCandidate(candidate, queryText, queryEmbedding, rrfScore, params) {
   const vector = candidate.vectorSim ?? cosineSimilarity(candidate.entry.embedding ?? [], queryEmbedding);
   const lexical = computeLexicalScore(queryText, candidate.entry.subject, candidate.entry.content);
   const recency = resolveRecencyScore(candidate.entry, params);
   const importance = importanceScore(candidate.entry.importance);
   const scored = scoreCandidate({
+    relevance: rrfScore,
     vectorSim: vector,
     lexical,
     recency,
@@ -1147,28 +1628,139 @@ function scoreMergedCandidate(candidate, queryText, queryEmbedding, params) {
     score: scored.score,
     scores: {
       ...scored.scores,
+      // `rrf` mirrors `relevance` and makes the reciprocal rank fusion source
+      // explicit for trace summaries and cross-stage reasoning in later phases.
+      rrf: scored.scores.relevance,
       historicalLineage: 0,
+      neighborhoodBoost: 0,
       claimKeyTrustPenalty: 0,
       claimKeyRedundancyPenalty: 0
     }
   };
 }
-async function expandHistoricalCandidates(mergedCandidates, queryEmbedding, ports, params) {
-  if (params.rankingProfile !== "historical_state" || mergedCandidates.size === 0 || !ports.fetchPredecessors) {
-    return;
+function resolveEntryRelevance(params) {
+  const { vectorRanks, ftsRanks, expansionRanks, policy, trace } = params;
+  if (policy?.rrf === "disabled") {
+    const fallbackChannel = vectorRanks.length > 0 ? vectorRanks : ftsRanks;
+    const fallback = /* @__PURE__ */ new Map();
+    fallbackChannel.forEach((id, index) => {
+      if (!fallback.has(id)) {
+        fallback.set(id, 1 / (index + 1));
+      }
+    });
+    trace.applied = false;
+    trace.channelCount = fallbackChannel.length > 0 ? 1 : 0;
+    trace.rankConstant = resolveRrfRankConstant(policy, fallback.size);
+    trace.fusedCandidateCount = fallback.size;
+    trace.maxFusedScore = fallback.size > 0 ? Math.max(...fallback.values()) : 0;
+    return fallback;
+  }
+  const channels = [Array.from(vectorRanks), Array.from(ftsRanks), Array.from(expansionRanks)];
+  const activeChannels = channels.filter((channel) => channel.length > 0);
+  const uniqueFusedIds = /* @__PURE__ */ new Set();
+  for (const channel of channels) {
+    for (const id of channel) {
+      uniqueFusedIds.add(id);
+    }
   }
-  const predecessors = await ports.fetchPredecessors({
-    activeEntryIds: params.activeEntryIds
+  const rankConstant = resolveRrfRankConstant(policy, uniqueFusedIds.size);
+  trace.rankConstant = rankConstant;
+  const fused = rrfFuse(channels, rankConstant);
+  trace.applied = fused.size > 0;
+  trace.channelCount = activeChannels.length;
+  trace.fusedCandidateCount = fused.size;
+  trace.maxFusedScore = fused.size > 0 ? Math.max(...fused.values()) : 0;
+  return fused;
+}
+function resolveRrfRankConstant(policy, fusedPoolSize) {
+  const rawGeneral = policy?.rrfRankConstant;
+  const hasExplicitGeneral = typeof rawGeneral === "number" && Number.isFinite(rawGeneral) && rawGeneral > 0;
+  const generalConstant = hasExplicitGeneral ? rawGeneral : DEFAULT_RRF_RANK_CONSTANT;
+  const isSmallPool = Number.isFinite(fusedPoolSize) && fusedPoolSize > 0 && fusedPoolSize <= SMALL_POOL_RRF_POOL_SIZE;
+  if (!isSmallPool) {
+    return generalConstant;
+  }
+  const rawSmall = policy?.rrfSmallPoolRankConstant;
+  if (typeof rawSmall === "number" && Number.isFinite(rawSmall) && rawSmall > 0) {
+    return rawSmall;
+  }
+  if (hasExplicitGeneral) {
+    return generalConstant;
+  }
+  return DEFAULT_RRF_SMALL_POOL_RANK_CONSTANT;
+}
+async function expandEntryNeighborhood(mergedCandidates, queryEmbedding, ports, params) {
+  const trace = params.neighborhoodTrace;
+  trace.expansionAvailable = Boolean(ports.expandNeighborhood);
+  if (mergedCandidates.size === 0 || !ports.expandNeighborhood || params.rankingProfile !== "historical_state") {
+    return [];
+  }
+  const families = HISTORICAL_NEIGHBORHOOD_FAMILIES;
+  const includeRetired = true;
+  const seedIds = Array.from(mergedCandidates.keys());
+  trace.expansionRequested = true;
+  trace.familiesRequested = [...families];
+  trace.includeRetired = includeRetired;
+  trace.seedIds = seedIds;
+  const expanded = await ports.expandNeighborhood({
+    seedIds,
+    budget: DEFAULT_NEIGHBORHOOD_BUDGET,
+    families,
+    includeRetired
   });
-  for (const entry of predecessors) {
-    if (mergedCandidates.has(entry.id)) {
-      continue;
-    }
-    mergedCandidates.set(entry.id, {
-      entry,
-      vectorSim: cosineSimilarity(entry.embedding ?? [], queryEmbedding)
+  const ranked = expanded.filter((entry) => !mergedCandidates.has(entry.id)).map((entry) => ({
+    entry,
+    vectorSim: cosineSimilarity(entry.embedding ?? [], queryEmbedding)
+  })).sort((left, right) => right.vectorSim - left.vectorSim || left.entry.id.localeCompare(right.entry.id));
+  for (const candidate of ranked) {
+    mergedCandidates.set(candidate.entry.id, {
+      entry: candidate.entry,
+      vectorSim: candidate.vectorSim
     });
   }
+  trace.expansionCandidates = ranked.length;
+  return ranked.map((candidate) => candidate.entry.id);
+}
+function applySeededEntryRerank(candidates, trace) {
+  if (candidates.length === 0) {
+    return candidates;
+  }
+  const seeds = selectStrongSeeds(
+    candidates.map((candidate) => ({ id: candidate.entry.id, score: candidate.score, entry: candidate.entry })),
+    {
+      topN: DEFAULT_STRONG_SEED_TOP_N,
+      scoreGapFloor: DEFAULT_STRONG_SEED_SCORE_GAP
+    }
+  );
+  if (seeds.length === 0) {
+    return candidates;
+  }
+  trace.strongSeedIds = seeds.map((seed) => seed.id);
+  const payloads = candidates.map((candidate) => ({
+    id: candidate.entry.id,
+    score: candidate.score,
+    entry: candidate.entry
+  }));
+  const reranked = seededRerank(payloads, seeds, (candidate, seed) => sharesEntryLineage(candidate.entry, seed.entry), {
+    weight: DEFAULT_SEEDED_RERANK_WEIGHT
+  });
+  trace.rerankBoostedIds = reranked.boostedIds;
+  const scoreById = new Map(reranked.candidates.map((candidate) => [candidate.id, candidate.score]));
+  return candidates.map((candidate) => {
+    const nextScore = scoreById.get(candidate.entry.id) ?? candidate.score;
+    const delta = nextScore - candidate.score;
+    if (delta <= 0) {
+      return candidate;
+    }
+    return {
+      ...candidate,
+      score: nextScore,
+      scores: {
+        ...candidate.scores,
+        neighborhoodBoost: candidate.scores.neighborhoodBoost + delta
+      }
+    };
+  });
 }
 function resolveRecencyScore(entry, params) {
   if (params.asOfDate) {
@@ -1214,8 +1806,9 @@ function applyHistoricalLineageBoosts(candidates, params, claimKeyTrace, slotPol
     return candidates;
   }
   const entries = candidates.map((candidate) => candidate.entry);
+  const scoresById = new Map(candidates.map((candidate) => [candidate.entry.id, candidate.score]));
   return candidates.map((candidate) => {
-    const decision = resolveHistoricalLineageBonus(candidate.entry, entries, params.aroundDate, slotPolicyConfig);
+    const decision = resolveHistoricalLineageBonus(candidate.entry, entries, scoresById, candidate.score, params.aroundDate, slotPolicyConfig);
     if (decision.tentativeLineageSuppressed) {
       claimKeyTrace.tentativeLineageSuppressed += 1;
     }
@@ -1234,10 +1827,12 @@ function applyHistoricalLineageBoosts(candidates, params, claimKeyTrace, slotPol
     };
   });
 }
-function resolveHistoricalLineageBonus(entry, entries, aroundDate, slotPolicyConfig) {
-  if (entries.some((peer) => peer.id !== entry.id && entry.superseded_by === peer.id)) {
+function resolveHistoricalLineageBonus(entry, entries, scoresById, candidateScore, aroundDate, slotPolicyConfig) {
+  const directSuccessor = entries.find((peer) => peer.id !== entry.id && entry.superseded_by === peer.id);
+  if (directSuccessor) {
+    const successorScore = scoresById.get(directSuccessor.id) ?? 0;
     return {
-      bonus: HISTORICAL_PREDECESSOR_BOOST,
+      bonus: shapeHistoricalLineageBonus(HISTORICAL_PREDECESSOR_BOOST, candidateScore, successorScore),
       tentativeLineageSuppressed: false
     };
   }
@@ -1248,6 +1843,8 @@ function resolveHistoricalLineageBonus(entry, entries, aroundDate, slotPolicyCon
     };
   }
   let tentativeLineageSuppressed = false;
+  let bestPeerScore = 0;
+  let peerMatched = false;
   for (const peer of entries) {
     if (peer.id === entry.id || !isPotentialCurrentPeer(peer) || createdAtMs(entry.created_at) >= createdAtMs(peer.created_at)) {
       continue;
@@ -1260,16 +1857,29 @@ function resolveHistoricalLineageBonus(entry, entries, aroundDate, slotPolicyCon
     if (relation === null) {
       continue;
     }
+    peerMatched = true;
+    const peerScore = scoresById.get(peer.id) ?? 0;
+    if (peerScore > bestPeerScore) {
+      bestPeerScore = peerScore;
+    }
+  }
+  if (!peerMatched) {
     return {
-      bonus: entry.retired ? HISTORICAL_RETIRED_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST,
+      bonus: 0,
       tentativeLineageSuppressed
     };
   }
+  const base = entry.retired ? HISTORICAL_RETIRED_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST;
   return {
-    bonus: 0,
+    bonus: shapeHistoricalLineageBonus(base, candidateScore, bestPeerScore),
     tentativeLineageSuppressed
   };
 }
+function shapeHistoricalLineageBonus(base, candidateScore, successorScore) {
+  const gap = successorScore - candidateScore;
+  const needed = gap > 0 ? gap + HISTORICAL_LINEAGE_GAP_MARGIN : 0;
+  return Math.min(HISTORICAL_LINEAGE_MAX_BONUS, Math.max(base, needed));
+}
 function isPotentialCurrentPeer(entry) {
   return !entry.retired && entry.superseded_by === void 0;
 }
@@ -1328,6 +1938,102 @@ function countSharedPrefixTokens(leftTokens, rightTokens) {
   }
   return sharedPrefixCount;
 }
+function applyMmrDiversification(candidates, queryEmbedding, policy, trace) {
+  if (candidates.length < 2 || policy?.mmr === "disabled") {
+    trace.applied = false;
+    trace.lambda = resolveMmrLambda(policy);
+    return candidates;
+  }
+  const reorder = maximalMarginalRelevance({
+    queryVector: queryEmbedding,
+    candidates: candidates.map((candidate) => ({
+      id: candidate.entry.id,
+      relevance: candidate.score,
+      ...candidate.entry.embedding ? { embedding: candidate.entry.embedding } : {}
+    })),
+    lambda: resolveMmrLambda(policy),
+    minPoolSize: resolveMmrMinPoolSize(policy)
+  });
+  trace.applied = reorder.applied;
+  trace.lambda = reorder.lambda;
+  trace.droppedDuplicateCount = reorder.droppedDuplicateCount;
+  trace.reorderedIds = reorder.reorderedIds;
+  if (!reorder.applied) {
+    return candidates;
+  }
+  const candidatesById = new Map(candidates.map((candidate) => [candidate.entry.id, candidate]));
+  return reorder.orderedIds.flatMap((id) => {
+    const candidate = candidatesById.get(id);
+    return candidate ? [candidate] : [];
+  });
+}
+async function applyEntryCrossEncoderRerank(candidates, query, crossEncoder, policy, trace) {
+  const result = await applyCrossEncoderRerank({
+    query,
+    candidates: candidates.map((candidate) => ({
+      id: candidate.entry.id,
+      text: buildCrossEncoderPassageText(candidate.entry),
+      score: candidate.score,
+      candidate
+    })),
+    port: crossEncoder,
+    disabled: policy?.crossEncoder === "disabled",
+    topK: policy?.crossEncoderTopK ?? DEFAULT_CROSS_ENCODER_TOP_K,
+    alpha: policy?.crossEncoderAlpha ?? DEFAULT_CROSS_ENCODER_ALPHA
+  });
+  trace.applied = result.applied;
+  trace.k = result.k;
+  trace.alpha = result.alpha;
+  trace.latencyMs = result.latencyMs;
+  trace.rescoredIds = [...result.rescoredIds];
+  if (result.degradedReason) {
+    trace.degradedReason = result.degradedReason;
+  } else {
+    delete trace.degradedReason;
+  }
+  return result.candidates.map((entry) => {
+    const scoredCandidate = entry.candidate;
+    const nextScore = entry.score;
+    if (typeof entry.crossEncoderScore !== "number" && nextScore === scoredCandidate.score) {
+      return scoredCandidate;
+    }
+    return {
+      ...scoredCandidate,
+      score: nextScore,
+      scores: {
+        ...scoredCandidate.scores,
+        ...typeof entry.crossEncoderScore === "number" ? { crossEncoder: entry.crossEncoderScore } : {}
+      }
+    };
+  });
+}
+function buildCrossEncoderPassageText(entry) {
+  const subject = entry.subject.trim();
+  const content = entry.content.trim();
+  if (subject.length === 0) {
+    return content;
+  }
+  if (content.length === 0) {
+    return subject;
+  }
+  return `${subject}
+
+${content}`;
+}
+function resolveMmrLambda(policy) {
+  const rawLambda = policy?.mmrLambda;
+  if (typeof rawLambda !== "number" || !Number.isFinite(rawLambda)) {
+    return DEFAULT_MMR_LAMBDA;
+  }
+  return Math.max(0, Math.min(1, rawLambda));
+}
+function resolveMmrMinPoolSize(policy) {
+  const raw = policy?.mmrMinPoolSize;
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+    return DEFAULT_MMR_MIN_POOL_SIZE;
+  }
+  return Math.floor(raw);
+}
 function applyClaimKeyResultShaping(candidates, claimKeyTrace, slotPolicyConfig) {
   if (candidates.length === 0) {
     return candidates;
@@ -1399,21 +2105,85 @@ function resolveTrustedSlotRedundancyPenalty(entryId, trustedSlotRankById) {
 function clampRecallScore(value) {
   return Math.max(0, Math.min(1, value));
 }
-function hasSufficientReturnEvidence(candidate) {
+function hasSufficientReturnEvidence(candidate, query) {
+  if (query.rankingProfile === "entity_attribute") {
+    return hasEntityAttributeEvidence(candidate.entry, query.queryShape);
+  }
+  const groundedLexicalSupport = hasGroundedLexicalSupport(candidate.entry, query.text);
   if (candidate.scores.lexical > 0) {
-    return true;
+    if (groundedLexicalSupport) {
+      return true;
+    }
+    return candidate.scores.vector >= MIN_VECTOR_WITHOUT_GROUNDED_LEXICAL_SUPPORT;
+  }
+  if (isWeaklyGroundedReminderQuery(query.text) && !groundedLexicalSupport) {
+    return false;
   }
   return candidate.scores.vector >= MIN_VECTOR_ONLY_EVIDENCE;
 }
+function hasGroundedLexicalSupport(entry, queryText) {
+  const groundingTokens = getGroundingTokens(queryText);
+  if (groundingTokens.length === 0) {
+    return false;
+  }
+  const candidateTokens = new Set(tokenize(`${entry.subject} ${entry.content}`).map(canonicalizeRecallToken));
+  return groundingTokens.some((token) => candidateTokens.has(token));
+}
+function isWeaklyGroundedReminderQuery(queryText) {
+  return WEAKLY_GROUNDED_REMINDER_PATTERN.test(queryText);
+}
+function hasEntityAttributeEvidence(entry, queryShape) {
+  if (queryShape?.kind !== "entity_attribute") {
+    return false;
+  }
+  const normalizedSubject = normalizeEntityAttributeText(entry.subject);
+  const normalizedContent = normalizeEntityAttributeText(entry.content);
+  const combinedTokens = new Set(tokenize(`${entry.subject} ${entry.content}`));
+  const entityTokenMatches = countTokenMatches(queryShape.entityTokens, combinedTokens);
+  const attributeTokenMatches = countTokenMatches(queryShape.attributeTokens, combinedTokens);
+  if (queryShape.attributeKind === "identity") {
+    if (normalizedSubject === queryShape.normalizedEntity || isIdentityWrapperSubject(normalizedSubject, queryShape.normalizedEntity)) {
+      return true;
+    }
+  }
+  if ((containsNormalizedPhrase(normalizedSubject, queryShape.normalizedEntity) || containsNormalizedPhrase(normalizedContent, queryShape.normalizedEntity)) && (queryShape.entityTokens.length >= 2 || attributeTokenMatches >= 1)) {
+    return true;
+  }
+  return entityTokenMatches >= 2 && attributeTokenMatches >= 1;
+}
+function countTokenMatches(expectedTokens, availableTokens) {
+  let matches = 0;
+  for (const token of expectedTokens) {
+    if (availableTokens.has(token)) {
+      matches += 1;
+    }
+  }
+  return matches;
+}
+function isIdentityWrapperSubject(normalizedSubject, normalizedEntity) {
+  return Array.from(ENTITY_ATTRIBUTE_IDENTITY_WRAPPERS).some((wrapper) => normalizedSubject === `${normalizedEntity} ${wrapper}`);
+}
+function containsNormalizedPhrase(normalizedText, normalizedPhrase) {
+  return normalizedPhrase.length > 0 && normalizedText.includes(normalizedPhrase);
+}
+function normalizeEntityAttributeText(text) {
+  return text.replace(/\s+/gu, " ").trim().normalize("NFKC").toLocaleLowerCase();
+}
 function mergeCandidates(vectorCandidates, ftsCandidates) {
   const merged = /* @__PURE__ */ new Map();
+  const vectorRanks = [];
+  const ftsRanks = [];
   for (const candidate of vectorCandidates) {
+    if (!merged.has(candidate.entry.id)) {
+      vectorRanks.push(candidate.entry.id);
+    }
     merged.set(candidate.entry.id, {
       entry: candidate.entry,
       vectorSim: candidate.vectorSim
     });
   }
   for (const candidate of ftsCandidates) {
+    ftsRanks.push(candidate.entry.id);
     const existing = merged.get(candidate.entry.id);
     if (existing) {
       existing.entry = existing.entry.embedding ? existing.entry : candidate.entry;
@@ -1423,7 +2193,11 @@ function mergeCandidates(vectorCandidates, ftsCandidates) {
       entry: candidate.entry
     });
   }
-  return merged;
+  return {
+    merged,
+    vectorRanks,
+    ftsRanks
+  };
 }
 function buildEntryFilters(types, tags, since, until) {
   const filters = {};
@@ -1457,6 +2231,134 @@ function applyBudget(results, budget) {
   }
   return accepted;
 }
+function sortAcceptedCandidates(candidates, queryText, rankingProfile) {
+  if (rankingProfile === "historical_state" || rankingProfile === "entity_attribute") {
+    return candidates.map((candidate, index) => ({ candidate, index })).sort((left, right) => right.candidate.score - left.candidate.score || left.index - right.index).map(({ candidate }) => candidate);
+  }
+  const groundingTokens = getGroundingTokens(queryText);
+  return candidates.map((candidate, index) => ({
+    candidate,
+    index,
+    grounding: computeGroundingSupport(candidate.entry, groundingTokens)
+  })).sort((left, right) => {
+    const scoreGap = Math.abs(left.candidate.score - right.candidate.score);
+    if (scoreGap > GROUNDING_SORT_MAX_SCORE_GAP || hasStructuralScoreShaping(left.candidate) || hasStructuralScoreShaping(right.candidate)) {
+      if (left.candidate.score !== right.candidate.score) {
+        return right.candidate.score - left.candidate.score;
+      }
+      return left.index - right.index;
+    }
+    if (left.grounding.phraseMatches !== right.grounding.phraseMatches) {
+      return right.grounding.phraseMatches - left.grounding.phraseMatches;
+    }
+    if (left.grounding.coverage !== right.grounding.coverage) {
+      return right.grounding.coverage - left.grounding.coverage;
+    }
+    if (left.candidate.scores.lexical !== right.candidate.scores.lexical) {
+      return right.candidate.scores.lexical - left.candidate.scores.lexical;
+    }
+    if (left.candidate.score !== right.candidate.score) {
+      return right.candidate.score - left.candidate.score;
+    }
+    if (left.candidate.scores.vector !== right.candidate.scores.vector) {
+      return right.candidate.scores.vector - left.candidate.scores.vector;
+    }
+    return left.index - right.index;
+  }).map(({ candidate }) => candidate);
+}
+function hasStructuralScoreShaping(candidate) {
+  return candidate.scores.historicalLineage > 0 || candidate.scores.neighborhoodBoost > 0 || candidate.scores.claimKeyTrustPenalty > 0 || candidate.scores.claimKeyRedundancyPenalty > 0;
+}
+function getGroundingTokens(queryText) {
+  const seen = /* @__PURE__ */ new Set();
+  const groundingTokens = [];
+  for (const token of tokenize(queryText)) {
+    if (WEAK_QUERY_GROUNDING_TOKENS.has(token)) {
+      continue;
+    }
+    const canonical = canonicalizeRecallToken(token);
+    if (seen.has(canonical)) {
+      continue;
+    }
+    seen.add(canonical);
+    groundingTokens.push(canonical);
+  }
+  return groundingTokens;
+}
+function canonicalizeRecallToken(token) {
+  const normalized = token.normalize("NFKC").toLocaleLowerCase();
+  if (normalized === "db" || normalized === "database" || normalized === "databases") {
+    return "db";
+  }
+  if (normalized === "resolve" || normalized === "resolves" || normalized === "resolved" || normalized === "resolving" || normalized === "resolution") {
+    return "resolve";
+  }
+  if (normalized === "branches") {
+    return "branch";
+  }
+  if (normalized === "prefix" || normalized === "prefixes") {
+    return "prefix";
+  }
+  if (normalized.endsWith("ies") && normalized.length > 4) {
+    return `${normalized.slice(0, -3)}y`;
+  }
+  if (normalized.endsWith("es") && normalized.length > 4) {
+    return normalized.slice(0, -2);
+  }
+  if (normalized.endsWith("s") && normalized.length > 3) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+function computeGroundingSupport(entry, groundingTokens) {
+  if (groundingTokens.length === 0) {
+    return {
+      phraseMatches: 0,
+      coverage: 0
+    };
+  }
+  const subjectTokens = tokenize(entry.subject).map(canonicalizeRecallToken);
+  const contentTokens = tokenize(entry.content).map(canonicalizeRecallToken);
+  const candidateTokens = /* @__PURE__ */ new Set([...subjectTokens, ...contentTokens]);
+  const matchedTokens = groundingTokens.filter((token) => candidateTokens.has(token));
+  return {
+    phraseMatches: countCanonicalPhraseMatches(groundingTokens, subjectTokens, contentTokens),
+    coverage: matchedTokens.length / groundingTokens.length
+  };
+}
+function countCanonicalPhraseMatches(queryTokens, subjectTokens, contentTokens) {
+  if (queryTokens.length < 2) {
+    return 0;
+  }
+  const matchedPhrases = /* @__PURE__ */ new Set();
+  for (let size = 2; size <= queryTokens.length; size += 1) {
+    for (let index = 0; index + size <= queryTokens.length; index += 1) {
+      const phraseTokens = queryTokens.slice(index, index + size);
+      if (hasCanonicalConsecutivePhrase(subjectTokens, phraseTokens) || hasCanonicalConsecutivePhrase(contentTokens, phraseTokens)) {
+        matchedPhrases.add(phraseTokens.join(" "));
+      }
+    }
+  }
+  return matchedPhrases.size;
+}
+function hasCanonicalConsecutivePhrase(haystack, needle) {
+  if (needle.length === 0 || haystack.length < needle.length) {
+    return false;
+  }
+  for (let index = 0; index + needle.length <= haystack.length; index += 1) {
+    let matches = true;
+    for (let offset = 0; offset < needle.length; offset += 1) {
+      if (haystack[index + offset] !== needle[offset]) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) {
+      return true;
+    }
+  }
+  return false;
+}
 function estimateTokens(entry) {
   return (entry.subject.length + entry.content.length) / 4;
 }
@@ -1487,7 +2389,7 @@ function normalizeAroundRadius(value) {
   }
   return value;
 }
-function elapsedMs(startedAt) {
+function elapsedMs2(startedAt) {
   return Math.max(0, Date.now() - startedAt);
 }
 
@@ -1495,7 +2397,6 @@ export {
   recencyScore,
   gaussianRecency,
   importanceScore,
-  combinedRelevance,
   scoreCandidate,
   cosineSimilarity,
   normalizeClaimKeySegment,
@@ -1513,5 +2414,23 @@ export {
   inferAroundDate,
   parseRelativeDate,
   resolveClaimSlotPolicy,
+  DEFAULT_CROSS_ENCODER_TOP_K,
+  DEFAULT_CROSS_ENCODER_ALPHA,
+  applyCrossEncoderRerank,
+  DEFAULT_RRF_RANK_CONSTANT,
+  rrfFuse,
+  rrfFuseVectorLexical,
+  DEFAULT_MMR_LAMBDA,
+  NEAR_DUPLICATE_SIMILARITY,
+  maximalMarginalRelevance,
+  DEFAULT_NEIGHBORHOOD_BUDGET,
+  DEFAULT_STRONG_SEED_TOP_N,
+  DEFAULT_STRONG_SEED_SCORE_GAP,
+  DEFAULT_SEEDED_RERANK_WEIGHT,
+  selectStrongSeeds,
+  seededRerank,
+  sharesEntryLineage,
+  sharesEpisodeLineage,
+  sharesProcedureLineage,
   recall
 };