Skip query-backed linksToMany expansion in prerender requests

[habdelra]

Summary

Inside a prerender request, the realm-server's loadLinks walker now stops short of expanding query-backed linksTo / linksToMany fields into included[], and the host's SearchResource resolves those relationships through stable per-URL GETs against the parent doc's already-serialized relationships.{field}.data IDs instead of firing a live _federated-search re-query.

Net effect on a card render whose template fans out across query-backed linksToMany fields:

	Before	After
_federated-search QUERY requests during the render	~240	~40 (just the top-level template searches)
Per-card cascade	every query-backed linksToMany getter fires a _federated-search and recursively expands	every getter loads the listed IDs by URL; each GET is one DB lookup
Wall-clock to data-prerender-status=ready (local stack, ~900-instance realm with 5 query-backed linksToMany fields per top-level card)	~213 s	~125 s
Bulk type search TTFB (direct _federated-search with the prerender header)	25–48 s	0.2–3 s (9–60× per type)

The live-SPA path is unchanged.

Why is N+1 small GETs faster than one big _federated-search?

It's counter-intuitive that replacing one server response that side-loads the linked resources with many per-URL GETs is faster. Two reasons:

1. Today's "one big response" isn't one request — it's a cascade

The current host behavior is: every query-backed linksToMany getter fires its own live _federated-search because the resource is isLive: true. So a Dashboard with M query-backed fields per card and N matched parents fans out into M×N×… cascaded searches, each of which itself returns a doc whose query-backed fields the next render layer also re-queries.

Concrete count during the local ~900-instance Dashboard render:

	_federated-search requests during render	Wall-clock to ready
