improvement(knowledge): remember a caller's saturated search reach

[waleedlatif1]

Summary

• A caller whose tokens reach past the permitted-set limit re-ran the reach count on every search, only to learn again that the set is unbounded. That count was ~200ms of server time per search for a broad member on a production-sized copy
• The saturated answer is now remembered per bases and token set for 5 minutes (bounded LRUCache, token set hashed)
• probeVisibleDocuments returns documents | saturated | timed_out instead of null for both of the latter, so a probe that ran out of time is never mistaken for a broad caller
• Safe when stale: an unbounded set only means both legs apply the full access predicate per candidate, so a cached answer can cost speed, never access

Type of Change

• Improvement

Testing

• New tests: saturation is remembered and skips the probe, is keyed by bases and token set, and is never inferred from a bounded set or a timed-out probe; each fails when the cache write is removed or widened to timeouts
• lib/knowledge/search suite (185 passing), type-check, bun run lint, check:audits

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
docs	Skipped		Sep 19, 2026 7:01am UTC

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no outstanding correctness, security, or repository-rule issues identified.

Summary

This PR avoids repeatedly probing broad callers whose permitted-document reach has already saturated:

• Distinguishes bounded document results, saturation, and probe timeouts with explicit outcomes.
• Caches saturation for five minutes using a bounded LRU keyed by sorted knowledge-base IDs and a hash of sorted user tokens.
• Preserves the full access predicate when using the cached unbounded path.
• Adds tests covering cache reuse, key isolation, bounded results, and timeouts.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Resolve permitted documents] --> B{Cached saturation for bases and token set?}
  B -->|Yes| C[Return unbounded]
  B -->|No| D[Probe visible documents]
  D --> E{Probe outcome}
  E -->|Documents| F[Return bounded document set]
  E -->|Saturated| G[Cache saturation for five minutes]
  G --> C
  E -->|Timed out| C

Loading

_{Reviews (2) · Last reviewed commit: "improvement(knowledge): keep the permitt..."}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}