fix(rag): restore bounded live retrieval reranking

src/lib/clinical-search.ts

@@ -1178,11 +1178,19 @@ const genericMedicationDoseQueryTokens = new Set([
  "sl",
 ]);
 
-/** Require dose evidence to carry the medication question's clinical subject. */
+/** Require medication evidence to carry the medication question's clinical subject. */
 export function medicationDoseQuerySubjectTokens(query: string) {
  return normalizedClinicalSearchTokens(query).filter((token) => !genericMedicationDoseQueryTokens.has(token));
 }
 
+/** Canonical medication subjects named by a monitoring query. */
+export function medicationMonitoringQuerySubjectTokens(query: string) {
+ return unique(
+ medicationTerms(normalizeAnalysisText(query)).flatMap((term) => normalizedClinicalSearchTokens(term)),
+ 12,
+ );
+}
+
 const medicationDoseAmountQueryPattern =
  /\b(?:dose|doses|dosage|dosages|dosing|amount|amounts|maximum|max|min|minimum|mg|mcg|micrograms?|milligrams?|ug)\b|[µμ]g|\bhow\s+much\b/i;
 const medicationDoseRouteQueryPattern =

src/lib/rag.ts

@@ -549,15 +549,21 @@ function recordRetrievalLayer(
  }
 }
 
+/** Whether the current result set carries bounded second-stage release scores. */
+function resultsHaveReleaseRankScore(results: SearchResult[]) {
+ return results.some((result) => result.score_explanation?.releaseRankScore !== undefined);
+}
+
 /**
- * Keep distinct results in the current ranked order while upgrading duplicate chunks to the
- * strongest released-hybrid copy.
+ * Keep the released result order on the live-eval-proven hybrid and bounded second-stage signals.
  *
  * App-layer rank scores remain available to answer evidence ranking and telemetry, but the
- * live corpus gate has not validated replacing the final distinct-result order with them.
+ * live corpus gate has not validated using them as the final retrieval order. Resolve duplicate
+ * chunks to their strongest released-hybrid copy before sorting the distinct results.
  */
