@gleanql/client 0.1.0

package/src/glue-server.ts

@@ -0,0 +1,46 @@
+import { jsx } from "react/jsx-runtime";
+import type { ComponentType, ReactNode } from "react";
+import { serializeGraph, type ActiveRequestGraph, type GraphHydrationPayload } from "./index.js";
+
+/**
+ * The server-side RSC glue. The generated `@gleanql/client/server` entrypoint is a
+ * thin shim that passes its framework's active-graph resolver + the client
+ * `GraphHydrator`, and re-exports `GraphHydrate`/`withGraphHydration`. Authored
+ * here (typed) rather than as a template string.
+ *
+ * `GraphHydrate` serializes this request's cache and renders the client hydrator
+ * with it as a prop, so the snapshot rides the RSC flight stream. `withGraphHydration`
+ * is the HOC the build plugin uses to auto-wrap each route component.
+ */
+export interface GraphServerOptions {
+  /** Resolve this request's active graph (null on non-graph routes). */
+  readonly getActive: () => ActiveRequestGraph | null;
+  /** The client hydrator component (from the generated client entrypoint). */
+  readonly GraphHydrator: ComponentType<{ payload: GraphHydrationPayload; children?: ReactNode }>;
+}
+
+export interface GraphServer {
+  GraphHydrate(props?: { clientSafeContext?: readonly string[]; children?: ReactNode }): ReactNode;
+  withGraphHydration<P extends object>(Page: ComponentType<P>): ComponentType<P>;
+}
+
+export function createGraphServer(opts: GraphServerOptions): GraphServer {
+  // The page renders INSIDE the hydrator: in the SSR pass the hydrator provides
+  // this request's graph through React context (request-isolated by construction),
+  // so `useGlean()` islands server-render warm. The payload prop still rides the
+  // flight stream for the browser's hydration.
+  function GraphHydrate(props?: { clientSafeContext?: readonly string[]; children?: ReactNode }): ReactNode {
+    const active = opts.getActive();
+    if (!active) return props?.children ?? null;
+    const payload = serializeGraph(active, { clientSafeContext: props?.clientSafeContext ?? [] });
+    return jsx(opts.GraphHydrator, { payload, children: props?.children });
+  }
+
+  function withGraphHydration<P extends object>(Page: ComponentType<P>): ComponentType<P> {
+    return function GraphHydratedPage(props: P) {
+      return jsx(GraphHydrate, { children: jsx(Page, props) });
+    };
+  }
+
+  return { GraphHydrate, withGraphHydration };
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `@gleanql/client` — the runtime an app installs.
+ *
+ * Bundles everything the app/worker needs at runtime: the Suspense-aware cache,
+ * graph proxies, request scope, mutations, the RedwoodSDK integration
+ * (preload/seed, serialize/hydrate), and the fetch transport adapter. The build
+ * plugin (`@gleanql/vite`) generates the schema-specific `graph` accessor +
+ * `operations` into this package's `generated/` slot; the app then imports
+ * everything from `@gleanql/client`.
+ */
+// Runtime core
+export * from "./adapter.js";
+export * from "./cache.js";
+export * from "./normalize.js";
+export * from "./runtime.js";
+export * from "./route.js";
+export * from "./cache-resolve.js";
+export * from "./proxy.js";
+export * from "./scope.js";
+export * from "./mutation.js";
+export * from "./mutator.js";
+// RedwoodSDK integration
+export * from "./context.js";
+export * from "./integration.js";
+export * from "./serialize.js";
+// Transport adapter helpers
+export * from "./adapter-shared.js";
+export * from "./adapter-ws.js";
+// Persisted-operation allowlist (server side)
+export * from "./persisted.js";

package/src/integration.ts

@@ -0,0 +1,201 @@
+import {
+  GraphRuntime,
+  bindGraph,
+  createMutator,
+  invalidateValue,
+  runRoute,
+  type BoundGraph,
+  type BoundMutations,
+  type CompiledOperation,
+  type FieldValue,
+  type GraphClientAdapter,
+  type GraphRef,
+  type GraphRequestContext,
+  type GraphScope,
+  type MissingFieldMode,
+  type MissingFieldRead,
+  type MissingFieldResult,
+} from "./index.js";
+import type { SchemaModel } from "@gleanql/core";
+import { buildRouteContext, type BuildRouteContextOptions, type GraphRouteContext, type RequestInfo } from "./context.js";
+
+/**
+ * RedwoodSDK integration.
+ *
+ * Answers the four questions the brief asks of a framework adapter:
+ *  - Which operation drives this entrypoint?  -> `resolveOperationName` / explicit name
+ *  - How do we read params/search/request/env? -> `buildRouteContext`
+ *  - How do we preload + seed?                 -> `runRoute` into a fresh per-request cache
+ *  - How do we expose the graph to components? -> attach a bound graph to `ctx`
+ *
+ * Per request: pick the operation, compute variables, execute via the client
+ * adapter, seed a fresh cache, and attach `{ runtime, graph, ... }` to
+ * `requestInfo.ctx` so Pages/components read graph fields with cache hits. Unseeded
+ * (lazy) fields fall through to the Suspense runtime.
+ */
+
+const CTX_KEY = "__graph" as const;
+
+export interface ActiveRequestGraph extends GraphRequestContext {
+  readonly runtime: GraphRuntime;
+  readonly graph: BoundGraph;
+  /** `graph.mutate.*` — one callable per compiled mutation operation. */
+  readonly mutate: BoundMutations;
+  readonly roots: Record<string, FieldValue>;
+  readonly operation: CompiledOperation<GraphRouteContext>;
+  readonly variables: Record<string, unknown>;
+  /** The route/request context (used for transport + missing-field fetches). */
+  readonly requestContext: GraphRouteContext;
+  readonly errors?: ReadonlyArray<{ message: string }>;
+}
+
+export interface GraphIntegrationOptions<Ctx extends Record<string, unknown> = Record<string, unknown>>
+  extends BuildRouteContextOptions<Ctx> {
+  readonly schema: SchemaModel;
+  /** Compiled operations, keyed by name (e.g. from `virtual:graph/operations`). */
+  readonly operations: Record<string, CompiledOperation<GraphRouteContext>>;
+  /** Transport: a fetch/graphql-request adapter. */
+  readonly adapter: GraphClientAdapter;
+  /** Map a request to its operation name when `preload` is called without one. */
+  readonly resolveOperationName?: (requestInfo: RequestInfo<Ctx>) => string | undefined;
+  /**
+   * Fetch fields absent from the compiled operation (lazy boundaries, dynamic
+   * misses). Receives the batched misses + request context; returns resolved
+   * values. If omitted, misses are allowed/warned per `unexpectedMissingField`
+   * (hybrid mode) and resolve to `undefined`.
+   */
+  readonly fetchMissing?: (
+    misses: readonly MissingFieldRead[],
+    context: GraphRequestContext,
+  ) => Promise<readonly MissingFieldResult[]>;
+  readonly unexpectedMissingField?: MissingFieldMode;
+  readonly onWarn?: (message: string) => void;
+  /** Allow-list of `context` keys that are safe to serialize to the client. */
+  readonly clientSafeContext?: readonly string[];
+  /** Optional scope to make a module-level `graph` import resolve this runtime. */
+  readonly scope?: GraphScope;
+}
+
+export interface GraphIntegration<Ctx extends Record<string, unknown>> {
+  /** Preload + seed the operation for a request; attaches the graph to `ctx`. */
+  preload(requestInfo: RequestInfo<Ctx>, operationName?: string): Promise<ActiveRequestGraph | undefined>;
+  /** Read the active graph attached to a request (throws if not preloaded). */
+  getGraph(requestInfo: RequestInfo<Ctx>): BoundGraph;
+  /** The `graph.mutate.*` namespace for this request (throws if not preloaded). */
+  getMutator(requestInfo: RequestInfo<Ctx>): BoundMutations;
+  /** Invalidate a graph value / ref in this request's cache (refetch on next read). */
+  invalidate(requestInfo: RequestInfo<Ctx>, value: GraphRef | unknown): void;
+  /** Read the full active request state (runtime, roots, variables, ...). */
+  getActive(requestInfo: RequestInfo<Ctx>): ActiveRequestGraph | undefined;
+  /** Re-run the active (or named) operation, bypassing cache-first, into the same cache. */
+  refetch(requestInfo: RequestInfo<Ctx>, operationName?: string): Promise<void>;
+  /** Run `fn` with this request's runtime installed on the scope (server render). */
+  runInScope<R>(requestInfo: RequestInfo<Ctx>, fn: () => R): R;
+}
+
+export function createGraphIntegration<Ctx extends Record<string, unknown> = Record<string, unknown>>(
+  options: GraphIntegrationOptions<Ctx>,
+): GraphIntegration<Ctx> {
+  // Identify entities by the schema's key fields (default `id`, or a `keys`
+  // override), so types keyed by something other than `id` normalize correctly.
+  const keyOf = (typename: string, obj: Record<string, unknown>) => options.schema.identityOf(typename, obj);
+
+  function makeRuntime(requestContext: GraphRouteContext): GraphRuntime {
+    return new GraphRuntime({
+      keyOf,
+      unexpectedMissingField: options.unexpectedMissingField,
+      onWarn: options.onWarn,
+      fetchMissing: async (misses) =>
+        options.fetchMissing ? options.fetchMissing(misses, requestContext) : missesUnresolved(misses),
+    });
+  }
+
+  async function preload(
+    requestInfo: RequestInfo<Ctx>,
+    operationName?: string,
+  ): Promise<ActiveRequestGraph | undefined> {
+    const name = operationName ?? options.resolveOperationName?.(requestInfo);
+    const operation = name ? options.operations[name] : undefined;
+    if (!operation) return undefined; // not a graph-backed entrypoint
+
+    const requestContext = buildRouteContext(requestInfo, options);
+    const runtime = makeRuntime(requestContext);
+    const { variables, roots, errors } = await runRoute({
+      operation,
+      routeContext: requestContext,
+      adapter: options.adapter,
+      context: requestContext,
+      runtime,
+    });
+    const graph = bindGraph({ schema: options.schema, getRuntime: () => runtime, roots });
+    const mutate = createMutator({ operations: options.operations, adapter: options.adapter, runtime, context: requestContext });
+
+    const active: ActiveRequestGraph = {
+      runtime,
+      graph,
+      mutate,
+      roots,
+      operation,
+      variables,
+      requestContext,
+      ...(errors ? { errors } : {}),
+    };
+    (requestInfo.ctx as Record<string, unknown>)[CTX_KEY] = active;
+    return active;
+  }
+
+  function getActive(requestInfo: RequestInfo<Ctx>): ActiveRequestGraph | undefined {
+    return (requestInfo.ctx as Record<string, unknown>)[CTX_KEY] as ActiveRequestGraph | undefined;
+  }
+
+  async function refetch(requestInfo: RequestInfo<Ctx>, operationName?: string): Promise<void> {
+    const active = getActive(requestInfo);
+    if (!active) return;
+    const operation = options.operations[operationName ?? active.operation.name];
+    if (!operation) return;
+    // Re-run into the same cache, bypassing cache-first; the re-seed bumps the
+    // cache version so subscribers (useSyncExternalStore) re-render.
+    await runRoute({
+      operation,
+      routeContext: active.requestContext,
+      adapter: options.adapter,
+      context: active.requestContext,
+      runtime: active.runtime,
+      options: { cacheFirst: false },
+    });
+  }
+
+  function getGraph(requestInfo: RequestInfo<Ctx>): BoundGraph {
+    const active = getActive(requestInfo);
+    if (!active) {
+      throw new Error(
+        "No graph attached to this request. Call integration.preload(requestInfo) before rendering (e.g. in a middleware or at the top of the Page).",
+      );
+    }
+    return active.graph;
+  }
+
+  function getMutator(requestInfo: RequestInfo<Ctx>): BoundMutations {
+    const active = getActive(requestInfo);
+    if (!active) throw new Error("No graph attached to this request. Call integration.preload(requestInfo) first.");
+    return active.mutate;
+  }
+
+  function invalidate(requestInfo: RequestInfo<Ctx>, value: GraphRef | unknown): void {
+    const active = getActive(requestInfo);
+    if (active) invalidateValue(active.runtime, value);
+  }
+
+  function runInScope<R>(requestInfo: RequestInfo<Ctx>, fn: () => R): R {
+    const active = getActive(requestInfo);
+    if (!active || !options.scope) return fn();
+    return options.scope.run({ runtime: active.runtime, graph: active.graph }, fn);
+  }
+
+  return { preload, getGraph, getMutator, invalidate, getActive, refetch, runInScope };
+}
+
+/** Default missing-field resolution: leave each miss undefined (hybrid allow/warn). */
+function missesUnresolved(misses: readonly MissingFieldRead[]): readonly MissingFieldResult[] {
+  return misses.map((m) => ({ ref: m.ref, fieldKey: m.fieldKey, value: undefined }));
+}

package/src/mutation.ts

@@ -0,0 +1,171 @@
+import { GraphCache, type GraphRef, type FieldValue } from "./cache.js";
+import type { GraphRuntime } from "./runtime.js";
+import type { GraphClientAdapter, GraphRequestContext } from "./adapter.js";
+import type { CompiledOperation } from "./route.js";
+import { selectionOf } from "./proxy.js";
+
+/**
+ * Mutations + invalidation.
+ *
+ * Reads were the first milestone; this is the write side. A mutation is run
+ * through the same client adapter as a query, and its result is normalized into
+ * the cache — so any entity it returns (`__typename + id`) updates *in place* and
+ * every read of that entity, through any path, reflects the change for free.
+ * That is the payoff of the normalized cache the brief asked for.
+ *
+ * On top of that the engine adds: GraphQL-style `userErrors`, optimistic writes
+ * with automatic rollback, and invalidation of affected graph values/roots.
+ */
+
+/** A GraphQL `userErrors` entry (Shopify-style mutation payloads). */
+export interface UserError {
+  readonly field?: readonly string[];
+  readonly message: string;
+  readonly code?: string;
+}
+
+export interface MutationResult<TData = unknown> {
+  readonly data?: TData;
+  /** Logical, per-mutation errors returned in the payload (not transport errors). */
+  readonly userErrors: readonly UserError[];
+  /** Transport/GraphQL execution errors. */
+  readonly errors?: ReadonlyArray<{ message: string }>;
+  /** True when there were no transport errors and no userErrors. */
+  readonly ok: boolean;
+}
+
+/**
+ * A reversible batch of cache writes. Optimistic updates record the prior value
+ * of every field they touch so the whole batch can be rolled back if the
+ * mutation fails (transport error or `userErrors`).
+ */
+export class MutationTransaction {
+  private readonly undo: Array<() => void> = [];
+
+  constructor(private readonly cache: GraphCache) {}
+
+  /** Optimistically write a field, remembering how to undo it. */
+  set(ref: GraphRef, fieldKey: string, value: FieldValue): void {
+    const before = this.cache.getField(ref, fieldKey);
+    if (before.status === "ready") {
+      const prev = before.value;
+      this.undo.push(() => this.cache.setField(ref, fieldKey, prev));
+    } else {
+      this.undo.push(() => this.cache.invalidateField(ref, fieldKey));
+    }
+    this.cache.setField(ref, fieldKey, value);
+  }
+
+  /** Roll back every write in reverse order. */
+  rollback(): void {
+    for (let i = this.undo.length - 1; i >= 0; i--) this.undo[i]!();
+    this.undo.length = 0;
+  }
+}
+
+export interface RunMutationOptions<TData = unknown> {
+  readonly operation: CompiledOperation<unknown, Record<string, unknown>> | {
+    readonly name: string;
+    readonly kind: "mutation";
+    readonly document: string;
+  };
+  readonly variables: Record<string, unknown>;
+  readonly adapter: GraphClientAdapter;
+  readonly context: GraphRequestContext;
+  readonly runtime: GraphRuntime;
+  /** Optimistically patch the cache before the request; rolled back on failure. */
+  readonly optimistic?: (tx: MutationTransaction) => void;
+  /** Apply the server result (e.g. prepend to a connection) after normalization. */
+  readonly update?: (data: TData, tx: MutationTransaction) => void;
+  /** Graph values / refs to invalidate on success (refetch on next read). */
+  readonly invalidate?: (data: TData) => ReadonlyArray<GraphRef | unknown>;
+}
+
+/**
+ * Execute a mutation, normalize its result into the cache, surface userErrors,
+ * and apply optimistic/invalidation policy. The returned promise never rejects
+ * for logical failures — inspect `ok`/`userErrors`/`errors`.
+ */
+export async function runMutation<TData = Record<string, unknown>>(
+  options: RunMutationOptions<TData>,
+): Promise<MutationResult<TData>> {
+  const { runtime, adapter, context, variables } = options;
+  const tx = new MutationTransaction(runtime.cache);
+  if (options.optimistic) options.optimistic(tx);
+
+  let result;
+  try {
+    result = await adapter.execute(
+      { name: options.operation.name, kind: "mutation", document: options.operation.document },
+      variables,
+      context,
+    );
+  } catch (error) {
+    tx.rollback();
+    return { userErrors: [], errors: [{ message: errorMessage(error) }], ok: false };
+  }
+
+  if (result.errors && result.errors.length > 0) {
+    tx.rollback();
+    return { userErrors: [], errors: result.errors, ok: false };
+  }
+
+  const data = result.data as TData | undefined;
+  const userErrors = data ? extractUserErrors(data as Record<string, unknown>) : [];
+
+  if (userErrors.length > 0) {
+    // The server rejected the change: undo the optimistic patch and report.
+    tx.rollback();
+    return { data, userErrors, ok: false };
+  }
+
+  // Success: fold the server result into the cache (entities update in place).
+  if (data) runtime.seedResult(data as Record<string, unknown>);
+  if (options.update && data) options.update(data, tx);
+
+  if (options.invalidate && data) {
+    for (const target of options.invalidate(data)) {
+      const ref = toRef(target);
+      if (ref) runtime.invalidate(ref);
+    }
+  }
+
+  return { data, userErrors: [], ok: true };
+}
+
+/** Invalidate a record by graph value (proxy) or raw ref — next read re-fetches. */
+export function invalidateValue(runtime: GraphRuntime, value: GraphRef | unknown): void {
+  const ref = toRef(value);
+  if (ref) runtime.invalidate(ref);
+}
+
+/** Collect `userErrors` from each top-level mutation payload in the result. */
+function extractUserErrors(data: Record<string, unknown>): UserError[] {
+  const out: UserError[] = [];
+  for (const value of Object.values(data)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const ue = (value as Record<string, unknown>).userErrors;
+      if (Array.isArray(ue)) {
+        for (const e of ue) {
+          if (e && typeof e === "object") out.push(e as UserError);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function toRef(value: GraphRef | unknown): GraphRef | undefined {
+  const selection = selectionOf(value);
+  if (selection) return selection.ref;
+  if (value && typeof value === "object") {
+    const v = value as Record<string, unknown>;
+    if ((v.__typename != null && v.id != null) || typeof v.path === "string") return v as GraphRef;
+  }
+  return undefined;
+}
+
+/** One rule for stringifying unknown errors, shared across hooks and transports. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/mutator.ts

@@ -0,0 +1,58 @@
+import type { GraphRuntime } from "./runtime.js";
+import type { GraphClientAdapter, GraphRequestContext } from "./adapter.js";
+import { runMutation, type MutationResult } from "./mutation.js";
+
+/** The minimal operation shape the mutator needs (any CompiledOperation satisfies it). */
+export interface MutationOperationLike {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "subscription";
+  readonly document: string;
+}
+
+/**
+ * The `graph.mutate.*` namespace.
+ *
+ * Mutations are compiled operations like queries; this binds one callable per
+ * compiled mutation operation so app code writes:
+ *
+ *   await graph.mutate.cartLinesAdd({ cartId, lines }, {
+ *     optimistic: (tx) => tx.set(cartRef, "totalQuantity", n + 1),
+ *     invalidate: (data) => [cartRef],
+ *   });
+ *
+ * Each call runs the mutation, folds the result into the cache, and applies the
+ * optimistic/invalidation policy (see runMutation).
+ */
+export type MutateFn = (
+  variables: Record<string, unknown>,
+  options?: Omit<Parameters<typeof runMutation>[0], "operation" | "variables" | "adapter" | "context" | "runtime">,
+) => Promise<MutationResult>;
+
+export type BoundMutations = Record<string, MutateFn>;
+
+export interface CreateMutatorOptions {
+  /** Compiled operations; only `kind: "mutation"` entries are bound. */
+  readonly operations: Record<string, MutationOperationLike>;
+  readonly adapter: GraphClientAdapter;
+  readonly runtime: GraphRuntime;
+  /** The request context (auth/locale/env) passed to the transport. */
+  readonly context: GraphRequestContext;
+}
+
+export function createMutator(options: CreateMutatorOptions): BoundMutations {
+  const mutate: BoundMutations = {};
+  for (const [name, operation] of Object.entries(options.operations)) {
+    if (operation.kind !== "mutation") continue;
+    const mutationOp = { name: operation.name, kind: "mutation" as const, document: operation.document };
+    mutate[name] = (variables, opts) =>
+      runMutation({
+        operation: mutationOp,
+        variables,
+        adapter: options.adapter,
+        context: options.context,
+        runtime: options.runtime,
+        ...opts,
+      });
+  }
+  return mutate;
+}

package/src/normalize.ts

@@ -0,0 +1,101 @@
+import type { GraphCache, GraphRef, FieldValue } from "./cache.js";
+
+/**
+ * Normalize a GraphQL JSON result into the cache.
+ *
+ * Every object selection includes `__typename` (and `id` when the type has one),
+ * so the result alone carries enough to choose an identity:
+ *  - `__typename + id` -> normalized entity record, deduped across queries.
+ *  - id-less object     -> embedded under its *owning entity* at the field path
+ *    since that entity (`Product:123.priceRange`), NOT the query path. So the same
+ *    nested object reached through two different queries resolves to one record —
+ *    update it once and every reader sees it, and a second query needn't refetch.
+ *  - id-less with no entity ancestor (root objects) -> anchored at the operation
+ *    path (`Query.search(q)`), which is the only correct identity for them.
+ * Scalars store inline; object fields store a `GraphRef`; lists store an array.
+ *
+ * `anchor` is the nearest owning entity's record key (or the root path); `field`
+ * is the path from that anchor.
+ */
+/**
+ * Resolve an object's identity value from its `__typename`, or undefined when
+ * the object is id-less (and must be embedded). Defaults to the `id` field;
+ * supply a schema-derived resolver to key types by another field (`sku`, `slug`)
+ * or a composite.
+ */
+export type KeyOf = (typename: string, obj: Record<string, unknown>) => string | undefined;
+
+const defaultKeyOf: KeyOf = (_t, obj) => (obj.id != null ? String(obj.id) : undefined);
+
+export function normalizeValue(
+  cache: GraphCache,
+  value: unknown,
+  anchor: string,
+  field: string,
+  keyOf: KeyOf = defaultKeyOf,
+  seen: WeakSet<object> = new WeakSet(),
+): FieldValue {
+  if (value === null || typeof value !== "object") return value as FieldValue;
+  // GraphQL JSON can't be cyclic, but optimistic/user-built objects can — fail
+  // with a clear message instead of blowing the stack. `seen` tracks the CURRENT
+  // DESCENT PATH (entries are removed on the way back up), so a DAG — the same
+  // object referenced from two siblings — still normalizes fine.
+  if (seen.has(value)) {
+    throw new Error(`normalizeValue: circular reference at ${anchor}.${field} — cannot normalize cyclic data`);
+  }
+  seen.add(value);
+  try {
+    return normalizeNonCyclic(cache, value, anchor, field, keyOf, seen);
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function normalizeNonCyclic(
+  cache: GraphCache,
+  value: object,
+  anchor: string,
+  field: string,
+  keyOf: KeyOf,
+  seen: WeakSet<object>,
+): FieldValue {
+  if (Array.isArray(value)) {
+    return value.map((item, i) => normalizeValue(cache, item, anchor, `${field}.${i}`, keyOf, seen));
+  }
+
+  const obj = value as Record<string, unknown>;
+  const typename = typeof obj.__typename === "string" ? obj.__typename : undefined;
+  const identity = typename != null ? keyOf(typename, obj) : undefined;
+
+  if (typename != null && identity != null) {
+    // Identified entity: a new normalization anchor; child paths reset under it.
+    const ref: GraphRef = { __typename: typename, id: identity };
+    const entityAnchor = cache.recordKey(ref);
+    for (const [key, v] of Object.entries(obj)) {
+      cache.setField(ref, key, normalizeValue(cache, v, entityAnchor, key, keyOf, seen));
+    }
+    return ref;
+  }
+
+  // Id-less: embed under the owning entity at `anchor.field` (stays anchored to
+  // the same entity as we descend, so it dedupes across queries).
+  const ref: GraphRef = { path: `${anchor}.${field}` };
+  for (const [key, v] of Object.entries(obj)) {
+    cache.setField(ref, key, normalizeValue(cache, v, anchor, `${field}.${key}`, keyOf, seen));
+  }
+  return ref;
+}
+
+/** Seed an operation result; returns each root field's ref for reading. */
+export function seedResult(
+  cache: GraphCache,
+  data: Readonly<Record<string, unknown>>,
+  options: { rootPath?: string; keyOf?: KeyOf } = {},
+): Record<string, FieldValue> {
+  const rootPath = options.rootPath ?? "Query";
+  const roots: Record<string, FieldValue> = {};
+  for (const [field, value] of Object.entries(data)) {
+    roots[field] = normalizeValue(cache, value, rootPath, field, options.keyOf);
+  }
+  return roots;
+}