improvement(knowledge): cache admitted usage checks on the search path

[waleedlatif1]

Summary

• Every knowledge search ran checkAttributedUsageLimits, which sums the payer's usage_log rows for the whole billing period. For a large organization that is a scan of over a million rows per search, usage_admission sat at a median of ~378ms per search, and the sum is one of the top database consumers overall
• Knowledge search (including org-wide Sim Search) now calls checkSearchUsageLimits, which serves a cached admission for up to 60s and always re-reads a refusal. Staleness only fails open: a payer who crosses their limit can keep searching for at most a minute, and a payer who raises their limit or upgrades is never held behind a cached block
• The search path never stores a refusal, so a fail-closed ledger error (which comes back as exceeded) can't be cached from search, and a refusal read by search never reaches ingestion. A read that throws writes nothing. coalesceLocally collapses concurrent misses and bounds a hung read at its settle deadline; the cache is an LRUCache capped at 10k entries
• Merged the existing ingestion gate into the same module (ingestion-usage-gate.ts → usage-gate-cache.ts): one key, one LRU, one coalescer, two entry points. checkIngestionUsageLimits behaves as before (serves cached refusals too); search serves only cached admissions, so it never sees a refusal ingestion cached
• The key now also includes the payer subscription (id, plan, status, seats), so a plan change reads fresh on both paths. It still excludes workspaceId, which the check never reads, so every workspace of one payer shares an entry
• Workflow execution admission, uploads, v1 /api/v1/knowledge/search (its own inline gate, not the search use case), and every other caller keep the fresh read. No invalidator: usage and limit changes land in other processes, so the TTL is the real bound

Type of Change

• Improvement

Testing

• New cases for the search entry point: reuse across workspaces, refusal re-read, never serving an ingestion-cached refusal, never storing a refusal for ingestion, failed read not cached. Verified they fail with the refusal guard removed
• Knowledge, billing, internal, and MCP suites pass (600 files / 7,187 tests); type-check, lint, check:audits (47), and check:api-validation pass

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 18, 2026 10:56pm UTC

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the bounded stale-admission behavior is intentional, billed, and isolated from cached refusals on the interactive search path.

Summary

This PR adds a shared, bounded usage-gate cache for high-frequency knowledge search and ingestion checks. Search reuses only successful admissions, while ingestion can reuse both admissions and refusals.

• Adds a 60-second, 10,000-entry LRU cache keyed by payer, billing period and source, actor, and subscription state.
• Coalesces concurrent ledger reads through the existing local singleflight utility.
• Keeps search refusals uncached and forces them to be re-read.
• Migrates document ingestion to the shared cache module and expands cross-path cache tests.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Knowledge search] --> B[checkSearchUsageLimits]
  C[Document ingestion] --> D[checkIngestionUsageLimits]
  B --> E{Acceptable cached entry?}
  D --> E
  E -->|Yes| F[Return cached result]
  E -->|No| G[Coalesce concurrent ledger read]
  G --> H[checkAttributedUsageLimits]
  H --> I{Exceeded?}
  I -->|No| J[Cache admission for 60 seconds]
  I -->|Yes, ingestion| K[Cache refusal for 60 seconds]
  I -->|Yes, search| L[Return refusal without caching]

Loading

_{Reviews (3) · Last reviewed commit: "fix(knowledge): key the usage gate cache..."}

[cubic-dev-ai]

All reported issues were addressed across 9 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[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]

All reported issues were addressed across 9 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[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 9 files

Confidence score: 5/5

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

_{Re-trigger cubic}