fix(knowledge): treat a reach of nothing as a bounded set of nothing

A member who reads no document in the bases, such as one with no source of their own yet, resolved as an unbounded reach: the vector leg then scanned the sliced sources for readable rows it could not find until its deadline, and the keyword leg ranked every match to the same end, so a search that could return nothing spent every budget it had. A counted reach of zero is now a bounded empty set, remembered like any reach, and both legs answer at once. An index the planner has no rows for keeps its old answer, since a bound of zero looks at nothing.

Author: waleedlatif1

apps/sim/lib/knowledge/search/queries.test.ts

@@ -2051,6 +2051,67 @@ describe('permitted-document planner', () => {
       expect(reachCounts()).toHaveLength(2)
     })
 
+    it('reports a caller who reaches nothing as a bounded set of nothing, and remembers it', async () => {
+      dbChainMockFns.execute.mockImplementation(async (query) => {
+        const statement = render(query).sql
+        if (statement.includes('EXPLAIN'))
+          return [{ 'QUERY PLAN': [{ Plan: { 'Plan Rows': 1_000_000 } }] }]
+        if (statement.includes(') reached')) return [{ n: 0 }]
+        return []
+      })
+      const reachCounts = () => statements().filter((query) => query.sql.includes(') reached'))
+      const plan = {
+        connectors: { workspace: [], admin: [], members: [], liveProofRequired: [] },
+        observers: { confirmed: [], observed: [] },
+        memberSources: [],
+        connectorTypes: new Map(),
+        uploads: true,
+      }
+      const budget = () => new SearchBudget('vector', performance.now() + 10_000)
+      await expect(
+        resolveReach(['org-index'], scope('reaches-nothing'), budget(), plan)
+      ).resolves.toEqual({ kind: 'bounded', documents: [] })
+      expect(reachCounts()).toHaveLength(1)
+      /** Remembered like any reach: the next search neither counts nor probes. */
+      await expect(
+        resolveReach(['org-index'], scope('reaches-nothing'), budget(), plan)
+      ).resolves.toEqual({ kind: 'bounded', documents: [] })
+      await expect(
+        resolvePermittedDocuments({
+          knowledgeBaseIds: ['org-index'],
+          access: scope('reaches-nothing'),
+          budget: budget(),
+          accessPlan: plan,
+        })
+      ).resolves.toEqual({ kind: 'bounded', documents: [] })
+      expect(reachCounts()).toHaveLength(1)
+      expect(probes()).toBe(0)
+    })
+
+    it('does not read an unanalyzed index as a reach of nothing', async () => {
+      /** The planner knows no rows yet, so the bound is zero and the count looked at nothing. */
+      dbChainMockFns.execute.mockImplementation(async (query) => {
+        const statement = render(query).sql
+        if (statement.includes('EXPLAIN')) return [{ 'QUERY PLAN': [{ Plan: { 'Plan Rows': 0 } }] }]
+        if (statement.includes(') reached')) return [{ n: 0 }]
+        return []
+      })
+      await expect(
+        resolveReach(
+          ['org-index'],
+          scope('unanalyzed'),
+          new SearchBudget('vector', performance.now() + 10_000),
+          {
+            connectors: { workspace: [], admin: [], members: [], liveProofRequired: [] },
+            observers: { confirmed: [], observed: [] },
+            memberSources: [],
+            connectorTypes: new Map(),
+            uploads: true,
+          }
+        )
+      ).resolves.toEqual({ kind: 'unbounded', broad: true })
+    })
+
     it('reports a leg whose own deadline passed during the count as short, not failed', async () => {
       const budget = new SearchBudget('vector', performance.now() - 1)
       await expect(

apps/sim/lib/knowledge/search/queries.ts

@@ -1184,8 +1184,16 @@ export const BROAD_REACH_SHARE = 0.25
  */
 const SATURATED_REACH_TTL_MS = 5 * 60 * 1000
 
-/** A saturated reach, and whether it is broad enough to walk the whole graph for. */
-const saturatedReach = new LRUCache<string, { broad: boolean }>({
+/**
+ * A counted reach: whether it is broad enough to walk the whole graph for, or empty, in which
+ * case the caller reads nothing in these bases and no leg has anything to rank.
+ */
+interface RememberedReach {
+  broad: boolean
+  empty: boolean
+}
+
+const saturatedReach = new LRUCache<string, RememberedReach>({
   max: 10_000,
   ttl: SATURATED_REACH_TTL_MS,
 })
@@ -1249,32 +1257,33 @@ async function estimateFilteredDocuments(
 }
 
 /**
- * Whether a reach is broad: the caller reaches at least {@link BROAD_REACH_SHARE} of the bases'
- * documents. Counted once against that bound and remembered, so the first search after the
- * window pays for it and the rest do not. A caller whose probe already saturated is known to
- * reach past the probe's limit, so a bound inside that limit is met without counting.
+ * How far a caller reaches: broad when they reach at least {@link BROAD_REACH_SHARE} of the
+ * bases' documents, empty when they reach none. Counted once against that bound and remembered,
+ * so the first search after the window pays for it and the rest do not. A caller whose probe
+ * already saturated is known to reach past the probe's limit, so a bound inside that limit is
+ * met without counting.
  *
  * The count reads as many index entries as the caller reaches, so on a large index it can cost
  * more than the leg it serves; it gets the probe's share of the deadline, never the whole leg's.
  * A count that runs out of that share answers `null`: the leg keeps its time and its deadline
  * intact, and the caller decides this search alone without remembering anything.
  */
-async function reachIsBroad(
+async function countReach(
   knowledgeBaseIds: string[],
   access: KnowledgeAccessScope,
   budget: SearchBudget | undefined,
   plan: SearchAccessPlan | undefined,
   saturated: boolean
-): Promise<boolean | null> {
-  if (access.kind !== 'user') return true
+): Promise<RememberedReach | null> {
+  if (access.kind !== 'user') return { broad: true, empty: false }
   const countBudget = budget?.capped(VECTOR_PROBE_BUDGET_MS)
   try {
     const total =
       (await indexDocumentCounts.fetch([...knowledgeBaseIds].sort().join(','), {
         context: countBudget,
       })) ?? 0
     const bound = Math.ceil(total * BROAD_REACH_SHARE)
-    if (saturated && bound <= VECTOR_PROBE_DOCUMENT_LIMIT) return true
+    if (saturated && bound <= VECTOR_PROBE_DOCUMENT_LIMIT) return { broad: true, empty: false }
     const [row] = await runSearchQuery(countBudget, 'permitted_documents', (executor) =>
       executor.execute<{ n: number }>(sql`
         SELECT count(*) AS n FROM (
@@ -1288,7 +1297,9 @@ async function reachIsBroad(
           LIMIT ${bound}
         ) reached`)
     )
-    return Number(row?.n ?? 0) >= bound
+    const reached = Number(row?.n ?? 0)
+    /** A count that looked and found nothing: only a bound of zero looks at nothing. */
+    return { broad: reached >= bound, empty: bound > 0 && reached === 0 }
   } catch (error) {
     if (!budget || !countBudget?.isTimeout(error)) throw error
     /** Only the count's share was spent; the leg's own deadline still governs. */
@@ -1343,20 +1354,31 @@ export async function resolveReach(
 ): Promise<PermittedDocuments> {
   const key = reachKey(knowledgeBaseIds, access, plan)
   const remembered = key ? saturatedReach.get(key) : undefined
-  if (remembered) return { kind: 'unbounded', broad: remembered.broad }
+  if (remembered) return permittedFromReach(remembered)
   try {
-    const broad = await reachIsBroad(knowledgeBaseIds, access, budget, plan, false)
+    const reach = await countReach(knowledgeBaseIds, access, budget, plan, false)
     /** A count that ran out of time decides this search only; the next one counts again. */
-    if (broad === null) return { kind: 'unbounded', broad: true }
-    if (key) saturatedReach.set(key, { broad })
-    return { kind: 'unbounded', broad }
+    if (reach === null) return { kind: 'unbounded', broad: true }
+    if (key) saturatedReach.set(key, reach)
+    return permittedFromReach(reach)
   } catch (error) {
     /** The leg's own deadline passed during the count: the leg is short, the search is not failed. */
     if (!budget?.isTimeout(error)) throw error
     return { kind: 'unbounded', broad: true }
   }
 }
 
+/**
+ * A reach of nothing is a bounded set of nothing: a caller who reads no document in these bases,
+ * such as a member with no source of their own yet, has nothing for any leg to rank, where an
+ * unbounded set would have each leg scan for rows it cannot find.
+ */
+function permittedFromReach(reach: RememberedReach): PermittedDocuments {
+  return reach.empty
+    ? { kind: 'bounded', documents: [] }
+    : { kind: 'unbounded', broad: reach.broad }
+}
+
 /**
  * Resolve the permitted set with the candidate predicate both legs apply, so restricting a leg
  * to it never admits a document the leg would otherwise refuse. Tag filters stay chunk-level in
@@ -1384,6 +1406,10 @@ export async function resolvePermittedDocuments(params: {
     params.accessPlan && (dateFilterCondition(params.filters) || params.filters?.source)
   )
   const remembered = key && !filteredDirectly ? saturatedReach.get(key) : undefined
+  if (remembered?.empty) {
+    annotateSearchDiagnostics({ permittedDocuments: 'bounded', permittedDocumentCount: 0 })
+    return { kind: 'bounded', documents: [] }
+  }
   if (remembered) {
     probe = { kind: 'saturated' }
     broad = remembered.broad
@@ -1408,17 +1434,17 @@ export async function resolvePermittedDocuments(params: {
     }
     if (probe.kind === 'saturated') {
       try {
-        const counted = await reachIsBroad(
+        const reach = await countReach(
           params.knowledgeBaseIds,
           params.access,
           params.budget,
           params.accessPlan,
           true
         )
         /** A count that ran out of time decides this search only; the next one counts again. */
-        if (counted !== null) {
-          broad = counted
-          if (key) saturatedReach.set(key, { broad })
+        if (reach !== null) {
+          broad = reach.broad
+          if (key) saturatedReach.set(key, reach)
         }
       } catch (error) {
         /** The leg's own deadline passed during the count: the leg is short, the search is not failed. */