Before	~240	~213 s
After	~40 (template's top-level searches only)	~125 s

The 200 requests we eliminate aren't "the parent's expansion" — they're cascaded re-queries from every child layer the template touches.

2. Each _federated-search was paying the full graph walk; per-URL GETs aren't

A _federated-search for a top-level type doesn't just read N rows — it executes the filter, then walks every query-backed linksToMany on every matched card, then walks their query-backed fields, serializing every reachable resource into included[]. Realm-server CPU and the SQL graph walk dominate; the actual filter is single-digit ms.

Measured directly with curl -X QUERY /_federated-search (TTFB, prerender header on, ~900-instance realm):

Top-level type search	data rows	included rows (before)	TTFB (before)	TTFB (after)	Speedup
Heavy type A	120	660 (full transitive walk)	14.8 s	<0.3 s	~50×
Heavy type B	30	780 (whole realm reachable through one query field)	21.7 s	<0.3 s	~70×
Heavy type C	40	~600	20.7 s	<0.3 s	~70×
Heavy type D	380	~580	16.9 s	~3 s	~6×
Heavy type E	200	~580	16.2 s	~2 s	~8×
Static-only type F	30	0	0.2 s	0.2 s	—
Static-only type G	50	0	0.2 s	0.2 s	—

The per-URL GETs that replace the included-expansion hit boxel_index by primary key, return the doc already-serialized at index time, and (post-CS-11176) reuse a job-scoped search cache when one of those linked instances is itself looked up by URL more than once during the render. Each GET is bounded by its own static-linksTo closure under the same prerender skip — no recursive query-field expansion through the cascade.

So the trade is: 1 expensive _federated-search (full-graph serialization) → 1 cheap _federated-search (just the top-level rows) + N cheap GETs (PK lookups, deduped by URL, multiplexed over HTTP/2). The wall-clock number is the integral of both, and the cascade-collapse is what makes it net-faster.

The contract change

Server side: loadLinks skips query-backed expansion in prerender

packages/runtime-common/realm-index-query-engine.ts gains a new skipQueryBackedExpansion option on the loadLinks walker. When set, the walker still populates relationships.{field}.data for query-backed linksTo / linksToMany fields but does not push the linked resources onto the next layer of the BFS. Static linksTo / linksToMany continue to expand transitively.

The per-field follow point reads the umbrella relationship's links.search. applyQueryResults is the only writer of that key, so its presence on a relationship is the unambiguous "this field is query-backed" signal at follow time.

packages/realm-server/handlers/handle-search.ts sets the opt for /_federated-search when x-boxel-during-prerender is on the request, mirroring the same gating used today for cacheOnlyDefinitions. The four cardDocument(..., { loadLinks: true }) call sites in packages/runtime-common/realm.ts (writeMany / patch / patch-noop / GET) thread the same opt via isDuringPrerenderRequest(request).

The walker is gated, not the indexer. boxel_index rows are written exactly as before. Only response shape changes — and only for requests inside a prerender.

Host side: SearchResource consumes the relationship IDs via per-URL GETs

packages/base/query-field-support.ts::captureQueryFieldSeedData captures the parent's relationships.{field}.data IDs into a new seedCardURLs array on the field's state, alongside the existing seedRecords / seedSearchURL / seedRealms.

packages/host/app/resources/search.ts::SearchResource.applySeed consumes those IDs: when the seed has empty cards but non-empty cardURLs, it loads each by URL through the runtime store (store.get(url)). The realm-server's instance-GET runs the same prerender skip, so each GET returns the bare resource plus its static-linksTo closure — no transitive query-backed walk.

The "seed is authoritative" predicate now reads three signals:

• seed.cards.length > 0 (parent serialized resolved instances in included)
• seed.cardURLs !== undefined (parent's relationship.data array was captured, including the empty-no-items case)
• seed.searchURL set (legacy signal — only present when the relationship is fully resolved)

In prerender, any of these short-circuits the live re-query. Outside prerender (isLive: true) this branch is bypassed entirely and the resource subscribes / re-validates as before.

Globals: one prerender flag, not two

Two globalThis flags signaled "this code is running in a prerender" at different layers and they didn't agree:

• __boxelDuringPrerender was set by the prerender server's evaluateOnNewDocument and read by the host's fetch wrapper.
• __boxelRenderContext was set by the host's route entry points and read by the seed-resolution logic.

The split caused the prerender header to silently miss in any test or driven render where the route flag was set but the server flag wasn't. Converged on __boxelRenderContext. The prerender server's evaluateOnNewDocument sets it; host routes (render / module / file-extract / command-runner) set it; the fetch wrapper, job-priority resolver, and seed-resolution path read it. The route teardown that previously cleared the flag now matches the other routes' isTesting() guard so the prerender server's persistent value survives between consecutive renders in a pooled tab.

How the new prerender request flow looks

1. Indexer fires _federated-search for the card it's rendering.
2. Server returns data + included containing only the static-linksTo closure (no recursion through query-backed fields). relationships.{field}.data still names the matched IDs for every query-backed field.
3. Host's applySeed reads cardURLs from the captured seed and issues per-URL GETs to materialize the listed cards.
4. Each per-URL GET also runs through the prerender skip, so it returns its own resource + static-linksTo closure without re-expanding query-backed fields.
5. Recursion terminates at the natural boundary of what the rendering template actually reads.

The cascade depth is bounded by how far the template walks the relationship graph, not by what the server eagerly includes.

Files changed

• packages/runtime-common/realm-index-query-engine.ts — skipQueryBackedExpansion opt + per-field follow gate in loadLinks.
• packages/runtime-common/realm.ts — thread the opt through Realm.search and all four cardDocument(..., { loadLinks: true }) call sites.
• packages/runtime-common/search-utils.ts — extend SearchableRealm / searchRealms opts.
• packages/realm-server/handlers/handle-search.ts — set the opt for /_federated-search based on the prerender header.
• packages/realm-server/prerender/page-pool.ts / prerender-constants.ts — set __boxelRenderContext (was __boxelDuringPrerender).
• packages/base/card-api.gts — extend the seed type with cardURLs.
• packages/base/query-field-support.ts — capture relationships.{field}.data IDs into seedCardURLs.
• packages/host/app/resources/search.ts — new per-URL load path in applySeed; widen the seed-authoritative predicate.
• packages/host/app/lib/prerender-fetch-headers.ts — read __boxelRenderContext (was __boxelDuringPrerender).
• packages/host/app/services/store.ts — extend the seed shape with cardURLs; same global rename.
• packages/host/app/routes/command-runner.ts — isTesting() guard on the route's __boxelRenderContext teardown so the persistent value survives between renders in a prerender tab (matches existing pattern in render.ts / module.ts / file-extract.ts).
• packages/host/tests/unit/job-priority-header-test.ts — global rename in test descriptions / comments.
• packages/realm-server/tests/skip-query-backed-expansion-test.ts — NEW unit test exercising both cardDocument and searchCards paths with and without the skip opt.

Test plan

• pnpm lint clean in packages/runtime-common and packages/base.
• CI lint on all packages (delegating realm-server / host to CI).
• New skip-query-backed-expansion-test.ts covers default-expand vs. skip on both code paths.
• Existing prerender, query-field, and search tests still pass on CI.
• Manual: indexer-driven prerender of a card with query-backed linksToMany fields on a realm-server build of this branch.

Out of scope

• Live-SPA behavior is unchanged. Outside a prerender, query-backed getters keep their live subscription semantics.
• The host's per-URL load path uses the existing store.get(url) instance-GET. No new endpoint is introduced.
• Cross-realm relationship data flows through the same path; cross-realm cards still resolve via federated mechanisms unchanged.

Risks

• The "is this field query-backed?" predicate keys off the umbrella relationship's links.search. If a future code path writes that key from somewhere other than applyQueryResults, the gate would mis-classify; the test in this PR pins the current writer.
• The host's per-URL fetch fan-out can recurse two levels for a Dashboard-shaped render (parent's query-backed linksToMany → each child's query-backed linksToMany). Termination is bounded by the template's actual reach into the relationship graph; tested locally.
• Instance-GET responses are also consumed by the live SPA. The skip only triggers when the request is identified as prerender via isDuringPrerenderRequest; non-prerender GETs are unchanged.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bc7212ed6e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR optimizes prerender-time relationship resolution by preventing the realm-server from eagerly expanding query-backed linksTo / linksToMany into included[], and instead having the host prerender path resolve those relationships via stable per-URL GETs based on the parent document’s relationships.{field}.data IDs. It also consolidates prerender detection onto a single globalThis.__boxelRenderContext flag.

Changes:

• Add skipQueryBackedExpansion plumbing from request detection → realm search / cardDocument → loadLinks walker to suppress query-backed transitive expansion during prerender.
• Extend query-field seed capture and host SearchResource.applySeed to use captured relationship IDs (cardURLs) and fetch per-URL rather than re-querying _federated-search.
• Rename prerender global from __boxelDuringPrerender to __boxelRenderContext and update routes/tests/headers to match.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/runtime-common/search-utils.ts	Extends search options to carry skipQueryBackedExpansion through searchRealms.
packages/runtime-common/realm.ts	Threads prerender-only skipQueryBackedExpansion into search and instance document generation.
packages/runtime-common/realm-index-query-engine.ts	Adds skipQueryBackedExpansion option and gates query-backed link traversal in loadLinks.
packages/realm-server/handlers/handle-search.ts	Enables skipQueryBackedExpansion for prerender-marked _federated-search requests.
packages/realm-server/prerender/prerender-constants.ts	Updates prerender global documentation to __boxelRenderContext.
packages/realm-server/prerender/page-pool.ts	Injects globalThis.__boxelRenderContext = true into pages.
packages/realm-server/tests/skip-query-backed-expansion-test.ts	Adds coverage for default vs. skip behavior for cardDocument and searchCards.
packages/base/card-api.gts	Extends search seed type to include cardURLs.
packages/base/query-field-support.ts	Captures relationship IDs into seedCardURLs for prerender seed resolution.
packages/host/app/resources/search.ts	Uses cardURLs to fetch per-URL instances in prerender seed mode; expands “seed is authoritative” predicate.
packages/host/app/lib/prerender-fetch-headers.ts	Switches prerender header gating to read __boxelRenderContext.
packages/host/app/services/store.ts	Renames prerender global usage and extends seed shape with cardURLs.
packages/host/app/routes/command-runner.ts	Aligns __boxelRenderContext teardown with other prerender routes (testing-only clear).
packages/host/tests/unit/job-priority-header-test.ts	Updates test descriptions/comments to the new global name.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files      1 suites   3h 38m 28s ⏱️
2 724 tests 2 706 ✅ 15 💤 0 ❌ 3 🔥
5 486 runs  5 450 ✅ 30 💤 3 ❌ 3 🔥

Results for commit f9a4060.

For more details on these errors, see this check.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   7m 48s ⏱️ - 1m 12s
1 482 tests ±0  1 482 ✅ ±0  0 💤 ±0  0 ❌ ±0 
1 573 runs  ±0  1 573 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit f9a4060. ± Comparison against earlier commit 7393d33.