improvement(knowledge): rank the vector page on the projection and admit searches in parallel

[waleedlatif1]

Summary

• A search nobody had run before took seconds even with the vector graph in cache, while a repeat took under 200 ms. The difference was the rerank: the walk ranked 1,600 candidates on the projection's stored halfvec, then rescored every one of them against the original vector, which lives out of line in toast storage no cache holds. That read one random page per candidate on every novel query (3.1 s cold on a production-shaped copy, 31 ms warm). Both hydration queries did the same for each result, and the keyword one also re-matched the text-search vector per row.
• The page is now the walk's own order. The walk gathers a pool sized to the pages asked for (200 for the first page, doubling when a page outruns it, capped at 1,600) instead of a rerank's 1,600, so it also ends far sooner; a denied source is excluded where the pool is built. vector.rerank becomes vector.page, which reads only the slice's identities; the full read predicate follows at hydration as before. Hydration scores results on the projection for both legs, and keyword hydration no longer re-matches the query. On 12 queries against a production-shaped copy the projection's order keeps the top result every time and 18.7 of the full-vector top 20.
• A filled projection decides readability on the row alone: the Tin window's acl IS NULL AND EXISTS (document …) fallback is omitted once the keyword projection is filled, the same gate the vector walk already used.
• The organization gate, billing attribution and usage admission ran serially ahead of the embedding call although none depends on the query; they now run beside it, with the tag definitions. A refusal still ends the search before retrieval. Access availability is resolved once per owner per minute instead of three times per search, the usage gate holds for five minutes, and the overage check and activity record no longer hold the response.
• Measured on staging (server critical path p50, common/medium/rare): 106/121/110 ms → 63/20/8 ms; every query complete.

Type of Change

• Improvement

Testing

• Unit tests updated for the page statement and added for the page-sized pool, projection-scored hydration, tsquery-free keyword hydration, the fill-gated Tin predicate, and the availability memo; each new assertion was checked against a reverted implementation.
• Integration recall checks now compare the page against exact ranking on the projection.
• bun run lint, check:audits, docs-manifest:check, block-registry audit, type-check pass; 4,165 tests pass across knowledge, search route and billing.

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 4:47am UTC

[cubic-dev-ai]

All reported issues were addressed across 12 files

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

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

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; all previous findings are resolved in the current code and the latest changes introduce no actionable regression.

Summary

This PR reduces knowledge-search latency by using projection-walk order directly, sizing vector candidate pools according to requested pages, scoring hydration from stored projection vectors, and avoiding redundant keyword matching. It also parallelizes independent pre-search reads while retaining admission before model execution, memoizes access availability, and extends usage-gate caching.

• Authorization remains applied during candidate selection and hydration, including fallback to document ACL data while projection backfills are incomplete.
• Vector pagination now advances by consumed pool entries, skips deleted-identity slices, and treats the capped pool as exhausted.
• Admission completes before embedding generation, while durable billing and organization-activity effects remain awaited.
• The only changes since the previous review strengthen the unfilled-projection exclusion test and add a semantically neutral SQL marker used by that test.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Search request] --> B[Parallel access, defaults, admission, and tag reads]
    B --> C{Admission accepted?}
    C -- No --> D[Reject before embedding]
    C -- Yes --> E[Generate query embedding]
    E --> F[Build bounded projection candidate pool]
    F --> G[Exclude denied sources]
    G --> H[Read identities in projection-walk order]
    H --> I[Apply full read predicate and hydrate]
    I --> J[Return ranked results]

Loading

_{Reviews (4) · Last reviewed commit: "improvement(knowledge): mark the exclude..."}

[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 12 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.

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

Confidence score: 5/5

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

_{Re-trigger cubic}