@gleanql/client 0.1.13 → 0.1.15

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,24 @@ 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>;
+  /**
+   * Async twin of {@link resolveRoot} for non-React callers (server handlers,
+   * proxy): run `exec` once per `key` and RESOLVE to the seeded root refs instead
+   * of throwing a Suspense promise. Shares the `resolvedRoots` cache and the
+   * `pending` map with `resolveRoot`, so an `await` and a concurrent sync (thrown)
+   * read of the same root+args dedupe to a single in-flight fetch.
+   */
+  resolveRootAsync(key: string, exec: () => Promise<Record<string, FieldValue>>): Promise<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 +347,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 +493,25 @@ 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;
+  /**
+   * Async twin of {@link resolveDeferredRoot}: resolve the seeded value without
+   * throwing, so a deferred root can be `await`ed in a non-React server handler
+   * (`const o = await glean.order({ id })`). Wired over `runtime.resolveRootAsync`.
+   */
+  readonly resolveDeferredRootAsync?: (rootField: string, args: Record<string, unknown> | undefined) => Promise<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,64 @@ 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;
+	}
+	/**
+	* Async twin of {@link resolveRoot} for non-React callers (server handlers,
+	* proxy): run `exec` once per `key` and RESOLVE to the seeded root refs instead
+	* of throwing a Suspense promise. Shares the `resolvedRoots` cache and the
+	* `pending` map with `resolveRoot`, so an `await` and a concurrent sync (thrown)
+	* read of the same root+args dedupe to a single in-flight fetch.
+	*/
+	async resolveRootAsync(key, exec) {
+		const done = this.resolvedRoots.get(key);
+		if (done) return done;
+		const pkey = `@root:${key}`;
+		const existing = this.pending.get(pkey);
+		if (existing) {
+			await existing.promise;
+			return this.resolvedRoots.get(key) ?? {};
+		}
+		const entry = this.makeDeferred();
+		entry.promise.catch(() => {});
+		this.pending.set(pkey, entry);
+		try {
+			const roots = await exec();
+			this.resolvedRoots.set(key, roots);
+			this.pending.delete(pkey);
+			entry.resolve();
+			return roots;
+		} catch (error) {
+			this.pending.delete(pkey);
+			entry.reject(error);
+			throw error;
+		}
+	}
 	/** Seed a record's fields (e.g. from the compiled operation result). */
 	seed(ref, fields) {
 		this.cache.merge(ref, fields);
@@ -722,6 +781,7 @@ const handler = {
 			type: state.type
 		};
 		if (typeof prop === "symbol") return void 0;
+		if (prop === "then") return void 0;
 		if (prop === "__typename") return state.ref.__typename ?? readField(state, "__typename");
 		const fieldName = prop;
 		const fieldDef = state.binding.schema.getField(state.type, fieldName);
@@ -771,16 +831,54 @@ 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 materialize = (seeded) => fieldDef.list ? (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail)) : wrap(binding, seeded, fieldDef.type, trail);
+			return makeDeferredRootValue(fieldName, args, fieldDef.list ?? false, materialize, options.resolveDeferredRoot, options.resolveDeferredRootAsync);
+		}
+		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);
 	};
 	return graph;
 }
