From 3b7e06502405d5136d990fa586d31370efbfddeb Mon Sep 17 00:00:00 2001
From: woodenriver05 <woodenriver@gmail.com>
Date: Mon, 11 May 2026 20:25:34 -1000
Subject: [PATCH] fix: forward candidateLimit through search APIs

---
 src/index.ts      |  4 ++++
 src/mcp/server.ts |  2 ++
 test/sdk.test.ts  | 14 ++++++++++++++
 3 files changed, 20 insertions(+)

diff --git a/src/index.ts b/src/index.ts
index 3de13a5..e8e2a45 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -159,6 +159,8 @@ export interface SearchOptions {
   collections?: string[];
   /** Max results (default: 10) */
   limit?: number;
+  /** Max candidates to rerank (default: 40) */
+  candidateLimit?: number;
   /** Minimum score threshold */
   minScore?: number;
   /** Include explain traces */
@@ -402,6 +404,7 @@ export async function createStore(options: StoreOptions): Promise<QMDStore> {
           minScore: opts.minScore,
           explain: opts.explain,
           intent: opts.intent,
+          candidateLimit: opts.candidateLimit,
           skipRerank,
           chunkStrategy: opts.chunkStrategy,
         });
@@ -414,6 +417,7 @@ export async function createStore(options: StoreOptions): Promise<QMDStore> {
         minScore: opts.minScore,
         explain: opts.explain,
         intent: opts.intent,
+        candidateLimit: opts.candidateLimit,
         skipRerank,
         chunkStrategy: opts.chunkStrategy,
       });
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 2f5482f..1bd7d0d 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -331,6 +331,7 @@ Intent-aware lex (C++ performance, not sports):
         collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
         limit,
         minScore,
+        candidateLimit,
         rerank,
         intent,
       });
@@ -692,6 +693,7 @@ export async function startMcpHttpServer(
           collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
           limit: params.limit ?? 10,
           minScore: params.minScore ?? 0,
+          candidateLimit: params.candidateLimit,
           intent: params.intent,
           rerank: params.rerank,
         });
diff --git a/test/sdk.test.ts b/test/sdk.test.ts
index b60e9e7..53764c5 100644
--- a/test/sdk.test.ts
+++ b/test/sdk.test.ts
@@ -614,6 +614,20 @@ describe("search (unified API)", () => {
     expect(results.length).toBeGreaterThan(0);
   });
 
+  test("search() forwards candidateLimit to structured search", async () => {
+    const results = await store.search({
+      queries: [
+        { type: "lex", query: "authentication" },
+        { type: "lex", query: "meeting" },
+      ],
+      limit: 5,
+      candidateLimit: 1,
+      rerank: false,
+    });
+
+    expect(results).toHaveLength(1);
+  });
+
   // Tests below use search({ query: ... }) which triggers LLM query expansion
   describe.skipIf(!!process.env.CI)("with LLM query expansion", () => {
     test("search() with query and rerank:false returns results", async () => {