@cue-dev/retrieval-core 0.1.3

package/test/mcp-search-quality.regression.test.ts

@@ -0,0 +1,1358 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { SearchContextOutputSchema } from "@cue-dev/contracts";
+import {
+  InMemoryQueryCache,
+  SqliteIndexRepository,
+  SqliteQueryCache,
+  type IndexRepository,
+  type RankedChunkCandidate
+} from "@cue-dev/data-plane";
+import { RetrievalCore } from "../src/index.js";
+
+function firstRank(results: Array<{ path: string }>, path: string): number {
+  const index = results.findIndex((row) => row.path === path);
+  return index >= 0 ? index + 1 : Number.POSITIVE_INFINITY;
+}
+
+function markdownCount(results: Array<{ path: string }>): number {
+  return results.filter((row) => row.path.toLowerCase().endsWith(".md")).length;
+}
+
+function buildLongCircuitBreakerFixture(): string {
+  const lines: string[] = [
+    "export interface RiskState {",
+    "  accountId: string;",
+    "  pnlSeries: number[];",
+    "  window: number[];",
+    "}",
+    "",
+    "const HARD_DRAWDOWN_LIMIT_BPS = 650;",
+    "const RISK_ACCUMULATOR_LIMIT = 25_000;",
+    "",
+    "function calculateDrawdownBps(values: number[], checksum: number): number {",
+    "  return values.length > 0 ? Math.max(...values) + (checksum % 7) : checksum % 7;",
+    "}",
+    "",
+    "function captureWindowChecksum(values: number[]): number {",
+    "  return values.reduce((sum, value) => sum + value, 0);",
+    "}",
+    "",
+    "function publishTripEvent(input: { reason: string; drawdownBps: number; riskAccumulator: number }) {",
+    "  return { eventId: `${input.reason}-${input.drawdownBps}-${input.riskAccumulator}` };",
+    "}",
+    "",
+    "function freezeOrderEntry(accountId: string, eventId: string): void {",
+    "  void accountId;",
+    "  void eventId;",
+    "}",
+    "",
+    "function recordTripAuditLog(accountId: string, eventId: string, checksum: number): string {",
+    "  void accountId;",
+    "  void eventId;",
+    "  return `${eventId}-${checksum}`;",
+    "}",
+    "",
+    "export function evaluateCircuitBreaker(state: RiskState): boolean {",
+    "  const startWindowChecksum = captureWindowChecksum(state.window);",
+    "  const drawdownBps = calculateDrawdownBps(state.pnlSeries, startWindowChecksum);",
+    "  const circuitActivationSeed = state.window.length + state.accountId.length;",
+    "  let riskAccumulator = 0;"
+  ];
+  for (let i = 0; i < 35; i += 1) {
+    lines.push(`  riskAccumulator += state.window[${i}] ?? 0;`);
+  }
+  lines.push(
+    "  const shouldTrip = drawdownBps >= HARD_DRAWDOWN_LIMIT_BPS || riskAccumulator >= RISK_ACCUMULATOR_LIMIT;",
+    "  if (!shouldTrip) {",
+    "    return false;",
+    "  }",
+    "  const tripEvent = publishTripEvent({",
+    "    reason: 'hard-drawdown',",
+    "    drawdownBps,",
+    "    riskAccumulator",
+    "  });",
+    "  const tripAuditDigest = recordTripAuditLog(state.accountId, tripEvent.eventId, startWindowChecksum);",
+    "  freezeOrderEntry(state.accountId, tripAuditDigest);",
+    "  return true;",
+    "}"
+  );
+  return lines.join("\n");
+}
+
+function buildOverlapHotspotFixture(): string {
+  const lines: string[] = [
+    "export function overlapMergeHotspot(seed: number): number {",
+    "  let total = seed;"
+  ];
+  for (let i = 0; i < 40; i += 1) {
+    lines.push(`  total += overlapMergeSignal(seed, ${i}); // overlap chunk merge hotspot coverage`);
+  }
+  lines.push(
+    "  return total;",
+    "}",
+    "",
+    "function overlapMergeSignal(seed: number, step: number): number {",
+    "  return seed + step;",
+    "}"
+  );
+  return lines.join("\n");
+}
+
+function buildLargeOverlapPressureFixture(): string {
+  const lines: string[] = [
+    "export function overlapPressureSignal(seed: number): number {",
+    "  let total = seed;"
+  ];
+  for (let i = 0; i < 220; i += 1) {
+    lines.push(
+      `  total += overlapPressureStep(seed, ${i}); // overlap pressure signal token cluster for chunk overlap diagnostics`
+    );
+  }
+  lines.push(
+    "  return total;",
+    "}",
+    "",
+    "function overlapPressureStep(seed: number, step: number): number {",
+    "  return seed + step;",
+    "}"
+  );
+  return lines.join("\n");
+}
+
+describe("mcp search quality regressions", () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    while (dirs.length > 0) {
+      const dir = dirs.pop();
+      if (dir) {
+        await rm(dir, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it("keeps MCP enforcement/config targets in top results and suppresses guidance noise", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-mcp-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "mcp-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-mcp",
+      tenant_id: "tenant-mcp",
+      name: "mcp",
+      project_root_path: "/workspace/mcp"
+    });
+
+    const cache = new SqliteQueryCache(sqlitePath);
+    const core = new RetrievalCore(repo, cache);
+
+    try {
+      await core.indexArtifact({
+        tenant_id: "tenant-mcp",
+        workspace_id: "ws-mcp",
+        index_version: "idx-mcp-v1",
+        files: [
+          {
+            path: "apps/mcp-api/src/server.ts",
+            language: "typescript",
+            content: `
+              export function resolveMcpAuthContext() {}
+              export function assertSessionMatchesAuth() {}
+              export function enforceMcpTenantBinding() {}
+              export function streamableHttpMcpRoute() {}
+            `
+          },
+          {
+            path: "apps/mcp-api/src/state.ts",
+            language: "typescript",
+            content: `
+              export const CUE_MCP_TOKEN_BINDINGS_JSON = "CUE_MCP_TOKEN_BINDINGS_JSON";
+              export function parseMcpTokenBindingsJson(raw: string) { return raw; }
+              export function resolveMcpAuthConfigFromEnv() { return { tenant_id: "t", workspace_id: "w", project_root_path: "/p" }; }
+            `
+          },
+          {
+            path: "apps/mcp-api/src/mcp-stdio.ts",
+            language: "typescript",
+            content: `
+              export function bootstrapRemoteProxy() {}
+              export function runRemoteMcpStdioServer() {}
+              export const REMOTE_BINDING_FIELDS = ["workspace_id", "project_root_path"];
+            `
+          },
+          {
+            path: "apps/mcp-api/src/mcp-tool-guidance.ts",
+            language: "typescript",
+            content: `
+              // guidance-only text containing overlapping auth/config terms
+              export const GUIDE = "tenant_id workspace_id project_root_path token binding mcp security config";
+            `
+          },
+          {
+            path: "apps/mcp-api/src/tools/search-context.ts",
+            language: "typescript",
+            content: "export function searchContextTool() { return 'tool'; }"
+          },
+          {
+            path: "apps/mcp-api/src/tools/enhance-prompt.ts",
+            language: "typescript",
+            content: "export function enhancePromptTool() { return 'tool'; }"
+          },
+          {
+            path: "apps/mcp-api/src/docs/reference.md",
+            language: "markdown",
+            content: "MCP docs reference for tokens, tenant_id, workspace_id, and project_root_path."
+          }
+        ]
+      });
+
+      const enforcement = await core.searchContext({
+        trace_id: "trc-mcp-enforcement",
+        tenant_id: "tenant-mcp",
+        workspace_id: "ws-mcp",
+        request: {
+          project_root_path: "/workspace/mcp",
+          query: "resolveMcpAuthContext enforceMcpTenantBinding assertSessionMatchesAuth streamable HTTP /mcp",
+          top_k: 8,
+          filters: { path_prefix: "apps/mcp-api/src" }
+        }
+      });
+
+      const config = await core.searchContext({
+        trace_id: "trc-mcp-config",
+        tenant_id: "tenant-mcp",
+        workspace_id: "ws-mcp",
+        request: {
+          project_root_path: "/workspace/mcp",
+          query: "CUE_MCP_TOKEN_BINDINGS_JSON parse token bindings tenant_id workspace_id project_root_path",
+          top_k: 6,
+          filters: { path_prefix: "apps/mcp-api/src" }
+        }
+      });
+
+      const stdio = await core.searchContext({
+        trace_id: "trc-mcp-stdio",
+        tenant_id: "tenant-mcp",
+        workspace_id: "ws-mcp",
+        request: {
+          project_root_path: "/workspace/mcp",
+          query: "mcp-stdio remote bootstrap token binding workspace_id project_root_path",
+          top_k: 6,
+          filters: { path_prefix: "apps/mcp-api/src" }
+        }
+      });
+
+      const enforcementTarget = firstRank(enforcement.results, "apps/mcp-api/src/server.ts");
+      const configTarget = firstRank(config.results, "apps/mcp-api/src/state.ts");
+      const stdioTarget = firstRank(stdio.results, "apps/mcp-api/src/mcp-stdio.ts");
+      const enforcementGuidance = firstRank(enforcement.results, "apps/mcp-api/src/mcp-tool-guidance.ts");
+      const configGuidance = firstRank(config.results, "apps/mcp-api/src/mcp-tool-guidance.ts");
+
+      expect(enforcementTarget).toBeLessThanOrEqual(3);
+      expect(configTarget).toBeLessThanOrEqual(3);
+      expect(stdioTarget).toBeLessThanOrEqual(3);
+      expect(enforcementGuidance).toBeGreaterThan(enforcementTarget);
+      expect(configGuidance).toBeGreaterThan(configTarget);
+    } finally {
+      cache.close();
+      repo.close();
+    }
+  });
+
+  it("prioritizes architecture entrypoints and limits markdown saturation for architecture queries", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-architecture-ranking-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "architecture-ranking.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-architecture",
+      tenant_id: "tenant-architecture",
+      name: "architecture",
+      project_root_path: "/workspace/architecture"
+    });
+
+    const cache = new SqliteQueryCache(sqlitePath);
+    const core = new RetrievalCore(repo, cache);
+
+    try {
+      await core.indexArtifact({
+        tenant_id: "tenant-architecture",
+        workspace_id: "ws-architecture",
+        index_version: "idx-architecture-v1",
+        files: [
+          {
+            path: "apps/api/src/index.ts",
+            language: "typescript",
+            content:
+              "export function bootstrapApiEntrypoint() {}\nexport function mountRoutesAndMiddleware() {}\n"
+          },
+          {
+            path: "packages/oracle/src/index.ts",
+            language: "typescript",
+            content: "export function startOracleCycle() {}\nexport function buildOracleModules() {}\n"
+          },
+          {
+            path: "packages/quant/src/index.ts",
+            language: "typescript",
+            content: "export function startQuantEngine() {}\nexport function createQuantModules() {}\n"
+          },
+          {
+            path: "packages/shared/src/index.ts",
+            language: "typescript",
+            content: "export * from './risk';\nexport * from './db';\n"
+          },
+          {
+            path: "apps/dashboard/src/app/layout.tsx",
+            language: "tsx",
+            content: "export default function RootLayout({ children }) { return children; }\n"
+          },
+          {
+            path: "packages/db/src/index.ts",
+            language: "typescript",
+            content: "export function createDbClient() {}\n"
+          },
+          {
+            path: "turbo.json",
+            language: "json",
+            content: "{\"pipeline\":{\"build\":{\"dependsOn\":[\"^build\"]}}}\n"
+          },
+          {
+            path: "package.json",
+            language: "json",
+            content: "{\"name\":\"architecture-monorepo\",\"workspaces\":[\"apps/*\",\"packages/*\"]}\n"
+          },
+          {
+            path: "docs/README.md",
+            language: "markdown",
+            content:
+              "Architecture overview and trading system modules with entry points and structure documentation."
+          },
+          {
+            path: "docs/02-architecture-overview.md",
+            language: "markdown",
+            content: "System architecture overview describing modules, entry points, and organization."
+          },
+          {
+            path: "docs/oracle-arch-review.md",
+            language: "markdown",
+            content: "Architecture review for oracle modules and architecture evolution."
+          },
+          {
+            path: "docs/05-shared-infra.md",
+            language: "markdown",
+            content: "Shared infrastructure architecture module layout and architecture notes."
+          }
+        ]
+      });
+
+      const result = await core.searchContext({
+        trace_id: "trc-architecture-query",
+        tenant_id: "tenant-architecture",
+        workspace_id: "ws-architecture",
+        request: {
+          project_root_path: "/workspace/architecture",
+          query: "How is the trading system architecture organized? What are the main modules and entry points?",
+          top_k: 8
+        }
+      });
+
+      const mdCount = markdownCount(result.results);
+      const codeCount = result.results.length - mdCount;
+      const structuralTargets = [
+        "apps/api/src/index.ts",
+        "packages/oracle/src/index.ts",
+        "packages/quant/src/index.ts",
+        "packages/shared/src/index.ts",
+        "apps/dashboard/src/app/layout.tsx",
+        "packages/db/src/index.ts",
+        "turbo.json",
+        "package.json"
+      ];
+      const structuralHits = structuralTargets.filter((path) => firstRank(result.results, path) <= 8).length;
+
+      expect(mdCount).toBeLessThanOrEqual(2);
+      expect(codeCount).toBeGreaterThanOrEqual(5);
+      expect(firstRank(result.results, "apps/api/src/index.ts")).toBeLessThanOrEqual(4);
+      expect(structuralHits).toBeGreaterThanOrEqual(5);
+    } finally {
+      cache.close();
+      repo.close();
+    }
+  });
+
+  it("keeps enhancer architecture context refs code-forward with markdown diversity cap", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-enhancer-architecture-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "enhancer-architecture.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-enhancer-architecture",
+      tenant_id: "tenant-enhancer-architecture",
+      name: "enhancer-architecture",
+      project_root_path: "/workspace/enhancer-architecture"
+    });
+
+    const cache = new SqliteQueryCache(sqlitePath);
+    const core = new RetrievalCore(repo, cache);
+
+    try {
+      await core.indexArtifact({
+        tenant_id: "tenant-enhancer-architecture",
+        workspace_id: "ws-enhancer-architecture",
+        index_version: "idx-enhancer-architecture-v1",
+        files: [
+          {
+            path: "apps/api/src/index.ts",
+            language: "typescript",
+            content:
+              "export function bootstrapApiEntrypoint() {}\nexport function mountRoutesAndMiddleware() {}\n"
+          },
+          {
+            path: "packages/oracle/src/index.ts",
+            language: "typescript",
+            content: "export function startOracleCycle() {}\n"
+          },
+          {
+            path: "packages/quant/src/index.ts",
+            language: "typescript",
+            content: "export function startQuantEngine() {}\n"
+          },
+          {
+            path: "packages/shared/src/index.ts",
+            language: "typescript",
+            content: "export * from './risk';\nexport * from './db';\n"
+          },
+          {
+            path: "docs/README.md",
+            language: "markdown",
+            content:
+              "Architecture overview and trading system modules with entry points and structure documentation."
+          },
+          {
+            path: "docs/02-architecture-overview.md",
+            language: "markdown",
+            content: "System architecture overview describing modules, entry points, and organization."
+          },
+          {
+            path: "docs/oracle-arch-review.md",
+            language: "markdown",
+            content: "Architecture review for oracle modules and architecture evolution."
+          }
+        ]
+      });
+
+      const output = await core.enhancePrompt({
+        trace_id: "trc-enhancer-architecture-query",
+        tenant_id: "tenant-enhancer-architecture",
+        workspace_id: "ws-enhancer-architecture",
+        request: {
+          project_root_path: "/workspace/enhancer-architecture",
+          prompt: "How is the trading system architecture organized? What are the main modules and entry points?",
+          conversation_history: [
+            {
+              role: "user",
+              content: "Focus on code entry points and wiring, keep docs secondary."
+            }
+          ]
+        }
+      });
+
+      const mdCount = markdownCount(output.context_refs);
+      const codeCount = output.context_refs.length - mdCount;
+
+      expect(mdCount).toBeLessThanOrEqual(2);
+      expect(codeCount).toBeGreaterThanOrEqual(2);
+      expect(firstRank(output.context_refs, "apps/api/src/index.ts")).toBeLessThanOrEqual(3);
+    } finally {
+      cache.close();
+      repo.close();
+    }
+  });
+
+  it("maintains or improves snippet completeness with upgraded chunk windows", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-mcp-snippet-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "mcp-snippet-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-snippet-legacy",
+      tenant_id: "tenant-snippet",
+      name: "snippet-quality-legacy",
+      project_root_path: "/workspace/snippet-legacy"
+    });
+    await repo.upsertWorkspace({
+      workspace_id: "ws-snippet-upgraded",
+      tenant_id: "tenant-snippet",
+      name: "snippet-quality-upgraded",
+      project_root_path: "/workspace/snippet-upgraded"
+    });
+
+    const cache = new SqliteQueryCache(sqlitePath);
+    const legacyCore = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 220,
+        chunk_overlap_tokens: 40
+      }
+    });
+    const upgradedCore = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 420,
+        chunk_overlap_tokens: 90
+      }
+    });
+
+    try {
+      const files = [
+        {
+          path: "packages/shared/src/risk/circuit-breaker.ts",
+          language: "typescript",
+          content: buildLongCircuitBreakerFixture()
+        },
+        {
+          path: "docs/risk-architecture.md",
+          language: "markdown",
+          content: "High-level risk architecture notes: circuit breaker policy, drawdown thresholds, and account controls."
+        }
+      ] as const;
+
+      await legacyCore.indexArtifact({
+        tenant_id: "tenant-snippet",
+        workspace_id: "ws-snippet-legacy",
+        index_version: "idx-snippet-legacy-v1",
+        files: [...files]
+      });
+      await upgradedCore.indexArtifact({
+        tenant_id: "tenant-snippet",
+        workspace_id: "ws-snippet-upgraded",
+        index_version: "idx-snippet-upgraded-v1",
+        files: [...files]
+      });
+
+      const query = "evaluateCircuitBreaker circuitActivationSeed tripAuditDigest freezeOrderEntry hard drawdown";
+      const legacyRetrieval = await legacyCore.searchContext({
+        trace_id: "trc-snippet-completeness-legacy",
+        tenant_id: "tenant-snippet",
+        workspace_id: "ws-snippet-legacy",
+        request: {
+          project_root_path: "/workspace/snippet-legacy",
+          query,
+          top_k: 5
+        }
+      });
+      const upgradedRetrieval = await upgradedCore.searchContext({
+        trace_id: "trc-snippet-completeness-upgraded",
+        tenant_id: "tenant-snippet",
+        workspace_id: "ws-snippet-upgraded",
+        request: {
+          project_root_path: "/workspace/snippet-upgraded",
+          query,
+          top_k: 5
+        }
+      });
+
+      const targetPath = "packages/shared/src/risk/circuit-breaker.ts";
+      const legacyTop = legacyRetrieval.results.find((row) => row.path === targetPath);
+      const upgradedTop = upgradedRetrieval.results.find((row) => row.path === targetPath);
+      expect(legacyTop).toBeDefined();
+      expect(upgradedTop).toBeDefined();
+
+      const legacySpan = (legacyTop?.end_line ?? 0) - (legacyTop?.start_line ?? 0);
+      const upgradedSpan = (upgradedTop?.end_line ?? 0) - (upgradedTop?.start_line ?? 0);
+      expect(upgradedSpan).toBeGreaterThanOrEqual(legacySpan);
+      expect((upgradedTop?.snippet.length ?? 0)).toBeGreaterThanOrEqual(legacyTop?.snippet.length ?? 0);
+
+      const tokenCoverage = (snippet: string | undefined): number =>
+        ["circuitActivationSeed", "tripAuditDigest", "freezeOrderEntry"].filter((token) => snippet?.includes(token))
+          .length;
+      expect(tokenCoverage(upgradedTop?.snippet)).toBeGreaterThanOrEqual(tokenCoverage(legacyTop?.snippet));
+      expect(tokenCoverage(upgradedTop?.snippet)).toBeGreaterThanOrEqual(2);
+    } finally {
+      cache.close();
+      repo.close();
+    }
+  });
+
+  it("merges overlapping top candidates to recover distinct file coverage", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-overlap-merge-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "overlap-merge-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-overlap",
+      tenant_id: "tenant-overlap",
+      name: "overlap-merge",
+      project_root_path: "/workspace/overlap"
+    });
+
+    const writerCache = new InMemoryQueryCache();
+    const withoutMergeCache = new InMemoryQueryCache();
+    const withMergeCache = new InMemoryQueryCache();
+    const writer = new RetrievalCore(repo, writerCache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 70,
+        chunk_overlap_tokens: 60
+      }
+    });
+    const withoutMerge = new RetrievalCore(repo, withoutMergeCache, {
+      scoringConfig: {
+        candidate_weights: {
+          lexical_weight: 1,
+          vector_weight: 0,
+          path_match_boost: 0.2,
+          recency_boost: 0,
+          generated_penalty: 0
+        },
+        rerank: {
+          merge_overlapping_chunks_enabled: false
+        }
+      }
+    });
+    const withMerge = new RetrievalCore(repo, withMergeCache, {
+      scoringConfig: {
+        candidate_weights: {
+          lexical_weight: 1,
+          vector_weight: 0,
+          path_match_boost: 0,
+          recency_boost: 0,
+          generated_penalty: 0
+        },
+        rerank: {
+          merge_overlapping_chunks_enabled: true
+        }
+      }
+    });
+
+    try {
+      await writer.indexArtifact({
+        tenant_id: "tenant-overlap",
+        workspace_id: "ws-overlap",
+        index_version: "idx-overlap-v1",
+        files: [
+          {
+            path: "src/hotspot.ts",
+            language: "typescript",
+            content: buildOverlapHotspotFixture()
+          },
+          {
+            path: "src/secondary.ts",
+            language: "typescript",
+            content:
+              "export function overlapCoverageFallback(): string { return 'overlap merge hotspot coverage fallback target overlap chunk'; }"
+          },
+          {
+            path: "src/noise.ts",
+            language: "typescript",
+            content: "export const NOISE = 'unrelated';"
+          }
+        ]
+      });
+
+      const query = "overlapMergeSignal overlap chunk merge hotspot coverage fallback target";
+      const baseline = await withoutMerge.searchContext({
+        trace_id: "trc-overlap-no-merge",
+        tenant_id: "tenant-overlap",
+        workspace_id: "ws-overlap",
+        request: {
+          project_root_path: "/workspace/overlap",
+          query,
+          top_k: 2
+        }
+      });
+      const merged = await withMerge.searchContext({
+        trace_id: "trc-overlap-merge",
+        tenant_id: "tenant-overlap",
+        workspace_id: "ws-overlap",
+        request: {
+          project_root_path: "/workspace/overlap",
+          query,
+          top_k: 2
+        }
+      });
+
+      expect(baseline.results[0]?.path).toBe("src/hotspot.ts");
+      expect(baseline.results[1]?.path).toBe("src/hotspot.ts");
+      const baselineFirst = baseline.results[0];
+      const baselineSecond = baseline.results[1];
+      expect(baselineFirst).toBeDefined();
+      expect(baselineSecond).toBeDefined();
+      const overlapStart = Math.max(baselineFirst?.start_line ?? 0, baselineSecond?.start_line ?? 0);
+      const overlapEnd = Math.min(baselineFirst?.end_line ?? 0, baselineSecond?.end_line ?? 0);
+      expect(overlapStart).toBeLessThanOrEqual(overlapEnd);
+
+      expect(merged.results[0]?.path).toBe("src/hotspot.ts");
+      expect(merged.results.some((result) => result.path === "src/secondary.ts")).toBe(true);
+      expect(new Set(merged.results.map((result) => result.path)).size).toBeGreaterThan(
+        new Set(baseline.results.map((result) => result.path)).size
+      );
+      const mergedHotspot = merged.results.find((result) => result.path === "src/hotspot.ts");
+      expect((mergedHotspot?.end_line ?? 0) - (mergedHotspot?.start_line ?? 0)).toBeGreaterThan(40);
+    } finally {
+      repo.close();
+    }
+  });
+
+  it("avoids heavy same-file overlap even when merge span cap prevents direct consolidation", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-overlap-selection-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "overlap-selection-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-overlap-selection",
+      tenant_id: "tenant-overlap-selection",
+      name: "overlap-selection",
+      project_root_path: "/workspace/overlap-selection"
+    });
+
+    const writer = new RetrievalCore(repo, new InMemoryQueryCache(), {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 70,
+        chunk_overlap_tokens: 60
+      }
+    });
+    const merged = new RetrievalCore(repo, new InMemoryQueryCache(), {
+      scoringConfig: {
+        candidate_weights: {
+          lexical_weight: 1,
+          vector_weight: 0,
+          path_match_boost: 0,
+          recency_boost: 0,
+          generated_penalty: 0
+        },
+        rerank: {
+          merge_overlapping_chunks_enabled: true,
+          merge_max_span_lines: 8
+        }
+      }
+    });
+
+    try {
+      await writer.indexArtifact({
+        tenant_id: "tenant-overlap-selection",
+        workspace_id: "ws-overlap-selection",
+        index_version: "idx-overlap-selection-v1",
+        files: [
+          {
+            path: "src/pressure.ts",
+            language: "typescript",
+            content: buildLargeOverlapPressureFixture()
+          },
+          {
+            path: "src/fallback.ts",
+            language: "typescript",
+            content:
+              "export function overlapPressureFallback(): string { return 'overlap pressure signal token cluster fallback target'; }"
+          },
+          {
+            path: "src/extra.ts",
+            language: "typescript",
+            content:
+              "export function overlapPressureExtra(): string { return 'overlap pressure signal token cluster extra coverage'; }"
+          }
+        ]
+      });
+
+      const retrieval = await merged.searchContext({
+        trace_id: "trc-overlap-selection",
+        tenant_id: "tenant-overlap-selection",
+        workspace_id: "ws-overlap-selection",
+        request: {
+          project_root_path: "/workspace/overlap-selection",
+          query: "overlap pressure signal token cluster fallback target",
+          top_k: 3
+        }
+      });
+
+      expect(retrieval.results.some((result) => result.path === "src/fallback.ts")).toBe(true);
+
+      const byPath = new Map<string, Array<{ start: number; end: number }>>();
+      for (const result of retrieval.results) {
+        const rows = byPath.get(result.path);
+        const range = { start: result.start_line, end: result.end_line };
+        if (rows) {
+          rows.push(range);
+        } else {
+          byPath.set(result.path, [range]);
+        }
+      }
+
+      for (const ranges of byPath.values()) {
+        for (let i = 0; i < ranges.length; i += 1) {
+          const left = ranges[i];
+          if (!left) {
+            continue;
+          }
+          for (let j = i + 1; j < ranges.length; j += 1) {
+            const right = ranges[j];
+            if (!right) {
+              continue;
+            }
+            const overlapStart = Math.max(left.start, right.start);
+            const overlapEnd = Math.min(left.end, right.end);
+            const overlapLength = overlapEnd >= overlapStart ? overlapEnd - overlapStart + 1 : 0;
+            const leftLength = Math.max(1, left.end - left.start + 1);
+            const rightLength = Math.max(1, right.end - right.start + 1);
+            const smaller = Math.min(leftLength, rightLength);
+            const overlapRatio = overlapLength / smaller;
+            expect(overlapRatio).toBeLessThan(0.2);
+          }
+        }
+      }
+    } finally {
+      repo.close();
+    }
+  });
+
+  it("absorbs contiguous same-file chunks during selection so top-k recovers file diversity", async () => {
+    const now = new Date().toISOString();
+    const rankedCandidates: RankedChunkCandidate[] = [
+      {
+        chunk_id: "chunk-circuit-1",
+        file_id: "file-circuit",
+        path: "src/circuitBreaker.ts",
+        start_line: 1,
+        end_line: 207,
+        snippet: "export function circuitBreakerPrimary() { return 'circuit breaker primary'; }",
+        updated_at: now,
+        score: 0.98,
+        lexical_score: 0.98,
+        vector_score: 0,
+        path_match: false,
+        recency_boosted: true
+      },
+      {
+        chunk_id: "chunk-circuit-2",
+        file_id: "file-circuit",
+        path: "src/circuitBreaker.ts",
+        start_line: 208,
+        end_line: 400,
+        snippet: "export function circuitBreakerSecondary() { return 'circuit breaker secondary'; }",
+        updated_at: now,
+        score: 0.97,
+        lexical_score: 0.97,
+        vector_score: 0,
+        path_match: false,
+        recency_boosted: true
+      },
+      {
+        chunk_id: "chunk-fallback",
+        file_id: "file-fallback",
+        path: "src/fallback.ts",
+        start_line: 1,
+        end_line: 80,
+        snippet: "export function fallbackSignal() { return 'fallback target'; }",
+        updated_at: now,
+        score: 0.75,
+        lexical_score: 0.75,
+        vector_score: 0,
+        path_match: false,
+        recency_boosted: true
+      },
+      {
+        chunk_id: "chunk-estimator",
+        file_id: "file-estimator",
+        path: "src/estimator.ts",
+        start_line: 1,
+        end_line: 70,
+        snippet: "export function estimatorSignal() { return 'estimator target'; }",
+        updated_at: now,
+        score: 0.74,
+        lexical_score: 0.74,
+        vector_score: 0,
+        path_match: false,
+        recency_boosted: true
+      }
+    ];
+
+    const store = {
+      getLatestReadyIndex: async () => ({
+        index_id: "idx-overlap-adjacent",
+        workspace_id: "ws-overlap-adjacent",
+        tenant_id: "tenant-overlap-adjacent",
+        index_version: "idx-overlap-adjacent-v1",
+        status: "ready" as const,
+        created_at: now,
+        updated_at: now
+      }),
+      getIndexMetadata: async () => ({
+        index_id: "idx-overlap-adjacent",
+        tenant_id: "tenant-overlap-adjacent",
+        embedding_provider: "deterministic",
+        embedding_model: "pseudo-sha256",
+        embedding_dimensions: 24,
+        embedding_version: "v1",
+        chunking_strategy: "sliding" as const,
+        chunking_fallback_strategy: "sliding" as const
+      }),
+      rankChunksByIndex: async () => rankedCandidates,
+      listChunksByIndex: async () => []
+    } as unknown as IndexRepository;
+
+    const merged = new RetrievalCore(store, new InMemoryQueryCache(), {
+      scoringConfig: {
+        candidate_weights: {
+          lexical_weight: 1,
+          vector_weight: 0,
+          path_match_boost: 0,
+          recency_boost: 0,
+          generated_penalty: 0
+        },
+        rerank: {
+          merge_overlapping_chunks_enabled: true,
+          merge_max_span_lines: 40
+        }
+      }
+    });
+
+    const retrieval = await merged.searchContext({
+      trace_id: "trc-overlap-adjacent-selection",
+      tenant_id: "tenant-overlap-adjacent",
+      workspace_id: "ws-overlap-adjacent",
+      request: {
+        project_root_path: "/workspace/overlap-adjacent",
+        query: "circuit breaker fallback estimator",
+        top_k: 3
+      }
+    });
+
+    const distinctPaths = new Set(retrieval.results.map((result) => result.path));
+    expect(retrieval.results).toHaveLength(3);
+    expect(distinctPaths.size).toBe(3);
+    expect(retrieval.results.filter((result) => result.path === "src/circuitBreaker.ts")).toHaveLength(1);
+    expect(distinctPaths.has("src/fallback.ts")).toBe(true);
+    expect(distinctPaths.has("src/estimator.ts")).toBe(true);
+
+    const mergedCircuitBreaker = retrieval.results.find((result) => result.path === "src/circuitBreaker.ts");
+    expect(mergedCircuitBreaker).toBeDefined();
+    expect(mergedCircuitBreaker?.start_line).toBe(1);
+    expect(mergedCircuitBreaker?.end_line).toBe(400);
+  });
+
+  it("packs same-file contextual spans with elision markers when context packing is enabled", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-context-packing-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "context-packing-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-context-pack",
+      tenant_id: "tenant-context-pack",
+      name: "context-pack",
+      project_root_path: "/workspace/context-pack"
+    });
+
+    const cache = new InMemoryQueryCache();
+    const core = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 35,
+        chunk_overlap_tokens: 8
+      },
+      scoringConfig: {
+        rerank: {
+          merge_overlapping_chunks_enabled: false
+        }
+      },
+      contextPackingConfig: {
+        enabled: true,
+        max_spans_per_result: 2,
+        max_gap_lines: 90,
+        max_snippet_chars: 3_200,
+        enhancer_snippet_char_limit: 2_200
+      }
+    });
+
+    try {
+      const bridgeNoise = Array.from({ length: 60 }, (_, idx) => `const bridgeNoise${idx} = ${idx};`);
+      await core.indexArtifact({
+        tenant_id: "tenant-context-pack",
+        workspace_id: "ws-context-pack",
+        index_version: "idx-context-pack-v1",
+        files: [
+          {
+            path: "packages/oracle/src/estimator.ts",
+            language: "typescript",
+            content: [
+              "export function computeProbability(marketSignal: number): number {",
+              "  const base = marketSignal * 0.7;",
+              "  const normalized = Math.max(0, Math.min(1, base));",
+              "  return normalized;",
+              "}",
+              "",
+              ...bridgeNoise,
+              "",
+              "export function fetchLlmInputs(llmInputFlow: string[]): string[] {",
+              "  return llmInputFlow.filter(Boolean);",
+              "}"
+            ].join("\n")
+          }
+        ]
+      });
+
+      const retrieval = await core.searchContext({
+        trace_id: "trc-context-pack",
+        tenant_id: "tenant-context-pack",
+        workspace_id: "ws-context-pack",
+        request: {
+          project_root_path: "/workspace/context-pack",
+          query: "computeProbability marketSignal fetchLlmInputs llmInputFlow",
+          top_k: 1
+        }
+      });
+
+      const top = retrieval.results[0];
+      expect(top).toBeDefined();
+      expect(top?.path).toBe("packages/oracle/src/estimator.ts");
+      expect(top?.snippet.includes("computeProbability")).toBe(true);
+      expect(top?.snippet.includes("fetchLlmInputs")).toBe(true);
+      expect(top?.snippet.includes("...")).toBe(true);
+      expect(top?.reason.includes("contextual spans")).toBe(true);
+      expect((top?.end_line ?? 0) - (top?.start_line ?? 0)).toBeGreaterThan(20);
+    } finally {
+      repo.close();
+    }
+  });
+
+  it("adds deterministic truncation metadata marker for broken TS function boundaries when enabled", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-snippet-integrity-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "snippet-integrity-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-snippet-integrity",
+      tenant_id: "tenant-snippet-integrity",
+      name: "snippet-integrity",
+      project_root_path: "/workspace/snippet-integrity"
+    });
+
+    const cache = new InMemoryQueryCache();
+    const core = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 35,
+        chunk_overlap_tokens: 8
+      },
+      scoringConfig: {
+        rerank: {
+          merge_overlapping_chunks_enabled: false
+        }
+      },
+      snippetIntegrityConfig: {
+        enabled: true,
+        target_languages: ["typescript"],
+        max_contiguous_gap_lines: 6,
+        marker_template_version: "v1"
+      }
+    });
+
+    try {
+      const body = Array.from(
+        { length: 500 },
+        (_, idx) => `  const checkpoint_${idx} = input + ${idx}; // estimator continuity signal`
+      );
+      await core.indexArtifact({
+        tenant_id: "tenant-snippet-integrity",
+        workspace_id: "ws-snippet-integrity",
+        index_version: "idx-snippet-integrity-v1",
+        files: [
+          {
+            path: "src/estimator.ts",
+            language: "typescript",
+            content: [
+              "export function estimateProbability(input: number): number {",
+              ...body,
+              "  return input;",
+              "}",
+              "",
+              "export function calibrateProbability(input: number): number {",
+              "  return estimateProbability(input + 1);",
+              "}"
+            ].join("\n")
+          }
+        ]
+      });
+
+      const retrieval = await core.searchContext({
+        trace_id: "trc-snippet-integrity",
+        tenant_id: "tenant-snippet-integrity",
+        workspace_id: "ws-snippet-integrity",
+        request: {
+          project_root_path: "/workspace/snippet-integrity",
+          query: "estimateProbability checkpoint_20 checkpoint_430",
+          top_k: 1
+        }
+      });
+
+      expect(() => SearchContextOutputSchema.parse(retrieval)).not.toThrow();
+      const top = retrieval.results[0];
+      expect(top).toBeDefined();
+      expect(top?.path).toBe("src/estimator.ts");
+      const markerLine = top?.snippet.split("\n").find((line) => line.includes("[truncated:v1"));
+      expect(markerLine).toBeDefined();
+      expect(markerLine).toMatch(/symbol=(?!unknown)[A-Za-z_$][\w$]*/);
+      expect(markerLine).toContain("estimated_total_lines=");
+      expect(markerLine).toContain("through_line=");
+      const omittedAfterMatch = markerLine?.match(/omitted_after=(\d+)/);
+      expect(Number.parseInt(omittedAfterMatch?.[1] ?? "0", 10)).toBeGreaterThan(0);
+    } finally {
+      repo.close();
+    }
+  });
+
+  it("repairs contiguous TS snippets before annotation when repair is enabled", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-snippet-repair-quality-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "snippet-repair-quality.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-snippet-repair",
+      tenant_id: "tenant-snippet-repair",
+      name: "snippet-repair",
+      project_root_path: "/workspace/snippet-repair"
+    });
+
+    const cache = new InMemoryQueryCache();
+    const core = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 35,
+        chunk_overlap_tokens: 8
+      },
+      scoringConfig: {
+        rerank: {
+          merge_overlapping_chunks_enabled: false
+        }
+      },
+      snippetIntegrityConfig: {
+        enabled: true,
+        target_languages: ["typescript"],
+        max_contiguous_gap_lines: 6,
+        marker_template_version: "v1",
+        repair_enabled: true,
+        repair_max_envelope_lines: 260,
+        repair_max_snippet_chars: 8_000
+      }
+    });
+
+    try {
+      const body = Array.from(
+        { length: 120 },
+        (_, idx) => `  const checkpoint_${idx} = input + ${idx}; // repair continuity signal`
+      );
+      await core.indexArtifact({
+        tenant_id: "tenant-snippet-repair",
+        workspace_id: "ws-snippet-repair",
+        index_version: "idx-snippet-repair-v1",
+        files: [
+          {
+            path: "src/repair.ts",
+            language: "typescript",
+            content: [
+              "export function estimateRepair(input: number): number {",
+              ...body,
+              "  return input;",
+              "}"
+            ].join("\n")
+          }
+        ]
+      });
+
+      const retrieval = await core.searchContext({
+        trace_id: "trc-snippet-repair",
+        tenant_id: "tenant-snippet-repair",
+        workspace_id: "ws-snippet-repair",
+        request: {
+          project_root_path: "/workspace/snippet-repair",
+          query: "estimateRepair checkpoint_10 checkpoint_110",
+          top_k: 1
+        }
+      });
+
+      const top = retrieval.results[0];
+      expect(top).toBeDefined();
+      expect(top?.path).toBe("src/repair.ts");
+      expect(top?.snippet.includes("checkpoint_10")).toBe(true);
+      expect(top?.snippet.includes("checkpoint_110")).toBe(true);
+      expect(top?.snippet.includes("[truncated:v1")).toBe(false);
+      expect((top?.end_line ?? 0) - (top?.start_line ?? 0)).toBeGreaterThan(80);
+    } finally {
+      repo.close();
+    }
+  });
+
+  it("falls back to truncation marker when repair output still exceeds caps", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-snippet-repair-fallback-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "snippet-repair-fallback.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-snippet-repair-fallback",
+      tenant_id: "tenant-snippet-repair-fallback",
+      name: "snippet-repair-fallback",
+      project_root_path: "/workspace/snippet-repair-fallback"
+    });
+
+    const cache = new InMemoryQueryCache();
+    const core = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "sliding",
+        target_chunk_tokens: 35,
+        chunk_overlap_tokens: 8
+      },
+      scoringConfig: {
+        rerank: {
+          merge_overlapping_chunks_enabled: false
+        }
+      },
+      snippetIntegrityConfig: {
+        enabled: true,
+        target_languages: ["typescript"],
+        max_contiguous_gap_lines: 6,
+        marker_template_version: "v1",
+        repair_enabled: true,
+        repair_max_envelope_lines: 260,
+        repair_max_snippet_chars: 220
+      }
+    });
+
+    try {
+      const body = Array.from(
+        { length: 120 },
+        (_, idx) => `  const checkpoint_${idx} = input + ${idx}; // repair fallback signal`
+      );
+      await core.indexArtifact({
+        tenant_id: "tenant-snippet-repair-fallback",
+        workspace_id: "ws-snippet-repair-fallback",
+        index_version: "idx-snippet-repair-fallback-v1",
+        files: [
+          {
+            path: "src/repair-fallback.ts",
+            language: "typescript",
+            content: [
+              "export function estimateRepairFallback(input: number): number {",
+              ...body,
+              "  return input;",
+              "}"
+            ].join("\n")
+          }
+        ]
+      });
+
+      const retrieval = await core.searchContext({
+        trace_id: "trc-snippet-repair-fallback",
+        tenant_id: "tenant-snippet-repair-fallback",
+        workspace_id: "ws-snippet-repair-fallback",
+        request: {
+          project_root_path: "/workspace/snippet-repair-fallback",
+          query: "estimateRepairFallback checkpoint_10 checkpoint_110",
+          top_k: 1
+        }
+      });
+
+      const top = retrieval.results[0];
+      expect(top).toBeDefined();
+      expect(top?.path).toBe("src/repair-fallback.ts");
+      expect(top?.snippet.includes("[truncated:v1")).toBe(true);
+    } finally {
+      repo.close();
+    }
+  });
+
+  it("does not add truncation marker for non-target languages", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cue-snippet-integrity-language-gate-"));
+    dirs.push(root);
+    const sqlitePath = join(root, "snippet-integrity-language-gate.sqlite");
+
+    const repo = new SqliteIndexRepository(sqlitePath);
+    await repo.migrate();
+    await repo.upsertWorkspace({
+      workspace_id: "ws-snippet-language-gate",
+      tenant_id: "tenant-snippet-language-gate",
+      name: "snippet-language-gate",
+      project_root_path: "/workspace/snippet-language-gate"
+    });
+
+    const cache = new InMemoryQueryCache();
+    const core = new RetrievalCore(repo, cache, {
+      chunkingConfig: {
+        strategy: "language_aware",
+        target_chunk_tokens: 40,
+        chunk_overlap_tokens: 8,
+        enabled_languages: ["go"]
+      },
+      snippetIntegrityConfig: {
+        enabled: true,
+        target_languages: ["typescript"],
+        max_contiguous_gap_lines: 6,
+        marker_template_version: "v1"
+      }
+    });
+
+    try {
+      const steps = Array.from({ length: 220 }, (_, idx) => `\ttotal += input + ${idx}`);
+      await core.indexArtifact({
+        tenant_id: "tenant-snippet-language-gate",
+        workspace_id: "ws-snippet-language-gate",
+        index_version: "idx-snippet-language-gate-v1",
+        files: [
+          {
+            path: "pkg/runtime/estimate.go",
+            language: "go",
+            content: [
+              "package runtime",
+              "",
+              "func EstimateProbability(input int) int {",
+              "\ttotal := 0",
+              ...steps,
+              "\treturn total",
+              "}"
+            ].join("\n")
+          }
+        ]
+      });
+
+      const retrieval = await core.searchContext({
+        trace_id: "trc-snippet-language-gate",
+        tenant_id: "tenant-snippet-language-gate",
+        workspace_id: "ws-snippet-language-gate",
+        request: {
+          project_root_path: "/workspace/snippet-language-gate",
+          query: "EstimateProbability input 200",
+          top_k: 1
+        }
+      });
+
+      const top = retrieval.results[0];
+      expect(top).toBeDefined();
+      expect(top?.path).toBe("pkg/runtime/estimate.go");
+      expect(top?.snippet.includes("[truncated:v1")).toBe(false);
+    } finally {
+      repo.close();
+    }
+  });
+});