+/**
+* A deferred ("two-sweep") root read is BOTH awaitable and directly readable, so
+* the same call works in a React render and a plain server handler:
+*  - `await glean.order({ id })`  → async-resolve, no Suspense (server handlers)
+*  - `glean.order({ id }).name`   → sync-resolve, suspends until seeded (React)
+*
+* It's a proxy over an EMPTY array (list root) or object (singular root): `.then`
+* drives the async executor (kept in the get-trap only, never an own property, so
+* it is awaitable without leaking into enumeration/spread/JSON), and every other
+* access sync-resolves (throwing a Suspense promise until the fetch+seed completes)
+* then delegates to the materialized value. The array target keeps `Array.isArray`
+* true for a list root, matching a non-deferred list read; the materialized value
+* is memoized so repeated sync reads on the same returned value keep stable element
+* identity. When no async executor is wired `.then` is absent, so the value is a
+* plain (non-thenable) sync read — unchanged React behavior.
+*/
+function makeDeferredRootValue(rootField, args, isList, materialize, syncResolve, asyncResolve) {
+	const then = asyncResolve ? (onFulfilled, onRejected) => asyncResolve(rootField, args).then((seeded) => materialize(seeded)).then(onFulfilled, onRejected) : void 0;
+	let ready = false;
+	let value;
+	const syncValue = () => {
+		if (!ready) {
+			value = materialize(syncResolve(rootField, args));
+			ready = true;
+		}
+		return value;
+	};
+	return new Proxy(isList ? [] : {}, { get(_t, prop) {
+		if (prop === "then") return then;
+		const v = syncValue();
+		const got = v[prop];
+		return typeof got === "function" ? got.bind(v) : got;
+	} });
+}
 //#endregion
 //#region src/cache-resolve.ts
 /**
@@ -1158,6 +1256,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 +1493,66 @@ 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 deferredKey = (rootField, args) => `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
+		const deferredExec = (rootField, args) => 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 ?? {};
+		};
+		const resolveDeferred = operation.deferred ? (rootField, args) => runtime.resolveRoot(deferredKey(rootField, args), deferredExec(rootField, args))[rootField] : void 0;
+		const resolveDeferredAsync = operation.deferred ? async (rootField, args) => (await runtime.resolveRootAsync(deferredKey(rootField, args), deferredExec(rootField, args)))[rootField] : void 0;
 		const active = {
 			runtime,
 			graph: bindGraph({
 				schema: options.schema,
 				getRuntime: () => runtime,
-				roots
+				roots,
+				...deferredRoots ? { deferredRoots } : {},
+				...resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {},
+				...resolveDeferredAsync ? { resolveDeferredRootAsync: resolveDeferredAsync } : {}
 			}),
 			mutate: createMutator({
 				operations: options.operations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleanql/client",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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.15"
   },
   "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,76 @@ 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, seed the cache, and resolve to the seeded ref(s). `runDeferredRoot` is
+    // the shared async fetch; the SYNC form (`resolveRoot`) throws a Suspense
+    // promise for React renders, the ASYNC form (`resolveRootAsync`) resolves for
+    // non-React callers (`await glean.order({ id })` in a server handler). Both
+    // dedupe on the same root+args key.
+    const deferredKey = (rootField: string, args: Record<string, unknown> | undefined) =>
+      `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
+    const deferredExec =
+      (rootField: string, args: Record<string, unknown> | undefined) => async (): Promise<Record<string, FieldValue>> => {
+        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 ?? {};
+      };
+
+    const resolveDeferred = operation.deferred
+      ? (rootField: string, args: Record<string, unknown> | undefined): FieldValue =>
+          runtime.resolveRoot(deferredKey(rootField, args), deferredExec(rootField, args))[rootField]
+      : undefined;
+    const resolveDeferredAsync = operation.deferred
+      ? async (rootField: string, args: Record<string, unknown> | undefined): Promise<FieldValue> =>
+          (await runtime.resolveRootAsync(deferredKey(rootField, args), deferredExec(rootField, args)))[rootField]
+      : undefined;
+
+    const graph = bindGraph({
+      schema: options.schema,
+      getRuntime: () => runtime,
+      roots,
+      ...(deferredRoots ? { deferredRoots } : {}),
+      ...(resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {}),
+      ...(resolveDeferredAsync ? { resolveDeferredRootAsync: resolveDeferredAsync } : {}),
     });
-    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

@@ -175,6 +175,11 @@ const handler: ProxyHandler<{ state: ProxyState }> = {
       return { ref: state.ref, type: state.type } satisfies GraphSelection;
     }
     if (typeof prop === "symbol") return undefined;
+    // Never look like a thenable: a graph proxy can be the resolved value of
+    // `await glean.order({ id })`, and Promise resolution probes `.then` — reading
+    // it as a (missing) field would suspend/throw mid-resolution. GraphQL has no
+    // `then` field in practice, so returning undefined is safe.
+    if (prop === "then") return undefined;
     if (prop === "__typename") {
       // Identity field: prefer the ref's own typename, fall back to a cache read.
       return state.ref.__typename ?? readField(state, "__typename");
@@ -252,6 +257,28 @@ 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;
+  /**
+   * Async twin of {@link resolveDeferredRoot}: resolve the seeded value without
+   * throwing, so a deferred root can be `await`ed in a non-React server handler
+   * (`const o = await glean.order({ id })`). Wired over `runtime.resolveRootAsync`.
+   */
+  readonly resolveDeferredRootAsync?: (
+    rootField: string,
+    args: Record<string, unknown> | undefined,
+  ) => Promise<FieldValue>;
 }
 
 export function bindGraph(options: BindGraphOptions): BoundGraph {
@@ -266,10 +293,32 @@ 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 instead of reading a preloaded root. The returned
+      // value is ISOMORPHIC — `await glean.nodes({ ids })` resolves it (server
+      // handlers), while `glean.nodes({ ids }).map(...)` reads it synchronously via
+      // Suspense (React). This also replaces the silent empty-array fallback below:
+      // a deferred list root fetches, it does not yield [].
+      if (options.deferredRoots?.has(fieldName) && options.resolveDeferredRoot) {
+        const materialize = (seeded: FieldValue): unknown =>
+          fieldDef.list
+            ? (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail))
+            : wrap(binding, seeded, fieldDef.type, trail);
+        return makeDeferredRootValue(
+          fieldName,
+          args,
+          fieldDef.list ?? false,
+          materialize,
+          options.resolveDeferredRoot,
+          options.resolveDeferredRootAsync,
+        );
+      }
+
       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
