fix(copilot): make the search_docs topK clamp type-safe and test it

The clamp guarded magnitude but not type: Math.min/Math.max propagate NaN,
so a non-numeric topK reached the query as `.limit(NaN)`. The `?? DEFAULT`
only caught undefined. Nothing enforced this but the generated Ajv schema,
and searchDocs is also called directly, so it should not depend on that.

Extract clampTopK, which falls back to the default for anything non-finite
(NaN, Infinity, a string that slipped through) and clamps the rest to
[1, 25].

The clamp was completely untested because the db mock's .limit() stub
discarded its argument — the mock now records it. Covers default, cap,
floor, truncation, and the non-finite fallback. Worth pinning: staging's
search_documentation documented "max 10" and enforced nothing, so this
bound is new behavior, not just a bigger number.

Author: j15z

apps/sim/lib/copilot/docs/docs-search.test.ts

@@ -3,9 +3,10 @@
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-const { mockGenerateSearchEmbedding, capturedWhere, mockRows } = vi.hoisted(() => ({
+const { mockGenerateSearchEmbedding, capturedWhere, capturedLimit, mockRows } = vi.hoisted(() => ({
   mockGenerateSearchEmbedding: vi.fn(),
   capturedWhere: { value: undefined as unknown },
+  capturedLimit: { value: undefined as number | undefined },
   mockRows: { value: [] as unknown[] },
 }))
 
@@ -38,7 +39,12 @@ vi.mock('@sim/db', () => ({
         where: (condition: unknown) => {
           capturedWhere.value = condition
           return {
-            orderBy: () => ({ limit: async () => mockRows.value }),
+            orderBy: () => ({
+              limit: async (n: number) => {
+                capturedLimit.value = n
+                return mockRows.value
+              },
+            }),
           }
         },
       }),
@@ -227,3 +233,43 @@ describe('searchDocs shortfall reporting', () => {
     expect(outcome.results).toHaveLength(1)
   })
 })
+
+describe('searchDocs topK clamping', () => {
+  beforeEach(() => {
+    capturedLimit.value = undefined
+    mockRows.value = []
+    mockGenerateSearchEmbedding.mockResolvedValue({ embedding: [0.1, 0.2] })
+  })
+
+  it('defaults to 10 when unspecified', async () => {
+    await searchDocs('cron')
+    expect(capturedLimit.value).toBe(10)
+  })
+
+  it('caps at 25 — the documented max, which the old tool never enforced', async () => {
+    await searchDocs('cron', { topK: 500 })
+    expect(capturedLimit.value).toBe(25)
+  })
+
+  it('floors at 1', async () => {
+    await searchDocs('cron', { topK: 0 })
+    expect(capturedLimit.value).toBe(1)
+    await searchDocs('cron', { topK: -8 })
+    expect(capturedLimit.value).toBe(1)
+  })
+
+  it('truncates a fractional count', async () => {
+    await searchDocs('cron', { topK: 7.9 })
+    expect(capturedLimit.value).toBe(7)
+  })
+
+  it('falls back to the default rather than passing NaN to the query', async () => {
+    // Math.min/Math.max propagate NaN, so a bare clamp would reach `.limit(NaN)`.
+    await searchDocs('cron', { topK: Number.NaN })
+    expect(capturedLimit.value).toBe(10)
+    await searchDocs('cron', { topK: 'twelve' as unknown as number })
+    expect(capturedLimit.value).toBe(10)
+    await searchDocs('cron', { topK: Number.POSITIVE_INFINITY })
+    expect(capturedLimit.value).toBe(10)
+  })
+})

apps/sim/lib/copilot/docs/docs-search.ts

@@ -108,6 +108,19 @@ function escapeLikePattern(value: string): string {
   return value.replace(/[\\%_]/g, (char) => `\\${char}`)
 }
 
+/**
+ * Clamp a caller-supplied result count into [1, {@link MAX_TOP_K}].
+ *
+ * Guards magnitude AND type: `Math.min`/`Math.max` propagate NaN, so a
+ * non-numeric value would otherwise reach the query as `.limit(NaN)`. The
+ * generated tool schema rejects a non-number upstream today, but this function
+ * is also called directly, so it does not rely on that.
+ */
+function clampTopK(requested: number | undefined): number {
+  if (requested === undefined || !Number.isFinite(requested)) return DEFAULT_TOP_K
+  return Math.min(Math.max(Math.trunc(requested), 1), MAX_TOP_K)
+}
+
 /**
  * Semantic search over the indexed docs corpus (`docs_embeddings`, rebuilt by
  * `scripts/process-docs.ts` on release). Every result carries the `docs/` path
@@ -128,7 +141,7 @@ export async function searchDocs(
 ): Promise<DocsSearchOutcome> {
   if (!query || typeof query !== 'string') throw new Error('query is required')
 
-  const topK = Math.min(Math.max(Math.trunc(options?.topK ?? DEFAULT_TOP_K), 1), MAX_TOP_K)
+  const topK = clampTopK(options?.topK)
   const where = scopeCondition(options?.path)
 
   logger.info('Executing docs search', { query, topK, path: options?.path ?? null })