perf(controlplane): page referrer references from an index
Summary
Discovery (ReferrerService/DiscoverPrivate, chainloop discover) was slow, and sometimes timed out, for referrers that many attestations share, such as an identical scanner report. To return one page of references, the control plane read and sorted every reference of the root. In production, one such material has 12.7k references: each page touched about 131k buffers, took 155 ms with a warm cache, about 5 s with a cold one, and hit the request deadline in the worst cases.
This change reads a page of references directly in page order, from the references of the caller's organizations only:
- The
referencesedge ofReferrerbecomes an Ent edge schema (ReferrerReference) on the existingreferrer_referencestable. The table gets two columns and an index on(referrer_id, organization_id, created_at DESC, referred_by_id DESC):created_atcopies the creation time of the referenced referrer, which is the page order.organization_idis the organization of the attestation whose ingestion stored the reference.
- A page reads one index range per caller organization, plus the range of references with no organization, each in page order, and merges them. Visibility and project filters are still checked per row with a correlated
EXISTS, and each range stops when the page is full. So the cost no longer grows with the number of references of the root, or with the share of them stored in other organizations. Order and cursor semantics stay the same. - A reference stored again by an attestation in another organization, for example the same attestation pushed to a run in another organization, loses its organization. A reference with no organization is read in every organization, so the column never hides a reference that the caller can see through that attestation. An organization is only ever replaced with NULL.
Behavior change
An attestation used as a material of an attestation in another organization is linked to that organization too. Until now, that organization also saw it through references that the first organization stored, for example under a material the two organizations share. Now it sees it as a root and through the references its own attestation stored, but not through references stored by the first organization.
Migration
- The two foreign keys are renamed to the names of the edge schema, instead of being dropped and recreated, so the table is not checked again.
- Both columns are added without a table rewrite.
- One backfill pass fills in the existing rows outside the schema-change transaction, so it takes only row locks. Nothing recorded which attestation stored a reference, so its organization is taken from the organizations both ends belong to: the one they share, or NULL when they share more than one.
- The index is built concurrently.
Out of scope
- The project-membership check for a material root still reads its references through the existing join.
Closes PFM-8116
Related to PFM-7062
AI assistance: this change was written with Claude Code.