-export function stabilizeReleasedSearchOrder(results: SearchResult[]) {
- const compareReleasedSearchStrength = (left: SearchResult, right: SearchResult) => {
+export function stabilizeReleasedSearchOrder(results: SearchResult[], preferSecondStageScore = false) {
+ const useSecondStageReleaseOrder = preferSecondStageScore && resultsHaveReleaseRankScore(results);
+ const compareReleasedHybridStrength = (left: SearchResult, right: SearchResult) => {
  const leftHybrid = left.hybrid_score ?? left.similarity ?? 0;
  const rightHybrid = right.hybrid_score ?? right.similarity ?? 0;
  if (rightHybrid !== leftHybrid) return rightHybrid - leftHybrid;
@@ -568,18 +574,30 @@ export function stabilizeReleasedSearchOrder(results: SearchResult[]) {
  return (right.relevance?.score ?? 0) - (left.relevance?.score ?? 0);
  return left.id.localeCompare(right.id);
  };
+ const compareReleasedSearchOrder = (left: SearchResult, right: SearchResult) => {
+ if (!useSecondStageReleaseOrder) return compareReleasedHybridStrength(left, right);
+ const leftReleaseScore = left.score_explanation?.releaseRankScore ?? left.hybrid_score ?? left.similarity ?? 0;
+ const rightReleaseScore = right.score_explanation?.releaseRankScore ?? right.hybrid_score ?? right.similarity ?? 0;
+ if (rightReleaseScore !== leftReleaseScore) return rightReleaseScore - leftReleaseScore;
+ const leftSimilarity = left.similarity ?? 0;
+ const rightSimilarity = right.similarity ?? 0;
+ if (rightSimilarity !== leftSimilarity) return rightSimilarity - leftSimilarity;
+ if (right.relevance?.score !== left.relevance?.score)
+ return (right.relevance?.score ?? 0) - (left.relevance?.score ?? 0);
+ return left.id.localeCompare(right.id);
+ };
  const strongestById = new Map<string, SearchResult>();
  for (const result of results) {
  const current = strongestById.get(result.id);
- if (!current || compareReleasedSearchStrength(result, current) < 0) strongestById.set(result.id, result);
- }
- const deduped: SearchResult[] = [];
- const seen = new Set<string>();
- for (const result of results) {
- if (seen.has(result.id)) continue;
- seen.add(result.id);
- deduped.push(strongestById.get(result.id) ?? result);
+ if (!current || compareReleasedHybridStrength(result, current) < 0) strongestById.set(result.id, result);
  }
+ const deduped = [...strongestById.values()]
+ .sort(compareReleasedSearchOrder)
+ .map((result, index) =>
+ result.score_explanation
+ ? { ...result, score_explanation: { ...result.score_explanation, finalRank: index + 1 } }
+ : result,
+ );
  results.length = 0;
  results.push(...deduped);
  return results;
@@ -601,7 +619,9 @@ function recordSearchScoreTelemetry(telemetry: SearchTelemetry, results: SearchR
  return;
  }
 
- stabilizeReleasedSearchOrder(results);
+ const useSecondStageReleaseOrder = resultsHaveReleaseRankScore(results);
+ telemetry.second_stage_rerank_used = useSecondStageReleaseOrder;
+ stabilizeReleasedSearchOrder(results, useSecondStageReleaseOrder);
  const coverageScores = results
  .map((result) => Math.max(0, result.hybrid_score ?? result.similarity ?? 0))
  .sort((left, right) => right - left);
@@ -719,6 +739,12 @@ export function applySecondStageRerankIfNeeded(args: {
  const secondStage = secondStageScore(result, args.queryClass, index);
  let rankScore = secondStage.rankScore;
  let confidenceAdjustment = secondStage.adjustment;
+ const releasedHybridScore = result.hybrid_score ?? result.similarity ?? 0;
+ let releaseRankScore = Math.max(
+ releasedHybridScore,
+ (result.score_explanation?.finalScore ?? result.hybrid_score ?? result.similarity ?? 0) +
+ secondStage.adjustment,
+ );
  const priorOccurrences = seenPerDocument.get(result.document_id) ?? 0;
  seenPerDocument.set(result.document_id, priorOccurrences + 1);
  if (rankingConfig.documentDiversityPenalty > 0 && priorOccurrences > 0) {
@@ -728,6 +754,16 @@ export function applySecondStageRerankIfNeeded(args: {
  );
  rankScore -= diversityPenalty;
  confidenceAdjustment -= diversityPenalty;
+ releaseRankScore -= diversityPenalty;
+ }
+ const selectionReasons = result.match_explanation?.reasons ?? [];
+ const clinicalSubjectRequired = selectionReasons.includes("retrieval_required_signal:clinical_subject");
+ const clinicalSubjectMatched = selectionReasons.includes("retrieval_signal:clinical_subject");
+ if (clinicalSubjectRequired && !clinicalSubjectMatched) {
+ // A wrong-medication chunk can carry attractive numeric dose/monitoring signals. Keep it
+ // available at its released hybrid strength, but do not let second-stage evidence boosts
+ // promote it above chunks that contain the medication subject requested by the query.
+ releaseRankScore = Math.min(releaseRankScore, releasedHybridScore);
  }
  const finalScore = Math.min(
  1,
@@ -745,6 +781,7 @@ export function applySecondStageRerankIfNeeded(args: {
  ? {
  ...result.score_explanation,
  rankScore: Number(rankScore.toFixed(4)),
+ releaseRankScore: Number(releaseRankScore.toFixed(4)),
  preClampFinalScore: Number(rankScore.toFixed(4)),
  finalScore: Number(finalScore.toFixed(4)),
  }

src/lib/retrieval-selection.ts

@@ -3,6 +3,7 @@ import {
  medicationDoseEvidenceQueryIntent,
  medicationDoseQueryContext,
  medicationDoseQuerySubjectTokens,
+ medicationMonitoringQuerySubjectTokens,
 } from "@/lib/clinical-search";
 import type {
  RagQueryClass,
@@ -236,6 +237,18 @@ function signalMatchesText(signal: string, text: string) {
  }
 }
 
+function medicationClinicalSubjectMatches(query: string, result: SearchResult, normalizedEvidenceText: string) {
+ const doseIntent = medicationDoseEvidenceQueryIntent(query);
+ if (doseIntent.asksAmount || doseIntent.asksRoute || doseIntent.asksFrequency) {
+ return medicationDoseQueryContext(query, result).matched;
+ }
+ const subjectTokens = medicationMonitoringQuerySubjectTokens(query);
+ if (!subjectTokens.length) return true;
+ const evidenceTokens = new Set(normalizedEvidenceText.split(" "));
+ const hitCount = subjectTokens.filter((token) => evidenceTokens.has(token)).length;
+ return hitCount >= Math.min(2, subjectTokens.length);
+}
+
 function matchedSignalsForResult(args: {
  query: string;
  intent: RetrievalIntent;
@@ -267,7 +280,7 @@ function matchedSignalsForResult(args: {
  if (args.intent.needsDoseRouteFrequency && hasRoute(text)) signals.push("route");
  if (
  args.intent.requiredTermSignals.includes("clinical_subject") &&
-medicationDoseQueryContext(args.query, args.result).matched
+medicationClinicalSubjectMatches(args.query, args.result, text)
  ) {
  signals.push("clinical_subject");
  }
@@ -358,6 +371,11 @@ export function buildRetrievalIntent(query: string, queryClass: RagQueryClass):
  const asksDoseRoute =
  medicationEvidenceIntent.asksAmount || medicationEvidenceIntent.asksRoute || medicationEvidenceIntent.asksFrequency;
  const asksDoseAmount = medicationEvidenceIntent.asksAmount;
+ const asksMedicationMonitoring =
+ queryClass === "medication_dose_risk" && /\b(?:monitor\w*|baseline|blood|level)\b/.test(normalizedQuery);
+ const clinicalSubjectTokens = asksMedicationMonitoring
+ ? medicationMonitoringQuerySubjectTokens(query)
+ : medicationDoseQuerySubjectTokens(query);
  const asksTable = /\b(?:table|chart|matrix|threshold|cutoff|cut off|range|criteria|row)\b/.test(normalizedQuery);
  const asksSourceImage =
  /\b(?:source|show|open|view|display|see)\b.*\b(?:image|figure|visual|table|chart|matrix)\b/.test(normalizedQuery) ||
@@ -400,9 +418,13 @@ export function buildRetrievalIntent(query: string, queryClass: RagQueryClass):
  if (asksDoseRoute) {
  if (asksDoseAmount) requiredTermSignals.push("dose_amount");
  if (medicationEvidenceIntent.asksRoute) requiredTermSignals.push("route");
- if (queryClass === "medication_dose_risk" && medicationDoseQuerySubjectTokens(query).length > 0) {
- requiredTermSignals.push("clinical_subject");
- }
+ }
+ if (
+ queryClass === "medication_dose_risk" &&
+ (asksDoseRoute || asksMedicationMonitoring) &&
+ clinicalSubjectTokens.length > 0
+ ) {
+ requiredTermSignals.push("clinical_subject");
  }
  if (asksFlowchart) {
  preferredDocumentSignals.push("flowchart", "pathway", "risk matrix");
@@ -490,9 +512,13 @@ function annotateResultWithSelection(
  result: SearchResult,
  candidate: RetrievalCandidate,
  originalScore: number,
+ intent: RetrievalIntent,
 ): SearchResult {
  const score = Number(Math.max(originalScore, candidate.score).toFixed(4));
  const selectionReasons = candidate.matchedSignals.map((signal) => `retrieval_signal:${signal}`);
+ if (intent.requiredTermSignals.includes("clinical_subject")) {
+ selectionReasons.push("retrieval_required_signal:clinical_subject");
+ }
  if (candidate.score > originalScore + 0.04) selectionReasons.push("retrieval_intent_rescue");
 
  return {
@@ -593,7 +619,7 @@ export function selectRetrievalEvidence(args: {
  .map((candidate) => {
  const result = byId.get(candidate.chunkId);
  if (!result) return null;
- return annotateResultWithSelection(result, candidate, originalScoreById.get(candidate.chunkId) ?? 0);
+ return annotateResultWithSelection(result, candidate, originalScoreById.get(candidate.chunkId) ?? 0, intent);
  })
  .filter((result): result is SearchResult => Boolean(result));
  const rescueApplied = selectedCandidates.some(

src/lib/types.ts

@@ -421,6 +421,8 @@ export type SearchScoreExplanation = {
  * this retains the magnitude of boosts and signed penalties after confidence saturates.
  */
  rankScore: number;
+ /** Live-eval-gated retrieval score used for the final released search order. */
+ releaseRankScore?: number;
  /** Existing public confidence signal, clamped to the inclusive 0-1 range. */
  finalScore: number;
  finalRank?: number;

tests/clinical-search.test.ts

@@ -9,6 +9,7 @@ import {
  hasDoseEvidenceSupport,
  hasNumericOrTableEvidence,
  hasStructuredThresholdEvidence,
+ medicationMonitoringQuerySubjectTokens,
  normalizedClinicalSearchTokens,
  rankClinicalResults,
 } from "../src/lib/clinical-search";
@@ -34,6 +35,13 @@ function result(overrides: Partial<SearchResult>): SearchResult {
 }
 
 describe("clinical search query normalization", () => {
+ it("keeps only the medication subject for monitoring questions", () => {
+ expect(medicationMonitoringQuerySubjectTokens("What monitoring is required for lithium therapy?")).toEqual([
+ "lithium",
+ ]);
+ expect(medicationMonitoringQuerySubjectTokens("What monitoring escalation is required?")).toEqual([]);
+ });
+
  it("classifies common RAG query shapes for routing and observability", () => {
  expect(classifyRagQuery("Find the NOCC document").queryClass).toBe("document_lookup");
  expect(classifyRagQuery("What should a patient safety plan include?").queryClass).toBe("document_lookup");

tests/rag-second-stage-ranking.test.ts

@@ -106,9 +106,47 @@ describe("second-stage rank score", () => {
 
  expect(ranked[0].id).toBe("high-rank");
  expect(ranked[0].score_explanation?.rankScore).toBe(1.49);
+ expect(ranked[0].score_explanation?.releaseRankScore).toBe(0.8);
+ expect(ranked[1].score_explanation?.releaseRankScore).toBeGreaterThan(0.8);
  expect(ranked[0].score_explanation?.preClampFinalScore).toBe(1.49);
  expect(ranked[0].score_explanation?.finalScore).toBe(0.69);
  expect(ranked.map((item) => item.score_explanation?.finalRank)).toEqual([1, 2]);
+ expect(stabilizeReleasedSearchOrder(ranked, true).map((item) => item.id)).toEqual(["runner-up", "high-rank"]);
+ });
+
+ it("caps wrong-subject monitoring evidence at its released hybrid score", () => {
+ const wrongSubject = explanation(1.4);
+ wrongSubject.finalScore = 1;
+ const rightSubject = explanation(0.79);
+ const ranked = applySecondStageRerankIfNeeded({
+ queryClass: "medication_dose_risk",
+ results: [
+ result({
+ id: "cardiac-dose",
+ document_id: "cardiac-doc",
+ content: "Cardiac monitoring includes a 5 mg treatment note.",
+ hybrid_score: 0.8,
+ score_explanation: wrongSubject,
+ match_explanation: { reasons: ["retrieval_required_signal:clinical_subject"] },
+ }),
+ result({
+ id: "lithium-monitoring",
+ document_id: "lithium-doc",
+ content: "Lithium monitoring requires serum levels.",
+ hybrid_score: 0.79,
+ score_explanation: rightSubject,
+ match_explanation: {
+ reasons: ["retrieval_required_signal:clinical_subject", "retrieval_signal:clinical_subject"],
+ },
+ }),
+ ],
+ telemetry: {} as SearchTelemetry,
+ topK: 2,
+ });
+
+ const stabilized = stabilizeReleasedSearchOrder(ranked, true);
+ expect(stabilized.map((item) => item.id)).toEqual(["lithium-monitoring", "cardiac-dose"]);
+ expect(stabilized[1].score_explanation?.releaseRankScore).toBe(0.8);
  });
 
  it("sorts by the computed second-stage score even when score explanations are absent", () => {
@@ -137,7 +175,7 @@ describe("second-stage rank score", () => {
  expect(ranked[1].score_explanation?.finalRank).toBe(2);
  });
 
- it("keeps distinct rank order while upgrading duplicate chunks to the strongest released-hybrid copy", () => {
+ it("sorts distinct chunks by the bounded release score and keeps the strongest duplicate copy", () => {
  const telemetry = {} as SearchTelemetry;
  const strongerHybridDuplicate = result({
  id: "stronger-hybrid",
@@ -180,10 +218,54 @@ describe("second-stage rank score", () => {
  });
  expect(secondStage.map((item) => item.id)).toEqual(["higher-rank-score", "stronger-hybrid", "stronger-hybrid"]);
 
- const stabilized = stabilizeReleasedSearchOrder(secondStage);
+ const stabilized = stabilizeReleasedSearchOrder(secondStage, true);
 
  expect(stabilized.map((item) => item.id)).toEqual(["higher-rank-score", "stronger-hybrid"]);
  expect(stabilized[1].hybrid_score).toBe(0.8);
  expect(stabilized[1].content).toBe(strongerHybridDuplicate.content);
+ expect(stabilized[0].score_explanation?.releaseRankScore).toBeGreaterThan(
+ stabilized[1].score_explanation?.releaseRankScore ?? 0,
+ );
+ expect(stabilized.map((item) => item.score_explanation?.finalRank)).toEqual([1, 2]);
+ });
+
+ it("ignores sticky second-stage preference when the final result set has no releaseRankScore", () => {
+ const clinicallyOrdered = [
+ result({
+ id: "lithium-monitoring",
+ hybrid_score: 0.79,
+ score_explanation: explanation(0.9),
+ }),
+ result({
+ id: "cardiac-dose",
+ hybrid_score: 0.8,
+ score_explanation: explanation(0.5),
+ }),
+ ];
+
+ expect(stabilizeReleasedSearchOrder([...clinicallyOrdered], true).map((item) => item.id)).toEqual(
+ stabilizeReleasedSearchOrder([...clinicallyOrdered], false).map((item) => item.id),
+ );
+ });
+
+ it("only applies bounded release ordering when the current result set carries releaseRankScore", () => {
+ const withReleaseScore = result({
+ id: "release-ranked",
+ hybrid_score: 0.79,
+ score_explanation: { ...explanation(0.79), releaseRankScore: 0.95 },
+ });
+ const withoutReleaseScore = result({
+ id: "hybrid-leading",
+ hybrid_score: 0.84,
+ score_explanation: explanation(0.84),
+ });
+
+ expect(stabilizeReleasedSearchOrder([withoutReleaseScore, withReleaseScore], true).map((item) => item.id)).toEqual([
+ "release-ranked",
+ "hybrid-leading",
+ ]);
+ expect(stabilizeReleasedSearchOrder([withoutReleaseScore, withReleaseScore], false).map((item) => item.id)).toEqual(
+ ["hybrid-leading", "release-ranked"],
+ );
  });
 });