improvement(knowledge): warm the search projection after its backfill

[waleedlatif1]

Summary

• A bulk pass over the ranking projections (the source/ACL backfill, an index rebuild, a restore) streams every heap page through the cache and pushes the vector graphs out of it. The next searches then read the graph one random page at a time from disk: a walk that takes 10–20 ms warm took 1.5–5.8 s cold, ran past the vector deadline, and returned partial results with the "some results may not be shown" notice until enough searches had paged the graph back in.
• prewarmSearchProjection reads both projections' heaps and their hnsw/tin/gin indexes back into the OS cache with pg_prewarm(…, 'read'), heaps first so the indexes survive when the cache is short. It resolves relations through the search path and skips any relation that fails; warming never fails its caller.
• The backfill calls it once both projections are filled, on its own connection, so the first search after the fill is as fast as the thousandth.
• pg_prewarm is not a trusted extension, so the application role cannot install it and no migration does. Where it is absent the helper logs a warning and does nothing. A superuser installs it once with CREATE EXTENSION pg_prewarm.
• bun apps/sim/scripts/prewarm-search-projection.ts warms on demand after any other bulk operation.

Type of Change

• Improvement

Testing

• Unit tests for the helper (absent extension, catalog order and read mode, per-relation failure, unreadable catalog) and for the backfill hook (runs once on completion before the connection closes, not when a budgeted run returns its cursor). Each new assertion was checked against a broken implementation.
• The operator script run against a local Postgres with pg_prewarm installed reads the heap and every HNSW index and reports pages per relation.
• bun run lint, check:audits, docs-manifest:check, block-registry audit, and type-check 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 21, 2026 3:17am UTC

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no accepted new findings or outstanding previous findings.

Summary

This PR warms the search projection after a completed source/ACL backfill so initial searches do not suffer cold-cache latency.

• Adds best-effort projection discovery and heap/index warming through pg_prewarm.
• Bounds backfill-triggered relation reads with a dedicated prewarm budget.
• Adds an operator script for warming after restores, failovers, and index rebuilds.
• Covers extension absence, catalog failures, per-relation failures, time budgets, and backfill lifecycle behavior with tests.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Run source and ACL backfill] --> B{Backfill completed?}
  B -- No, cursor returned --> C[Close connection without prewarming]
  B -- Yes --> D[Check pg_prewarm extension]
  D --> E[List projection heaps and ranking indexes]
  E --> F[Warm heaps first]
  F --> G[Warm HNSW, TIN, and GIN indexes]
  G --> H[Stop when prewarm budget expires]
  H --> I[Close dedicated connection]

Loading

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

[cubic-dev-ai]

All reported issues were addressed across 5 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 5 files

Confidence score: 5/5

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

_{Re-trigger cubic}