@cue-dev/retrieval-core 0.1.3

package/test/enhance-confidence.test.ts

@@ -0,0 +1,752 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { InMemoryQueryCache } from "@cue-dev/data-plane";
+import { InMemoryIndexStore, RetrievalCore } from "../src/index.js";
+
+const testRerankerProvider = {
+  async rerank(input: { query: string; documents: string[]; top_n: number }) {
+    return input.documents.slice(0, input.top_n).map((_, index) => ({
+      index,
+      relevance_score: input.top_n - index
+    }));
+  },
+  describe: () => ({ provider: "test-reranker", model: "stub-v1" })
+};
+
+describe("enhance prompt confidence controls", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("filters risky refs when retrieval confidence is low", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+    vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-low-confidence",
+      results: [
+        {
+          path: "docs/reference/hooks.md",
+          start_line: 1,
+          end_line: 20,
+          snippet: "addHook lifecycle ordering and examples",
+          score: 0.71,
+          reason: "semantic match"
+        },
+        {
+          path: "test/hooks.test.js",
+          start_line: 1,
+          end_line: 25,
+          snippet: "addHook lifecycle should preserve plugin encapsulation",
+          score: 0.707,
+          reason: "path and token overlap"
+        },
+        {
+          path: "lib/hooks.js",
+          start_line: 1,
+          end_line: 40,
+          snippet: "function addHook(name, fn) { return hooks.add(name, fn) }",
+          score: 0.704,
+          reason: "exact symbol match"
+        },
+        {
+          path: "examples/hooks.js",
+          start_line: 1,
+          end_line: 22,
+          snippet: "example for addHook lifecycle behavior",
+          score: 0.703,
+          reason: "semantic match"
+        },
+        {
+          path: "lib/error-handler.js",
+          start_line: 1,
+          end_line: 30,
+          snippet: "function setErrorHandler(fn) { return fn }",
+          score: 0.702,
+          reason: "path and token overlap"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 15,
+        retrieval_mode: "hybrid",
+        index_version: "idx-1"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-low-confidence",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Refine addHook lifecycle runtime behavior and preserve plugin compatibility.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Avoid docs and tests as primary context." }]
+      }
+    });
+
+    expect(output.warnings).toEqual([]);
+    expect(output.questions).toEqual([]);
+    expect(output.context_refs.length).toBeGreaterThan(0);
+    expect(output.context_refs.some((ref) => ref.path === "lib/hooks.js")).toBe(true);
+    expect(output.context_refs.every((ref) => !/^docs\/|^test\/|^examples\//.test(ref.path))).toBe(true);
+  });
+
+  it("builds enhancer retrieval query from history symbols and implementation hints", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+    const searchSpy = vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-query-build",
+      results: [
+        {
+          path: "lib/error-handler.js",
+          start_line: 1,
+          end_line: 20,
+          snippet: "function setErrorHandler(fn) { return fn }",
+          score: 0.95,
+          reason: "exact symbol match"
+        },
+        {
+          path: "lib/hooks.js",
+          start_line: 1,
+          end_line: 20,
+          snippet: "function addHook(name, fn) { return hooks.add(name, fn) }",
+          score: 0.3,
+          reason: "path and token overlap"
+        },
+        {
+          path: "fastify.js",
+          start_line: 1,
+          end_line: 20,
+          snippet: "function setErrorHandler(fn) { return buildErrorHandler(fn) }",
+          score: 0.28,
+          reason: "path and token overlap"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 10,
+        retrieval_mode: "hybrid",
+        index_version: "idx-2"
+      }
+    });
+
+    await core.enhancePrompt({
+      trace_id: "trc-query-build",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Improve request pipeline error handling and keep behavior stable.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [
+          { role: "user", content: "Focus on `setErrorHandler` and onRequest ordering." },
+          { role: "assistant", content: "Likely files include lib/error-handler.js and fastify.js." }
+        ]
+      }
+    });
+
+    expect(searchSpy).toHaveBeenCalledTimes(1);
+    const retrievalQuery = searchSpy.mock.calls[0]?.[0].request.query ?? "";
+    expect(retrievalQuery).toContain("setErrorHandler");
+    expect(retrievalQuery).toContain("lib/error-handler.js");
+    expect(retrievalQuery).toMatch(/query_intent:\s+symbol-heavy/);
+    expect(retrievalQuery).toMatch(/retrieval_hints:\s+.*setErrorHandler.*lib\/error-handler\.js/);
+  });
+
+  it("routes symbol-heavy prompts to tighter pre-rerank caps", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerConfig: {
+        max_candidates_pre_rerank: 4
+      }
+    });
+    const searchSpy = vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-symbol-intent-cap",
+      results: [
+        {
+          path: "lib/error-handler.js",
+          start_line: 1,
+          end_line: 20,
+          snippet: "function setErrorHandler(fn) { return buildErrorHandler(fn) }",
+          score: 0.92,
+          reason: "exact symbol match"
+        },
+        {
+          path: "src/server.ts",
+          start_line: 1,
+          end_line: 20,
+          snippet: "addHook onRequest preHandler onError lifecycle",
+          score: 0.9,
+          reason: "path and token overlap"
+        },
+        {
+          path: "internal/router.ts",
+          start_line: 1,
+          end_line: 20,
+          snippet: "registerRoute and dispatchRequest internals",
+          score: 0.89,
+          reason: "path and token overlap"
+        },
+        {
+          path: "app/runtime.ts",
+          start_line: 1,
+          end_line: 20,
+          snippet: "runtime hook orchestration",
+          score: 0.88,
+          reason: "semantic match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 10,
+        retrieval_mode: "hybrid",
+        index_version: "idx-symbol-intent"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-symbol-intent-cap",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Refine `setErrorHandler` + `addHook` + `onRequest` + `preHandler` flow.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Target exact lifecycle symbols only." }]
+      }
+    });
+
+    const retrievalQuery = searchSpy.mock.calls[0]?.[0].request.query ?? "";
+    const retrievalTopK = searchSpy.mock.calls[0]?.[0].request.top_k;
+    expect(retrievalQuery).toMatch(/query_intent:\s+symbol-heavy/);
+    expect(retrievalTopK).toBe(8);
+    expect(output.context_refs.length).toBeLessThanOrEqual(3);
+  });
+
+  it("routes conceptual prompts without forcing implementation-only filtering", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+    const searchSpy = vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-conceptual-intent",
+      results: [
+        {
+          path: "docs/architecture/retrieval.md",
+          start_line: 1,
+          end_line: 30,
+          snippet: "retrieval architecture and ranking tradeoffs",
+          score: 0.91,
+          reason: "path and token overlap"
+        },
+        {
+          path: "src/retrieval/rerank.ts",
+          start_line: 1,
+          end_line: 20,
+          snippet: "rerank implementation details",
+          score: 0.89,
+          reason: "semantic match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 9,
+        retrieval_mode: "hybrid",
+        index_version: "idx-conceptual-intent"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-conceptual-intent",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Explain architecture tradeoffs for retrieval ranking and docs guidance.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Need high-level conceptual guidance." }]
+      }
+    });
+
+    const retrievalQuery = searchSpy.mock.calls[0]?.[0].request.query ?? "";
+    const retrievalTopK = searchSpy.mock.calls[0]?.[0].request.top_k;
+    expect(retrievalQuery).toMatch(/query_intent:\s+conceptual/);
+    expect(retrievalTopK).toBe(12);
+    expect(output.context_refs.some((ref) => ref.path.startsWith("docs/"))).toBe(true);
+  });
+
+  it("demotes declaration-heavy top hits during low-confidence rerank", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      rerankerProvider: testRerankerProvider
+    });
+    vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-declaration-demotion",
+      results: [
+        {
+          path: "types/hooks.d.ts",
+          start_line: 1,
+          end_line: 24,
+          snippet: "export interface HookContext { requestId: string; route: string }",
+          score: 0.92,
+          reason: "path and token overlap"
+        },
+        {
+          path: "lib/hooks.js",
+          start_line: 1,
+          end_line: 40,
+          snippet: "function addHook(name, fn) { return hooks.add(name, fn) }",
+          score: 0.91,
+          reason: "semantic match"
+        },
+        {
+          path: "lib/handle-request.js",
+          start_line: 1,
+          end_line: 35,
+          snippet: "function preHandlerHookRunner(state) { return state }",
+          score: 0.9,
+          reason: "semantic match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 10,
+        retrieval_mode: "hybrid",
+        index_version: "idx-declaration-demotion"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-declaration-demotion",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Stabilize runtime hook lifecycle behavior and avoid docs/examples context.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Keep implementation-focused guidance." }]
+      }
+    });
+
+    expect(output.context_refs.length).toBeGreaterThan(0);
+    expect(output.context_refs[0]?.path).not.toBe("types/hooks.d.ts");
+    expect(output.context_refs[0]?.path.startsWith("lib/")).toBe(true);
+    expect(output.context_refs[0]?.path.endsWith(".d.ts")).toBe(false);
+  });
+
+  it("skips enhancer rerank when reranker provider is not configured", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+    vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-rerank-disabled",
+      results: [
+        {
+          path: "types/hooks.d.ts",
+          start_line: 1,
+          end_line: 24,
+          snippet: "export interface HookContext { requestId: string; route: string }",
+          score: 0.92,
+          reason: "path and token overlap"
+        },
+        {
+          path: "lib/hooks.js",
+          start_line: 1,
+          end_line: 40,
+          snippet: "function addHook(name, fn) { return hooks.add(name, fn) }",
+          score: 0.91,
+          reason: "semantic match"
+        },
+        {
+          path: "lib/handle-request.js",
+          start_line: 1,
+          end_line: 35,
+          snippet: "function preHandlerHookRunner(state) { return state }",
+          score: 0.9,
+          reason: "semantic match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 10,
+        retrieval_mode: "hybrid",
+        index_version: "idx-rerank-disabled"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-rerank-disabled",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Stabilize runtime hook lifecycle behavior and avoid docs/examples context.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Keep implementation-focused guidance." }]
+      }
+    });
+
+    expect(output.context_refs.length).toBeGreaterThan(0);
+    expect(output.context_refs[0]?.path).toBe("types/hooks.d.ts");
+  });
+
+  it("applies negation-aware filtering for docs/tests/examples/archive paths", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache());
+    vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-negation-filter",
+      results: [
+        {
+          path: "docs/reference/blueprints.md",
+          start_line: 1,
+          end_line: 20,
+          snippet: "blueprints runtime design notes",
+          score: 0.93,
+          reason: "path and token overlap"
+        },
+        {
+          path: "tests/blueprints.test.py",
+          start_line: 1,
+          end_line: 20,
+          snippet: "test blueprint registration order",
+          score: 0.92,
+          reason: "path and token overlap"
+        },
+        {
+          path: "examples/blueprint_demo.py",
+          start_line: 1,
+          end_line: 20,
+          snippet: "example blueprint usage",
+          score: 0.91,
+          reason: "semantic match"
+        },
+        {
+          path: "src/flask/_archive/blueprints_legacy.py",
+          start_line: 1,
+          end_line: 30,
+          snippet: "legacy blueprint implementation",
+          score: 0.9,
+          reason: "semantic match"
+        },
+        {
+          path: "src/flask/blueprints.py",
+          start_line: 1,
+          end_line: 40,
+          snippet: "def register_blueprint(app, blueprint): return app",
+          score: 0.89,
+          reason: "exact symbol match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 12,
+        retrieval_mode: "hybrid",
+        index_version: "idx-negation"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-negation-filter",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Improve blueprints runtime behavior and avoid docs/tests/examples/archive context.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Keep implementation focused." }]
+      }
+    });
+
+    expect(output.context_refs.length).toBeGreaterThan(0);
+    expect(output.context_refs[0]?.path).toBe("src/flask/blueprints.py");
+    expect(output.context_refs.every((ref) => !/docs\/|tests\/|examples\/|_archive\//.test(ref.path))).toBe(true);
+  });
+
+  it("caps expansion hints and emits path-form hint expansions", async () => {
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerConfig: {
+        max_expansion_hints: 6
+      }
+    });
+    const searchSpy = vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-hint-cap",
+      results: [],
+      search_metadata: {
+        latency_ms: 8,
+        retrieval_mode: "hybrid",
+        index_version: "idx-cap"
+      }
+    });
+
+    await core.enhancePrompt({
+      trace_id: "trc-hint-cap",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Harden JSON provider and blueprints runtime behavior without docs.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Focus on `render_template_string` and json provider internals." }]
+      }
+    });
+
+    const retrievalQuery = searchSpy.mock.calls[0]?.[0].request.query ?? "";
+    expect(retrievalQuery).toContain("json/provider");
+    const hintLine = retrievalQuery
+      .split("\n")
+      .find((line) => line.startsWith("retrieval_hints:"));
+    const hintCount = (hintLine ?? "")
+      .replace(/^retrieval_hints:\s*/u, "")
+      .split(/\s+/)
+      .filter(Boolean).length;
+    expect(hintCount).toBeLessThanOrEqual(6);
+  });
+
+  it("uses configured enhancer provider output", async () => {
+    const generate = vi.fn(async (_input: unknown) => ({
+      enhanced_prompt: "Provider-generated plan with explicit checklist."
+    }));
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 2_000,
+        max_retries: 0,
+        tool_mode: "read_only"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-provider-output",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Improve runtime guardrails and preserve API behavior.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Include regression tests." }]
+      }
+    });
+
+    expect(output.enhanced_prompt).toBe("Provider-generated plan with explicit checklist.");
+    expect(generate).toHaveBeenCalledTimes(1);
+    const providerInput = generate.mock.calls[0]?.[0] as {
+      tool_mode?: string;
+      intent?: string;
+      style_requested?: string;
+      style_resolved?: string;
+    } | undefined;
+    expect(providerInput?.tool_mode).toBe("read_only");
+    expect(providerInput?.intent).toBeDefined();
+    expect(providerInput?.style_requested).toBe("standard");
+    expect(providerInput?.style_resolved).toBe("standard");
+  });
+
+  it("resolves style=auto to deep for high-risk requests", async () => {
+    const generate = vi.fn(async (_input: unknown) => ({
+      enhanced_prompt: "Provider-generated deep plan."
+    }));
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 2_000,
+        max_retries: 0,
+        tool_mode: "read_only"
+      }
+    });
+
+    await core.enhancePrompt({
+      trace_id: "trc-provider-style-auto",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Harden tenant authorization boundaries and preserve compatibility",
+        style: "auto",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Add comprehensive regression tests." }]
+      }
+    });
+
+    const providerInput = generate.mock.calls[0]?.[0] as { style_requested?: string; style_resolved?: string } | undefined;
+    expect(providerInput?.style_requested).toBe("auto");
+    expect(providerInput?.style_resolved).toBe("deep");
+  });
+
+  it("returns provider output without synthetic fallback rewriting", async () => {
+    const generate = vi.fn(async () => ({
+      enhanced_prompt: [
+        "**Goal:**",
+        "Harden tenant authorization and keep behavior stable.",
+        "",
+        "**Deliverables:**",
+        "1. Comprehensive regression test suite with documentation.",
+        "2. Security review of changes and integration testing in staging environment.",
+        "",
+        "**Likely Files/Areas to Modify:**",
+        "- auth/, middleware/, guards/, context/, handlers/"
+      ].join("\n")
+    }));
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 2_000,
+        max_retries: 0,
+        tool_mode: "none"
+      }
+    });
+    vi.spyOn(core, "searchContext").mockResolvedValue({
+      trace_id: "trc-provider-generic",
+      results: [
+        {
+          path: "src/auth/tenant-guard.ts",
+          start_line: 12,
+          end_line: 44,
+          snippet: "export function assertTenantAccess(ctx) { /* ... */ }",
+          score: 0.97,
+          reason: "exact symbol match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 8,
+        retrieval_mode: "hybrid",
+        index_version: "idx-provider-generic"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-provider-generic",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Harden tenant authorization and keep behavior stable",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "Add regression tests for auth boundaries" }]
+      }
+    });
+
+    expect(output.enhanced_prompt).toContain("Deliverables");
+    expect(output.enhanced_prompt).not.toContain("Codebase anchors");
+  });
+
+  it("retries enhancer provider and then fails with upstream error when attempts are exhausted", async () => {
+    const generate = vi.fn(async (_input: unknown) => {
+      throw new Error("provider unavailable");
+    });
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 1_000,
+        max_retries: 1,
+        tool_mode: "none"
+      }
+    });
+
+    await expect(
+      core.enhancePrompt({
+        trace_id: "trc-provider-retry-fail",
+        tenant_id: "tenant-dev",
+        workspace_id: "ws-dev",
+        request: {
+          prompt: "Tighten workspace checks and keep behavior stable.",
+          project_root_path: "/workspace/dev",
+          conversation_history: [{ role: "user", content: "No contract changes." }]
+        }
+      })
+    ).rejects.toThrow(/enhancer provider failed after retries/i);
+    expect(generate).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not retry enhancer provider when attempt times out", async () => {
+    const generate = vi.fn(async (input: unknown) => {
+      const signal = (input as { abort_signal?: AbortSignal }).abort_signal;
+      await new Promise<void>((resolve, reject) => {
+        signal?.addEventListener(
+          "abort",
+          () => {
+            reject(new Error("aborted_by_timeout"));
+          },
+          { once: true }
+        );
+      });
+      return { enhanced_prompt: "unreachable" };
+    });
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 30,
+        max_retries: 4,
+        tool_mode: "none"
+      }
+    });
+
+    await expect(
+      core.enhancePrompt({
+        trace_id: "trc-provider-timeout-no-retry",
+        tenant_id: "tenant-dev",
+        workspace_id: "ws-dev",
+        request: {
+          prompt: "Tighten workspace checks and keep behavior stable.",
+          project_root_path: "/workspace/dev",
+          conversation_history: [{ role: "user", content: "No contract changes." }]
+        }
+      })
+    ).rejects.toThrow(/timeout_after_30ms/i);
+    expect(generate).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps enhancer request alive when provider emits progress heartbeats", async () => {
+    const generate = vi.fn(async (input: unknown) => {
+      const onProgress = (input as { on_progress?: () => void }).on_progress;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      onProgress?.();
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      onProgress?.();
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      return { enhanced_prompt: "heartbeat-kept-alive" };
+    });
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 40,
+        max_retries: 0,
+        tool_mode: "none"
+      }
+    });
+
+    const output = await core.enhancePrompt({
+      trace_id: "trc-provider-heartbeat",
+      tenant_id: "tenant-dev",
+      workspace_id: "ws-dev",
+      request: {
+        prompt: "Tighten workspace checks and keep behavior stable.",
+        project_root_path: "/workspace/dev",
+        conversation_history: [{ role: "user", content: "No contract changes." }]
+      }
+    });
+    expect(output.enhanced_prompt).toBe("heartbeat-kept-alive");
+    expect(generate).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not retry enhancer provider when response shape is invalid", async () => {
+    const generate = vi.fn(async () => ({
+      enhanced_prompt: ""
+    }));
+    const core = new RetrievalCore(new InMemoryIndexStore(), new InMemoryQueryCache(), {
+      enhancerProvider: {
+        generate,
+        describe: () => ({ provider: "test_enhancer", model: "stub-v1" })
+      },
+      enhancerGenerationConfig: {
+        timeout_ms: 500,
+        max_retries: 3,
+        tool_mode: "none"
+      }
+    });
+
+    await expect(
+      core.enhancePrompt({
+        trace_id: "trc-invalid-response-no-retry",
+        tenant_id: "tenant-dev",
+        workspace_id: "ws-dev",
+        request: {
+          prompt: "Harden tenant authorization and keep behavior stable",
+          project_root_path: "/workspace/dev",
+          conversation_history: [{ role: "user", content: "Add regression tests." }]
+        }
+      })
+    ).rejects.toThrow(/empty enhanced_prompt/i);
+    expect(generate).toHaveBeenCalledTimes(1);
+  });
+});