fix(knowledge): recover vector candidates an HNSW post-filter discards

[waleedlatif1]

Why

pgvector's HNSW index post-filters by construction. hnswgettuple never reads the scan
keys hnswrescan writes, the access method declares no scan strategies, and there is no
amgetbitmap — so a visibility predicate cannot narrow the graph walk. It can only discard
neighbours the walk has already committed to. When the documents a caller may read are a
small share of the index, the traversal returns a handful of candidates instead of its limit,
and the leg hands back almost nothing.

Two settings made that worse. hnsw.max_scan_tuples excludes the initial beam, so pairing a
1,000-wide ef_search with a 1,000-tuple budget spent the whole budget inside the first beam:
ResumeScanItems never ran and the iterative scan never iterated. And a beam is uninterruptible
— pgvector calls CHECK_FOR_INTERRUPTS only in its index-build paths, never in hnswgettuple
— so a wide beam is also the leg's cancellation floor.

The probe in front of the traversal had its own problem: it scanned documents until it had
accumulated a fixed number of chunks. A search index holds only a few chunks per document,
so that bound let it evaluate the access predicate across many times more documents than its
limit suggested, with no deadline of its own.

What changed

1. An exact ranking rescues an underfilled traversal. A traversal that fills its candidate
   limit is already the nearest permitted chunks and is returned untouched — nothing else runs,
   so a scope the graph serves well pays nothing. Only when it comes back short does the leg
   probe how many documents the caller may read, and rank exactly when that set is small enough
   to afford. The exact scan is keyed by the probed document identities, so it reads through
   embedding_search_document_lookup_idx and costs what the permitted set costs rather than
   re-deriving permission across the index. It also honours statement_timeout, which a
   traversal cannot.

2. The probe is bounded by documents examined and has its own sub-budget. Reaching either
   bound means an exact ranking is not worth attempting — a decision, not a failure — so the
   traversal's own candidates stand and the leg's deadline is untouched. The bound is derived
   from the narrowest live vector budget and the measured per-document cost, not picked.

3. Retuned the scan settings: ef_search 1000 → 200, max_scan_tuples 1000 → 20000. The
   tuple budget now sits an order of magnitude above the beam, which is what lets the iterative
   scan iterate at all (pgvector#912), and the narrower beam lowers the uninterruptible floor.

Measured

On a local reproduction built to match the search index's shape — chunk and document counts,
knowledge-base size skew, chunks per document, index parameters and server settings — and run
under matching cache pressure (working set ~14x shared_buffers). Candidate-stage wall clock and
candidates returned; the retrieval budget for the narrowest surface is 3,000 ms.

scope	before	after
org index, caller sees 67% of docs, query off-beam	123 ms, 1600	29 ms, 1600
org index, sees 27%, off-beam	70 ms, 1600	40 ms, 1600
org index, sees 6.7%, off-beam	55 ms, 2	637 ms, 1600
org index, sees 1.6%, off-beam	39 ms, 1	363 ms, 1600
org index, sees nothing	43 ms, 0	273 ms, 0
org index, sees 6.7%, on-beam	57 ms, 1600	46 ms, 1600
workspace KB, 0.5% of index	61 ms, 1600	20 ms, 1600
workspace KB, 4.7% of index	57 ms, 7	424 ms, 1600
workspace KB, 8.4% of index	56 ms, 0	559 ms, 1600

Every case where the traversal fills is faster after, with identical recall — workspace-scoped
search, which was healthy, is strictly better. Every case where it came back short now returns a
full candidate set, for a fraction of the budget. Two workspace-scoped cases turn out to have
been quietly broken too: a knowledge base that is a small share of the shared index collapses
for the same reason an organization index does.

The one axis that is worse: a caller who may read nothing costs ~230 ms more, because the
retuned scan works harder before concluding there is nothing to find and the probe then confirms
it. Both paths return nothing either way, it is bounded, and it buys the recall above.

Cancellation, same reproduction: the exact scan and the probe honour statement_timeout within
1.0–2.4x. The retuned traversal is cancelled at every timeout tested; the previous settings ran
a single beam straight through a 50 ms timeout without yielding.

Plan shape of the rescue is a bounded parallel top-N heapsort at every permitted-set size tested,
with no correlated subquery in it — it does not depend on the planner's estimate for one.

Tests

vector.probe timing out no longer fails the leg, so it moved out of the shared partial-retrieval
case and into its own test. New tests cover the rescue firing, not firing on a filled traversal,
declining past the probe bound, and the max_scan_tuples / ef_search relationship. Each was
verified to fail when the corresponding change is reverted.

Type of Change

• Bug fix

Testing

lib/knowledge + app/api/knowledge suites pass (3,117 tests). Each new test was verified to fail when its change is reverted. bun run lint, check:audits (46 audits), docs-manifest:check, block-registry check and type-check all pass. No schema or migration changes.

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 9:02am UTC

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

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previously reported disabled-chunk probe inflation is fixed and no new actionable failure remains.

Summary

The PR improves vector-search recall when pgvector’s HNSW post-filter underfills the candidate set.

• Retunes HNSW traversal so iterative scanning can progress with a smaller cancellation floor.
• Adds a document-bounded, separately budgeted visibility probe.
• Exactly ranks tractable permitted document sets before the existing rerank, live-authorization, and hydration stages.
• Requires enabled chunks when structured tags determine whether a document consumes the probe bound.
• Expands diagnostics and tests for rescue, timeout, authorization-refill, and scan-setting behavior.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Start vector retrieval] --> B[Bounded HNSW traversal]
    B --> C{Candidate limit filled?}
    C -- Yes --> G[Rerank bounded candidates]
    C -- No --> D[Probe visible documents<br/>under capped deadline]
    D --> E{Probe tractable and nonempty?}
    E -- Too large or timed out --> G
    E -- Empty --> H[Return no candidates]
    E -- Yes --> F[Exact rank permitted documents]
    F --> G
    G --> I[Verify live source authorization]
    I --> J[Hydrate under full visibility predicate]
    J --> K[Return results]

Loading

_{Reviews (3) · Last reviewed commit: "fix(knowledge): require an enabled chunk..."}

[cubic-dev-ai]

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

Confidence score: 5/5

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

_{Re-trigger cubic}