@@ -286,3 +335,63 @@ export function bindGraph(options: BindGraphOptions): BoundGraph {
   }
   return graph as BoundGraph;
 }
+
+/**
+ * A deferred ("two-sweep") root read is BOTH awaitable and directly readable, so
+ * the same call works in a React render and a plain server handler:
+ *  - `await glean.order({ id })`  → async-resolve, no Suspense (server handlers)
+ *  - `glean.order({ id }).name`   → sync-resolve, suspends until seeded (React)
+ *
+ * It's a proxy over an EMPTY array (list root) or object (singular root): `.then`
+ * drives the async executor (kept in the get-trap only, never an own property, so
+ * it is awaitable without leaking into enumeration/spread/JSON), and every other
+ * access sync-resolves (throwing a Suspense promise until the fetch+seed completes)
+ * then delegates to the materialized value. The array target keeps `Array.isArray`
+ * true for a list root, matching a non-deferred list read; the materialized value
+ * is memoized so repeated sync reads on the same returned value keep stable element
+ * identity. When no async executor is wired `.then` is absent, so the value is a
+ * plain (non-thenable) sync read — unchanged React behavior.
+ */
+function makeDeferredRootValue(
+  rootField: string,
+  args: Record<string, unknown> | undefined,
+  isList: boolean,
+  materialize: (seeded: FieldValue) => unknown,
+  syncResolve: (rootField: string, args: Record<string, unknown> | undefined) => FieldValue,
+  asyncResolve?: (rootField: string, args: Record<string, unknown> | undefined) => Promise<FieldValue>,
+): unknown {
+  const then = asyncResolve
+    ? (onFulfilled?: (v: unknown) => unknown, onRejected?: (e: unknown) => unknown) =>
+        asyncResolve(rootField, args).then((seeded) => materialize(seeded)).then(onFulfilled, onRejected)
+    : undefined;
+
+  // Materialize once per resolved value: `syncResolve` throws the Suspense promise
+  // until seeded, so nothing is cached until it succeeds; afterwards repeated reads
+  // return the same array/proxies (stable identity, matching a plain array/object).
+  let ready = false;
+  let value: unknown;
+  const syncValue = (): Record<PropertyKey, unknown> => {
+    if (!ready) {
+      value = materialize(syncResolve(rootField, args));
+      ready = true;
+    }
+    return value as Record<PropertyKey, unknown>;
+  };
+
+  // A real array target for list roots (so `Array.isArray` is true and index/length
+  // reads behave like the array they materialize to); a plain object otherwise. Both
+  // are empty and carry no own keys, so enumeration/spread never leak internals.
+  const target: object = isList ? [] : {};
+
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (prop === "then") return then;
+      // Any other read sync-resolves (Suspense) then delegates to the materialized
+      // value/array. Bind functions (Array.prototype.* / callable graph fields) to
+      // that value so `this` is correct.
+      const v = syncValue();
+      const got = v[prop];
+      return typeof got === "function" ? (got as (...a: unknown[]) => unknown).bind(v) : got;
+    },
+  });
+}

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,79 @@ 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;
+  }
+
+  /**
+   * Async twin of {@link resolveRoot} for non-React callers (server handlers,
+   * proxy): run `exec` once per `key` and RESOLVE to the seeded root refs instead
+   * of throwing a Suspense promise. Shares the `resolvedRoots` cache and the
+   * `pending` map with `resolveRoot`, so an `await` and a concurrent sync (thrown)
+   * read of the same root+args dedupe to a single in-flight fetch.
+   */
+  async resolveRootAsync(key: string, exec: () => Promise<Record<string, FieldValue>>): Promise<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) {
+      // A sync read already kicked off this fetch — await it, then read the cache.
+      await existing.promise;
+      return this.resolvedRoots.get(key) ?? {};
+    }
+
+    const entry = this.makeDeferred();
+    // The barrier promise only exists to signal concurrent readers (a sync reader
+    // `throw`s it, an async reader `await`s it). On the solo path nothing attaches
+    // to it, so observe its rejection here — the error still propagates to THIS
+    // caller via the `throw` below; without this a failing `await glean.x()` would
+    // surface an unhandled rejection (noisy / isolate-fatal in a Worker).
+    entry.promise.catch(() => {});
+    this.pending.set(pkey, entry);
+    try {
+      const roots = await exec();
+      this.resolvedRoots.set(key, roots);
+      this.pending.delete(pkey);
+      entry.resolve();
+      return roots;
+    } catch (error) {
+      this.pending.delete(pkey);
+      entry.reject(error);
+      throw error;
+    }
+  }
+
   /** 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);