@gleanql/client 0.1.13 → 0.1.14

package/dist/index.d.mts

@@ -265,6 +265,7 @@ declare class GraphRuntime {
   private readonly options;
   readonly cache: GraphCache;
   private readonly pending;
+  private readonly resolvedRoots;
   private queue;
   private flushScheduled;
   constructor(options: GraphRuntimeOptions);
@@ -272,6 +273,16 @@ declare class GraphRuntime {
   readField(ref: GraphRef, fieldKey: string, debug?: {
     component?: string;
   }): FieldValue;
+  /**
+   * Suspense primitive for a render-time ("two-sweep") root read: run `exec`
+   * once per `key` (it fetches the root with the call-site args and seeds the
+   * cache), throwing its promise until it resolves, then return the seeded root
+   * refs. Mirrors `readField`'s pending/throw/resume, keyed by the root field +
+   * its args. Because `exec` SEEDS before resolving, every subsequent field read
+   * on the returned refs is a cache hit — so a deferred root's fields never reach
+   * `reportMiss` (they aren't "unexpected" misses).
+   */
+  resolveRoot(key: string, exec: () => Promise<Record<string, FieldValue>>): Record<string, FieldValue>;
   /** Seed a record's fields (e.g. from the compiled operation result). */
   seed(ref: GraphRef, fields: Readonly<Record<string, FieldValue>>): void;
   /** Normalize a full operation result into the cache; returns root refs. */
@@ -328,6 +339,12 @@ interface CompiledOperation<RouteContext = unknown, TVariables = Record<string,
   readonly readMap?: Record<string, readonly string[]>;
   /** Merged selection tree; enables cache-first resolution when present. */
   readonly selection?: SelectionSet;
+  /** True when one or more root reads take render-time ("two-sweep") args; those
+   * roots are executed at the call-site, not preloaded from ctx. See `runtimeVars`. */
+  readonly deferred?: boolean;
+  /** Operation variables ($vars) supplied at the render call-site (the factory
+   * omits them); used to prune the eager preload + identify deferred roots. */
+  readonly runtimeVars?: readonly string[];
 }
 interface RunRouteOptions {
   /**
@@ -468,6 +485,19 @@ interface BindGraphOptions {
    * the server/isomorphic accessor omits it.
    */
   readonly tracker?: Set<string>;
+  /**
+   * Root fields whose args are computed at the render call-site ("two-sweep").
+   * They aren't preloaded; the callable executes them on demand via
+   * {@link BindGraphOptions.resolveDeferredRoot}.
+   */
+  readonly deferredRoots?: ReadonlySet<string>;
+  /**
+   * Execute a deferred root with its call-site args and return the seeded value
+   * (a ref, or an array of refs for a list root). Suspends (throws a promise)
+   * until the fetch+seed completes, then returns synchronously on retry. Wired by
+   * the integration over `runtime.resolveRoot` + `resolveDeferredRoot`.
+   */
+  readonly resolveDeferredRoot?: (rootField: string, args: Record<string, unknown> | undefined) => FieldValue;
 }
 declare function bindGraph(options: BindGraphOptions): BoundGraph;
 //#endregion

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { argAliasSuffix, canonicalArgs, responseKey } from "@gleanql/core";
+import { argAliasSuffix, canonicalArgs, printOperation, responseKey } from "@gleanql/core";
 //#region src/adapter-shared.ts
 /** Build a `GraphResult`, omitting empty `data`/`errors` keys. */
 function result(data, errors) {
@@ -459,6 +459,7 @@ var GraphRuntime = class GraphRuntime {
 	options;
 	cache;
 	pending = /* @__PURE__ */ new Map();
+	resolvedRoots = /* @__PURE__ */ new Map();
 	queue = [];
 	flushScheduled = false;
 	constructor(options) {
@@ -482,6 +483,33 @@ var GraphRuntime = class GraphRuntime {
 		this.scheduleFlush();
 		throw entry.promise;
 	}
+	/**
+	* Suspense primitive for a render-time ("two-sweep") root read: run `exec`
+	* once per `key` (it fetches the root with the call-site args and seeds the
+	* cache), throwing its promise until it resolves, then return the seeded root
+	* refs. Mirrors `readField`'s pending/throw/resume, keyed by the root field +
+	* its args. Because `exec` SEEDS before resolving, every subsequent field read
+	* on the returned refs is a cache hit — so a deferred root's fields never reach
+	* `reportMiss` (they aren't "unexpected" misses).
+	*/
+	resolveRoot(key, exec) {
+		const done = this.resolvedRoots.get(key);
+		if (done) return done;
+		const pkey = `@root:${key}`;
+		const existing = this.pending.get(pkey);
+		if (existing) throw existing.promise;
+		const entry = this.makeDeferred();
+		this.pending.set(pkey, entry);
+		exec().then((roots) => {
+			this.resolvedRoots.set(key, roots);
+			this.pending.delete(pkey);
+			entry.resolve();
+		}, (error) => {
+			this.pending.delete(pkey);
+			entry.reject(error);
+		});
+		throw entry.promise;
+	}
 	/** Seed a record's fields (e.g. from the compiled operation result). */
 	seed(ref, fields) {
 		this.cache.merge(ref, fields);
@@ -771,11 +799,16 @@ function bindGraph(options) {
 	const rootFields = options.schema.getType(queryType)?.fields ?? {};
 	const graph = {};
 	for (const [fieldName, fieldDef] of Object.entries(rootFields)) graph[fieldName] = (args) => {
-		const seeded = (typeof options.roots === "function" ? options.roots() : options.roots)?.[fieldName];
 		const trail = [{
 			name: fieldName,
 			...args ? { args } : {}
 		}];
+		if (options.deferredRoots?.has(fieldName) && options.resolveDeferredRoot) {
+			const seededDeferred = options.resolveDeferredRoot(fieldName, args);
+			if (fieldDef.list) return (Array.isArray(seededDeferred) ? seededDeferred : []).map((item) => wrap(binding, item, fieldDef.type, trail));
+			return wrap(binding, seededDeferred, fieldDef.type, trail);
+		}
+		const seeded = (typeof options.roots === "function" ? options.roots() : options.roots)?.[fieldName];
 		if (fieldDef.list) return (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail));
 		return createGraphProxy(binding, isGraphRef(seeded) ? seeded : { path: `${queryType}.${fieldName}(${canonicalArgs(toArgMap(args))})` }, fieldDef.type, trail);
 	};
@@ -1158,6 +1191,211 @@ function buildRouteContext(requestInfo, options = {}) {
 	};
 }
 //#endregion
+//#region src/paginate.ts
+/**
+* Execute a single deferred ("two-sweep") root read with args computed at the
+* render call-site, and seed the cache — the runtime half of the deferred-args
+* feature. Reuses the pagination machinery (`buildPageOperation` builds a
+* single-root operation from the compiled selection, turning the call-site args
+* into `$vars` with schema-derived types) but seeds the result as a fresh root
+* (`seedResult`) instead of appending a connection page. Pure — exported for
+* testing. The caller (the bound-graph deferred branch) wraps this in
+* `runtime.resolveRoot(...)` for Suspense de-dup + resume.
+*/
+async function resolveDeferredRoot(params) {
+	const { op, rootField, args, schema, adapter, runtime, context } = params;
+	const built = buildPageOperation(op, [{
+		name: rootField,
+		args
+	}], args, schema);
+	if (!built) return { ok: false };
+	let result;
+	try {
+		result = await adapter.execute({
+			name: built.name,
+			kind: "query",
+			document: built.document
+		}, args, context);
+	} catch (err) {
+		return {
+			ok: false,
+			error: errorMessage(err)
+		};
+	}
+	if (result?.errors?.length) return {
+		ok: false,
+		error: result.errors[0].message
+	};
+	return {
+		ok: true,
+		roots: result?.data ? runtime.seedResult(result.data) : {}
+	};
+}
+/**
+* Split a deferred operation into the part that can be preloaded eagerly from
+* `ctx` and the set of root fields whose args are render-time (`runtimeVars`).
+* Returns a pruned eager op (only the non-deferred roots, with just the vars they
+* still use) — `undefined` when no eager roots remain (a pure two-sweep route) —
+* plus the deferred root field names. Pure — exported for testing.
+*/
+function splitDeferredRoots(op, runtimeVars) {
+	const deferredRoots = /* @__PURE__ */ new Set();
+	const eagerFields = [];
+	for (const f of op.selection?.fields ?? []) {
+		const vars = /* @__PURE__ */ new Set();
+		for (const [, v] of f.args ?? []) collectArgValueVars(v, vars);
+		if ([...vars].some((v) => runtimeVars.has(v))) deferredRoots.add(f.name);
+		else eagerFields.push(f);
+	}
+	if (eagerFields.length === 0 || !op.selection) return { deferredRoots };
+	const selection = {
+		typeName: op.selection.typeName,
+		fields: eagerFields
+	};
+	const used = collectVarNames(selection);
+	const variables = parseVariableDefs(op.document).filter((v) => used.has(v.name));
+	const name = `${op.name}_eager`;
+	return {
+		eager: {
+			name,
+			kind: "query",
+			document: printOperation({
+				kind: "query",
+				name,
+				variables,
+				selection
+			}),
+			selection
+		},
+		deferredRoots
+	};
+}
+/** Variable names referenced in a single arg value (non-recursive into selections). */
+function collectArgValueVars(v, out) {
+	if (v.kind === "var") out.add(v.name);
+	else if (v.kind === "list") v.items.forEach((i) => collectArgValueVars(i, out));
+	else if (v.kind === "object") v.fields.forEach(([, vv]) => collectArgValueVars(vv, out));
+}
+/** The op field whose response key matches a runtime path step (handles arg-aliasing). */
+function pickStepField(fields, step) {
+	const named = fields.filter((f) => f.name === step.name);
+	if (named.length <= 1) return named[0];
+	const keys = responseKeyCandidates(step.name, toArgMap(step.args));
+	return named.find((f) => keys.includes(f.alias ?? f.name)) ?? named[0];
+}
+/** Replace/add args on the connection field, turning each caller arg into a `$var`. */
+function withUserArgs(existing, args) {
+	const map = new Map(existing ?? []);
+	for (const name of Object.keys(args)) map.set(name, {
+		kind: "var",
+		name
+	});
+	return [...map.entries()];
+}
+/** Clone the single root→connection path out of `op`, overriding the connection's args. */
+function clonePathField(parent, trail, depth, args) {
+	const field = pickStepField(parent.fields, trail[depth]);
+	if (!field) return void 0;
+	if (depth === trail.length - 1) return {
+		...field,
+		args: withUserArgs(field.args, args)
+	};
+	if (!field.selection) return void 0;
+	const child = clonePathField(field.selection, trail, depth + 1, args);
+	if (!child) return void 0;
+	const identity = field.selection.fields.filter((f) => !f.selection && (f.name === "__typename" || f.name === "id"));
+	return {
+		...field,
+		selection: {
+			typeName: field.selection.typeName,
+			fields: [...identity, child]
+		}
+	};
+}
+/** Walk the schema along `trail` to the connection field's declared arg types. */
+function connectionArgTypes(trail, schema) {
+	let parentType = schema.queryType;
+	let fieldDef;
+	for (const step of trail) {
+		if (!parentType) return {};
+		fieldDef = schema.getField(parentType, step.name);
+		parentType = fieldDef?.type;
+	}
+	const out = {};
+	for (const a of fieldDef?.args ?? []) out[a.name] = a.type;
+	return out;
+}
+/**
+* Build a query for the NEXT page of the connection at `trail`: the single path from
+* a Query root to it (with its full node/pageInfo selection), with the caller's
+* `args` overriding the connection field's arguments as `$vars`. Returns `undefined`
+* if the path isn't in the op. Pure — exported for testing.
+*/
+function buildPageOperation(op, trail, args, schema) {
+	if (!op.selection || trail.length === 0) return void 0;
+	const pathField = clonePathField(op.selection, trail, 0, args);
+	if (!pathField) return void 0;
+	const selection = {
+		typeName: op.selection.typeName,
+		fields: [pathField]
+	};
+	const used = collectVarNames(selection);
+	const argTypes = connectionArgTypes(trail, schema);
+	const headerVars = parseVariableDefs(op.document).filter((v) => used.has(v.name));
+	const argVars = Object.keys(args).map((name) => ({
+		name,
+		type: argTypes[name] ?? "String"
+	}));
+	const variables = dedupeVarsByName([...headerVars, ...argVars]);
+	const name = `${op.name}_page`;
+	return {
+		name,
+		kind: "query",
+		document: printOperation({
+			kind: "query",
+			name,
+			variables,
+			selection
+		})
+	};
+}
+function dedupeVarsByName(vars) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const v of vars) if (!seen.has(v.name)) seen.set(v.name, v);
+	return [...seen.values()];
+}
+/** Names of operation variables referenced anywhere in a selection's arguments. */
+function collectVarNames(sel) {
+	const out = /* @__PURE__ */ new Set();
+	const fromValue = (v) => {
+		if (v.kind === "var") out.add(v.name);
+		else if (v.kind === "list") v.items.forEach(fromValue);
+		else if (v.kind === "object") v.fields.forEach(([, vv]) => fromValue(vv));
+	};
+	const fromArgs = (args) => (args ?? []).forEach(([, v]) => fromValue(v));
+	const walk = (s) => {
+		for (const f of s.fields) {
+			fromArgs(f.args);
+			if (f.selection) walk(f.selection);
+		}
+		for (const fr of s.inlineFragments ?? []) walk(fr.selection);
+	};
+	walk(sel);
+	return out;
+}
+/** Parse `query Name($a: T!, $b: [U!])` → variable defs (operation header only). */
+function parseVariableDefs(document) {
+	const m = /^\s*(?:query|mutation|subscription)\s+\w+\s*\(([^)]*)\)\s*\{/.exec(document);
+	if (!m?.[1]) return [];
+	return m[1].split(",").map((s) => s.trim()).filter(Boolean).map((s) => {
+		const colon = s.indexOf(":");
+		return {
+			name: s.slice(0, colon).trim().replace(/^\$/, ""),
+			type: s.slice(colon + 1).trim()
+		};
+	});
+}
+//#endregion
 //#region src/integration.ts
 /**
 * RedwoodSDK integration.
@@ -1190,19 +1428,65 @@ function createGraphIntegration(options) {
 		if (!operation) return void 0;
 		const requestContext = buildRouteContext(requestInfo, options);
 		const runtime = makeRuntime(requestContext);
-		const { variables, roots, errors } = await runRoute({
-			operation,
-			routeContext: requestContext,
-			adapter: options.adapter,
-			context: requestContext,
-			runtime
-		});
+		let variables;
+		let roots;
+		let errors;
+		let deferredRoots;
+		if (operation.deferred) {
+			const split = splitDeferredRoots(operation, new Set(operation.runtimeVars ?? []));
+			deferredRoots = split.deferredRoots;
+			if (split.eager) {
+				const r = await runRoute({
+					operation: {
+						...operation,
+						name: split.eager.name,
+						document: split.eager.document,
+						selection: split.eager.selection
+					},
+					routeContext: requestContext,
+					adapter: options.adapter,
+					context: requestContext,
+					runtime
+				});
+				({variables, roots, errors} = r);
+			} else {
+				variables = operation.variables(requestContext);
+				roots = {};
+			}
+		} else {
+			const r = await runRoute({
+				operation,
+				routeContext: requestContext,
+				adapter: options.adapter,
+				context: requestContext,
+				runtime
+			});
+			({variables, roots, errors} = r);
+		}
+		const resolveDeferred = operation.deferred ? (rootField, args) => {
+			const key = `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
+			return runtime.resolveRoot(key, async () => {
+				const res = await resolveDeferredRoot({
+					op: operation,
+					rootField,
+					args: args ?? {},
+					schema: options.schema,
+					adapter: options.adapter,
+					runtime,
+					context: requestContext
+				});
+				if (!res.ok && res.error) throw new Error(res.error);
+				return res.roots ?? {};
+			})[rootField];
+		} : void 0;
 		const active = {
 			runtime,
 			graph: bindGraph({
 				schema: options.schema,
 				getRuntime: () => runtime,
-				roots
+				roots,
+				...deferredRoots ? { deferredRoots } : {},
+				...resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {}
 			}),
 			mutate: createMutator({
 				operations: options.operations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleanql/client",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Glean's runtime: normalized cache, fine-grained reactivity, mutations, subscriptions and React hooks",
   "license": "MIT",
   "author": "Alexander Liljengard",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@gleanql/core": "0.1.13"
+    "@gleanql/core": "0.1.14"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -52,6 +52,6 @@
   },
   "sideEffects": false,
   "scripts": {
-    "build": "NODE_OPTIONS=--max-old-space-size=4096 tsdown src/index.ts --format esm --dts.eager"
+    "build": "tsdown src/index.ts --format esm --dts.eager"
   }
 }

package/src/integration.ts

@@ -5,6 +5,7 @@ import {
   invalidateValue,
   runRoute,
   runServerMutation,
+  toArgMap,
   type MutationResult,
   type BoundGraph,
   type BoundMutations,
@@ -18,7 +19,8 @@ import {
   type MissingFieldRead,
   type MissingFieldResult,
 } from "./index.js";
-import type { SchemaModel } from "@gleanql/core";
+import { resolveDeferredRoot as runDeferredRoot, splitDeferredRoots } from "./paginate.js";
+import { canonicalArgs, type SchemaModel } from "@gleanql/core";
 import { buildRouteContext, type BuildRouteContextOptions, type GraphRouteContext, type RequestInfo } from "./context.js";
 
 /**
@@ -133,14 +135,65 @@ export function createGraphIntegration<Ctx extends Record<string, unknown> = Rec
 
     const requestContext = buildRouteContext(requestInfo, options);
     const runtime = makeRuntime(requestContext);
-    const { variables, roots, errors } = await runRoute({
-      operation,
-      routeContext: requestContext,
-      adapter: options.adapter,
-      context: requestContext,
-      runtime,
+
+    // Two-sweep: preload only the ctx-derivable roots; render-time roots execute
+    // at the call-site (resolveDeferredRoot below). A pure two-sweep route has no
+    // eager roots to preload at all.
+    let variables: Record<string, unknown>;
+    let roots: Record<string, FieldValue>;
+    let errors: ReadonlyArray<{ message: string }> | undefined;
+    let deferredRoots: ReadonlySet<string> | undefined;
+
+    if (operation.deferred) {
+      const split = splitDeferredRoots(operation, new Set(operation.runtimeVars ?? []));
+      deferredRoots = split.deferredRoots;
+      if (split.eager) {
+        const eagerOp: CompiledOperation<GraphRouteContext> = {
+          ...operation,
+          name: split.eager.name,
+          document: split.eager.document,
+          selection: split.eager.selection,
+        };
+        const r = await runRoute({ operation: eagerOp, routeContext: requestContext, adapter: options.adapter, context: requestContext, runtime });
+        ({ variables, roots, errors } = r);
+      } else {
+        variables = operation.variables(requestContext); // ctx vars only (factory omits deferred)
+        roots = {};
+      }
+    } else {
+      const r = await runRoute({ operation, routeContext: requestContext, adapter: options.adapter, context: requestContext, runtime });
+      ({ variables, roots, errors } = r);
+    }
+
+    // The deferred-root executor: fetch a render-time root with its call-site
+    // args (suspends via runtime.resolveRoot, seeds, then resolves to the ref(s)).
+    const resolveDeferred = operation.deferred
+      ? (rootField: string, args: Record<string, unknown> | undefined): FieldValue => {
+          const key = `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
+          const seededRoots = runtime.resolveRoot(key, async () => {
+            const res = await runDeferredRoot({
+              op: operation,
+              rootField,
+              args: args ?? {},
+              schema: options.schema,
+              adapter: options.adapter,
+              runtime,
+              context: requestContext,
+            });
+            if (!res.ok && res.error) throw new Error(res.error);
+            return res.roots ?? {};
+          });
+          return seededRoots[rootField];
+        }
+      : undefined;
+
+    const graph = bindGraph({
+      schema: options.schema,
+      getRuntime: () => runtime,
+      roots,
+      ...(deferredRoots ? { deferredRoots } : {}),
+      ...(resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {}),
     });
-    const graph = bindGraph({ schema: options.schema, getRuntime: () => runtime, roots });
     const mutate = createMutator({ operations: options.operations, adapter: options.adapter, runtime, context: requestContext });
 
     const active: ActiveRequestGraph = {

package/src/paginate.ts

@@ -13,6 +13,7 @@ import {
   responseKeyCandidates,
   toArgMap,
   createGraphProxy,
+  type FieldValue,
   type GraphClientAdapter,
   type GraphPagePointer,
   type GraphRef,
@@ -90,6 +91,79 @@ interface PageableOp {
   readonly selection?: SelectionSet;
 }
 
+/**
+ * Execute a single deferred ("two-sweep") root read with args computed at the
+ * render call-site, and seed the cache — the runtime half of the deferred-args
+ * feature. Reuses the pagination machinery (`buildPageOperation` builds a
+ * single-root operation from the compiled selection, turning the call-site args
+ * into `$vars` with schema-derived types) but seeds the result as a fresh root
+ * (`seedResult`) instead of appending a connection page. Pure — exported for
+ * testing. The caller (the bound-graph deferred branch) wraps this in
+ * `runtime.resolveRoot(...)` for Suspense de-dup + resume.
+ */
+export async function resolveDeferredRoot(params: {
+  readonly op: PageableOp;
+  readonly rootField: string;
+  readonly args: Record<string, unknown>;
+  readonly schema: SchemaModel;
+  readonly adapter: GraphClientAdapter;
+  readonly runtime: GraphRuntime;
+  readonly context: GraphRequestContext;
+}): Promise<{ ok: boolean; roots?: Record<string, FieldValue>; error?: string }> {
+  const { op, rootField, args, schema, adapter, runtime, context } = params;
+  const trail: PathStep[] = [{ name: rootField, args }];
+  const built = buildPageOperation(op, trail, args, schema);
+  if (!built) return { ok: false };
+
+  let result;
+  try {
+    result = await adapter.execute({ name: built.name, kind: "query", document: built.document }, args, context);
+  } catch (err) {
+    return { ok: false, error: errorMessage(err) };
+  }
+  if (result?.errors?.length) return { ok: false, error: result.errors[0]!.message };
+  const roots = result?.data ? runtime.seedResult(result.data as Record<string, unknown>) : {};
+  return { ok: true, roots };
+}
+
+/**
+ * Split a deferred operation into the part that can be preloaded eagerly from
+ * `ctx` and the set of root fields whose args are render-time (`runtimeVars`).
+ * Returns a pruned eager op (only the non-deferred roots, with just the vars they
+ * still use) — `undefined` when no eager roots remain (a pure two-sweep route) —
+ * plus the deferred root field names. Pure — exported for testing.
+ */
+export function splitDeferredRoots(
+  op: { name: string; document: string; selection?: SelectionSet },
+  runtimeVars: ReadonlySet<string>,
+): { eager?: { name: string; kind: "query"; document: string; selection: SelectionSet }; deferredRoots: Set<string> } {
+  const deferredRoots = new Set<string>();
+  const eagerFields: FieldSelection[] = [];
+  for (const f of op.selection?.fields ?? []) {
+    const vars = new Set<string>();
+    for (const [, v] of f.args ?? []) collectArgValueVars(v, vars);
+    if ([...vars].some((v) => runtimeVars.has(v))) deferredRoots.add(f.name);
+    else eagerFields.push(f);
+  }
+  if (eagerFields.length === 0 || !op.selection) return { deferredRoots };
+
+  const selection: SelectionSet = { typeName: op.selection.typeName, fields: eagerFields };
+  const used = collectVarNames(selection);
+  const variables = parseVariableDefs(op.document).filter((v) => used.has(v.name));
+  const name = `${op.name}_eager`;
+  return {
+    eager: { name, kind: "query", document: printOperation({ kind: "query", name, variables, selection }), selection },
+    deferredRoots,
+  };
+}
+
+/** Variable names referenced in a single arg value (non-recursive into selections). */
+function collectArgValueVars(v: ArgValue, out: Set<string>): void {
+  if (v.kind === "var") out.add(v.name);
+  else if (v.kind === "list") v.items.forEach((i) => collectArgValueVars(i, out));
+  else if (v.kind === "object") v.fields.forEach(([, vv]) => collectArgValueVars(vv, out));
+}
+
 export interface PaginateConnectionParams {
   readonly connection: unknown;
   readonly args: Record<string, unknown>;

package/src/proxy.ts

@@ -252,6 +252,19 @@ export interface BindGraphOptions {
    * the server/isomorphic accessor omits it.
    */
   readonly tracker?: Set<string>;
+  /**
+   * Root fields whose args are computed at the render call-site ("two-sweep").
+   * They aren't preloaded; the callable executes them on demand via
+   * {@link BindGraphOptions.resolveDeferredRoot}.
+   */
+  readonly deferredRoots?: ReadonlySet<string>;
+  /**
+   * Execute a deferred root with its call-site args and return the seeded value
+   * (a ref, or an array of refs for a list root). Suspends (throws a promise)
+   * until the fetch+seed completes, then returns synchronously on retry. Wired by
+   * the integration over `runtime.resolveRoot` + `resolveDeferredRoot`.
+   */
+  readonly resolveDeferredRoot?: (rootField: string, args: Record<string, unknown> | undefined) => FieldValue;
 }
 
 export function bindGraph(options: BindGraphOptions): BoundGraph {
@@ -266,10 +279,24 @@ export function bindGraph(options: BindGraphOptions): BoundGraph {
   const graph: Record<string, (args?: Record<string, unknown>) => unknown> = {};
   for (const [fieldName, fieldDef] of Object.entries(rootFields)) {
     graph[fieldName] = (args?: Record<string, unknown>) => {
+      const trail: PathStep[] = [{ name: fieldName, ...(args ? { args } : {}) }];
+
+      // Deferred ("two-sweep") root: args are only known at the render call-site,
+      // so execute on demand (suspends until fetched + seeded) instead of reading
+      // a preloaded root. This replaces the silent empty-array fallback below for
+      // deferred list roots — `glean.nodes({ ids }).map(...)` fetches, not yields [].
+      if (options.deferredRoots?.has(fieldName) && options.resolveDeferredRoot) {
+        const seededDeferred = options.resolveDeferredRoot(fieldName, args);
+        if (fieldDef.list) {
+          const items = Array.isArray(seededDeferred) ? seededDeferred : [];
+          return items.map((item) => wrap(binding, item, fieldDef.type, trail));
+        }
+        return wrap(binding, seededDeferred, fieldDef.type, trail);
+      }
+
       const rootsNow =
         typeof options.roots === "function" ? options.roots() : options.roots;
       const seeded = rootsNow?.[fieldName];
-      const trail: PathStep[] = [{ name: fieldName, ...(args ? { args } : {}) }];
       // A list root (`type Query { todos: [Todo!] }`) seeds an array of refs — wrap
       // each as a child proxy so `glean.todos().map(...)` works without an object
       // wrapper. Unseeded (pre-hydration / not yet fetched) -> empty array; the

package/src/route.ts

@@ -20,6 +20,12 @@ export interface CompiledOperation<RouteContext = unknown, TVariables = Record<s
   readonly readMap?: Record<string, readonly string[]>;
   /** Merged selection tree; enables cache-first resolution when present. */
   readonly selection?: SelectionSet;
+  /** True when one or more root reads take render-time ("two-sweep") args; those
+   * roots are executed at the call-site, not preloaded from ctx. See `runtimeVars`. */
+  readonly deferred?: boolean;
+  /** Operation variables ($vars) supplied at the render call-site (the factory
+   * omits them); used to prune the eager preload + identify deferred roots. */
+  readonly runtimeVars?: readonly string[];
 }
 
 export interface RunRouteOptions {

package/src/runtime.ts

@@ -48,6 +48,7 @@ interface PendingEntry {
 export class GraphRuntime {
   readonly cache: GraphCache;
   private readonly pending = new Map<string, PendingEntry>();
+  private readonly resolvedRoots = new Map<string, Record<string, FieldValue>>();
   private queue: MissingFieldRead[] = [];
   private flushScheduled = false;
 
@@ -73,6 +74,39 @@ export class GraphRuntime {
     throw entry.promise;
   }
 
+  /**
+   * Suspense primitive for a render-time ("two-sweep") root read: run `exec`
+   * once per `key` (it fetches the root with the call-site args and seeds the
+   * cache), throwing its promise until it resolves, then return the seeded root
+   * refs. Mirrors `readField`'s pending/throw/resume, keyed by the root field +
+   * its args. Because `exec` SEEDS before resolving, every subsequent field read
+   * on the returned refs is a cache hit — so a deferred root's fields never reach
+   * `reportMiss` (they aren't "unexpected" misses).
+   */
+  resolveRoot(key: string, exec: () => Promise<Record<string, FieldValue>>): Record<string, FieldValue> {
+    const done = this.resolvedRoots.get(key);
+    if (done) return done;
+
+    const pkey = `@root:${key}`;
+    const existing = this.pending.get(pkey);
+    if (existing) throw existing.promise; // dedupe in-flight / stable across retries
+
+    const entry = this.makeDeferred();
+    this.pending.set(pkey, entry);
+    exec().then(
+      (roots) => {
+        this.resolvedRoots.set(key, roots);
+        this.pending.delete(pkey);
+        entry.resolve();
+      },
+      (error) => {
+        this.pending.delete(pkey);
+        entry.reject(error);
+      },
+    );
+    throw entry.promise;
+  }
+
   /** Seed a record's fields (e.g. from the compiled operation result). */
   seed(ref: GraphRef, fields: Readonly<Record<string, FieldValue>>): void {
     this.cache.merge(ref, fields);