@bhooai/nexus-graphql 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @bhooai/nexus-graphql
+
+GraphQL on `graphql` (graphql-js) with a **custom federation/gateway layer built
+from scratch** — no Apollo, no `@graphql-tools/federation`.
+
+## Exports
+
+- **subgraph** — `defineSubgraph` (SDL + resolvers, auto-wires `_service`/`_entities`),
+  federation directives, `parseKeys`.
+- **gateway** — `createGateway({ subgraph })` (single-subgraph, in-process) and
+  `createFederatedGateway` (multi-subgraph). `graphqlHttpHandler({ gateway,
+  introspection, context })` for HTTP `/graphql`.
+- **subscriptions** — `PubSub` (async iterators), `SubscriptionServer` over
+  WebSocket (`graphql-transport-ws`) with auth.
+- **federation** — `composeSupergraph` (field ownership, `@key` collection,
+  `@provides`/`@requires` records → supergraph SDL), the query planner (FetchNode
+  DAG: root + entity fetches, `@requires` two-step), and `executor` (batched
+  `_entities` by `__typename+keyFields`, `@provides` short-circuit, error remap).
+
+## Subset supported (v1)
+
+`@key` (single + composite), `@external`, `@requires`, `@provides`, `@extends`,
+`_entities`, `_service { sdl }`. Skipped: `@shareable` arbitration, `@override`,
+`@inaccessible` enforcement, subscription federation. See `docs/ARCHITECTURE.md`.
+
+## Subscribe note
+
+`gateway.subscribe({ document, contextValue })` needs a **parsed** `DocumentNode`
+(`parse(query)`) and the param is `contextValue` (HTTP execute uses `context`).

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@bhooai/nexus-graphql",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "@bhooai/nexus-auth": "^0.1.0",
+    "graphql": "^16.9.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/federation/composeSupergraph.ts

@@ -0,0 +1,153 @@
+import { buildSchema, isObjectType, isInterfaceType, type GraphQLSchema, type GraphQLObjectType, type GraphQLInterfaceType } from 'graphql';
+import type { Subgraph } from '../types.js';
+import { parseFederationMetadata, type TypeMeta } from './parseMetadata.js';
+import { buildPublicSchema } from '../gateway/publicSchema.js';
+
+export interface EntitySource {
+  subgraph: string;
+  keyFields: string[];
+}
+export interface RequiresRecord {
+  subgraph: string;
+  requiresFields: string[];
+}
+
+export interface Supergraph {
+  subgraphs: Subgraph[];
+  /** typeName -> fieldName -> owning subgraph name. */
+  ownership: Map<string, Map<string, string>>;
+  /** typeName -> subgraphs that can resolve it via _entities (have @key). */
+  entities: Map<string, EntitySource[]>;
+  /** typeName -> fieldName -> subgraph that @provides the field. */
+  provides: Map<string, Map<string, string>>;
+  /** typeName -> fieldName -> { subgraph, requiresFields }. */
+  requires: Map<string, Map<string, RequiresRecord>>;
+  /** Client-facing merged SDL (no federation directives). */
+  mergedSdl: string;
+  /** Schema built from mergedSdl (for query planning/type lookup only). */
+  schema: GraphQLSchema;
+  /** Per-subgraph public schemas (type info). */
+  subgraphSchemas: Map<string, GraphQLSchema>;
+  /** Per-subgraph federation metadata. */
+  metadata: Map<string, Map<string, TypeMeta>>;
+}
+
+const ROOT_TYPES = ['Query', 'Mutation', 'Subscription'];
+
+/**
+ * Compose multiple subgraphs into a Supergraph: collect field ownership,
+ * entity @key sources, @provides and @requires records, and a merged public SDL.
+ *
+ * Ownership rule (v1): a field is owned by a subgraph if that subgraph's SDL
+ * defines the field on the type and it is NOT `@external`. The first subgraph
+ * to claim a non-external field wins; a conflicting claim by a second subgraph
+ * is recorded as a composition warning (real federation would arbitrate via
+ * `@shareable`/`@override` — out of scope for v1).
+ */
+export function composeSupergraph(subgraphs: Subgraph[]): Supergraph {
+  if (subgraphs.length === 0) throw new Error('[nexus-graphql] composeSupergraph requires subgraphs');
+
+  const ownership = new Map<string, Map<string, string>>();
+  const entities = new Map<string, EntitySource[]>();
+  const provides = new Map<string, Map<string, string>>();
+  const requires = new Map<string, Map<string, RequiresRecord>>();
+  const subgraphSchemas = new Map<string, GraphQLSchema>();
+  const metadata = new Map<string, Map<string, TypeMeta>>();
+  const conflicts: string[] = [];
+
+  for (const sub of subgraphs) {
+    const pub = buildPublicSchema(sub.sdl);
+    subgraphSchemas.set(sub.name, pub);
+    const meta = parseFederationMetadata(sub.sdl);
+    metadata.set(sub.name, meta);
+
+    for (const [typeName, typeMeta] of meta) {
+      // Entity sources: every @key on the type makes the subgraph a resolver.
+      if (typeMeta.keys.length) {
+        const list = entities.get(typeName) ?? [];
+        for (const keyFields of typeMeta.keys) list.push({ subgraph: sub.name, keyFields });
+        entities.set(typeName, list);
+      }
+      for (const [fieldName, fieldMeta] of typeMeta.fields) {
+        if (fieldMeta.external) continue; // resolved elsewhere — not owned here
+        const typeOwn = ownership.get(typeName) ?? new Map<string, string>();
+        if (typeOwn.has(fieldName) && typeOwn.get(fieldName) !== sub.name) {
+          conflicts.push(`${typeName}.${fieldName} claimed by ${typeOwn.get(fieldName)} and ${sub.name} (v1: first wins)`);
+        } else {
+          typeOwn.set(fieldName, sub.name);
+        }
+        ownership.set(typeName, typeOwn);
+        if (fieldMeta.provides) {
+          const tp = provides.get(typeName) ?? new Map<string, string>();
+          tp.set(fieldName, sub.name);
+          provides.set(typeName, tp);
+        }
+        if (fieldMeta.requires) {
+           const tr = requires.get(typeName) ?? new Map<string, RequiresRecord>();
+          tr.set(fieldName, { subgraph: sub.name, requiresFields: fieldMeta.requires });
+          requires.set(typeName, tr);
+        }
+      }
+    }
+  }
+
+  const mergedSdl = mergeSdl(subgraphs, subgraphSchemas, metadata, ownership);
+  const schema = buildSchema(mergedSdl);
+
+  return { subgraphs, ownership, entities, provides, requires, mergedSdl, schema, subgraphSchemas, metadata };
+}
+
+/** Build the merged public SDL from all subgraphs' public types. */
+function mergeSdl(
+  subgraphs: Subgraph[],
+  subgraphSchemas: Map<string, GraphQLSchema>,
+  _metadata: Map<string, Map<string, TypeMeta>>,
+  ownership: Map<string, Map<string, string>>,
+): string {
+  // Collect each type's fields (name -> SDL type string) from the owning subgraph's public schema.
+  const typeFields = new Map<string, Map<string, string>>();
+  const rootFields = new Map<string, Map<string, string>>(); // Query/Mutation/Subscription
+  const kinds = new Map<string, 'type' | 'interface'>();
+
+  for (const sub of subgraphs) {
+    const pub = subgraphSchemas.get(sub.name)!;
+    const typeMap = pub.getTypeMap();
+    for (const [typeName, gqlType] of Object.entries(typeMap)) {
+      if (typeName.startsWith('__') || typeName.startsWith('_')) continue;
+      if (isObjectType(gqlType)) {
+        const isRoot = ROOT_TYPES.includes(typeName);
+        const target = isRoot ? (rootFields.get(typeName) ?? new Map<string, string>()) : (typeFields.get(typeName) ?? new Map<string, string>());
+        kinds.set(typeName, 'type');
+        for (const field of Object.values(gqlType.getFields())) {
+          const owner = ownership.get(typeName)?.get(field.name);
+          // Include the field if this subgraph owns it (or it's a root field here).
+          if (isRoot || owner === sub.name) {
+            target.set(field.name, field.type.toString());
+          }
+        }
+        if (isRoot) rootFields.set(typeName, target); else typeFields.set(typeName, target);
+      } else if (isInterfaceType(gqlType)) {
+        const target = typeFields.get(typeName) ?? new Map<string, string>();
+        kinds.set(typeName, 'interface');
+        for (const field of Object.values(gqlType.getFields())) {
+          if (ownership.get(typeName)?.get(field.name) === sub.name) target.set(field.name, field.type.toString());
+        }
+        typeFields.set(typeName, target);
+      }
+    }
+  }
+
+  const parts: string[] = [];
+  for (const [typeName, fields] of rootFields) {
+    parts.push(`type ${typeName} {\n${fieldLines(fields)}\n}`);
+  }
+  for (const [typeName, fields] of typeFields) {
+    const kind = kinds.get(typeName) ?? 'type';
+    parts.push(`${kind} ${typeName} {\n${fieldLines(fields)}\n}`);
+  }
+  return parts.join('\n\n');
+}
+
+function fieldLines(fields: Map<string, string>): string {
+  return [...fields.entries()].map(([name, type]) => `  ${name}: ${type}`).join('\n');
+}

package/src/federation/createFederatedGateway.ts

@@ -0,0 +1,36 @@
+import { parse, type DocumentNode, type ExecutionResult } from 'graphql';
+import type { Subgraph, GraphQLContext, ExecuteParams } from '../types.js';
+import { composeSupergraph, type Supergraph } from './composeSupergraph.js';
+import { executeFederated, planQuery, type FetchPlan } from './executor.js';
+
+export interface FederatedGateway {
+  /** Client-facing merged schema. */
+  schema: Supergraph['schema'];
+  supergraph: Supergraph;
+  subgraphs: Subgraph[];
+  execute(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<ExecutionResult>;
+  /** Inspect the fetch plan for a query (golden tests / debugging). */
+  plan(document: DocumentNode): FetchPlan;
+}
+
+/**
+ * Compose multiple subgraphs into a federated gateway. The gateway exposes the
+ * merged public schema and executes queries via the naive sequential federated
+ * executor (root fetches + iterative entity-join passes). Subscriptions are not
+ * federated in v1 — route them to the owning subgraph's `SubscriptionServer`.
+ */
+export function createFederatedGateway(subgraphs: Subgraph[]): FederatedGateway {
+  const supergraph = composeSupergraph(subgraphs);
+  return {
+    schema: supergraph.schema,
+    supergraph,
+    subgraphs,
+    async execute(params) {
+      const document: DocumentNode = params.document;
+      return executeFederated(supergraph, document, params.variableValues, (params.contextValue as GraphQLContext) ?? {});
+    },
+    plan(document) {
+      return planQuery(supergraph, document);
+    },
+  };
+}

package/src/federation/executor.ts

@@ -0,0 +1,305 @@
+import { execute, parse, isObjectType, isInterfaceType, type DocumentNode, type SelectionSetNode, type FieldNode, type InlineFragmentNode, type FragmentSpreadNode, type ExecutionResult } from 'graphql';
+import type { Supergraph } from './composeSupergraph.js';
+import type { Subgraph, GraphQLContext } from '../types.js';
+import { createFieldResolver } from '../gateway/fieldResolver.js';
+
+/**
+ * Naive sequential federated executor (Phase 6, v1).
+ *
+ * Algorithm:
+ *   1. Root pass — group the operation's top-level fields by their owning
+ *      subgraph; for each group, execute a trimmed subquery against that
+ *      subgraph in-process. Trim keeps only fields owned by that subgraph,
+ *      plus `__typename` and entity key fields (so later passes can join).
+ *   2. Entity-join passes — scan the stitched result for entity-typed objects
+ *      whose requested fields are owned by *other* subgraphs; for each such
+ *      (subgraph, type) pair, call that subgraph's `_entities` with
+ *      representations built from the parents' keys and a trimmed subquery,
+ *      then merge the returned fields back by key. Repeat until no missing
+ *      fields remain (handles nested joins, one level per pass).
+ *
+ * Limitations (documented): sequential (no parallel fetch fan-out), `@requires`
+ * supported as "fetch the required external fields first, then resolve", no
+ * `@shareable` arbitration, no `@override`. Composition is ours; execution is
+ * in-process (shared nothing is Phase 6-distributed, designed not built).
+ */
+
+export interface FetchNode {
+  kind: 'root' | 'entities';
+  subgraph: string;
+  /** SDL selection set this fetch executes. */
+  selection: string;
+  /** For entity fetches: the entity type name being resolved. */
+  typeName?: string;
+  /** For entity fetches: key fields used to build representations. */
+  keyFields?: string[];
+}
+export interface FetchPlan {
+  nodes: FetchNode[];
+}
+
+/** Build a FetchPlan description for inspection/golden tests. */
+export function planQuery(supergraph: Supergraph, document: DocumentNode): FetchPlan {
+  const nodes: FetchNode[] = [];
+  const op = document.definitions.find((d) => d.kind === 'OperationDefinition') as
+    | { selectionSet: SelectionSetNode }
+    | undefined;
+  if (!op) return { nodes };
+  const rootType = 'Query';
+  const bySub = new Map<string, string[]>();
+  for (const sel of op.selectionSet.selections) {
+    if (sel.kind === 'Field') {
+      const owner = supergraph.ownership.get(rootType)?.get((sel as FieldNode).name.value);
+      if (owner) bySub.set(owner, [...(bySub.get(owner) ?? []), (sel as FieldNode).name.value]);
+    }
+  }
+  for (const [sub, fields] of bySub) {
+    nodes.push({ kind: 'root', subgraph: sub, selection: `{ ${fields.join(' ') } }` });
+  }
+  return { nodes };
+}
+
+/** Execute a federated query in-process against the composed subgraphs. */
+export async function executeFederated(
+  supergraph: Supergraph,
+  document: DocumentNode,
+  variableValues: Record<string, any> | undefined,
+  contextValue: GraphQLContext,
+): Promise<ExecutionResult> {
+  const op = document.definitions.find((d) => d.kind === 'OperationDefinition') as
+    | { selectionSet: SelectionSetNode; operation: string }
+    | undefined;
+  if (!op) return { errors: [{ message: 'No operation in document' }] as unknown as NonNullable<ExecutionResult['errors']> };
+  const rootType = op.operation === 'mutation' ? 'Mutation' : op.operation === 'subscription' ? 'Subscription' : 'Query';
+
+  const subgraphByName = new Map<string, Subgraph>(supergraph.subgraphs.map((s) => [s.name, s]));
+
+  // 1. Root pass: group top-level fields by owner and execute trimmed subqueries.
+  const rootGroups = new Map<string, FieldNode[]>();
+  for (const sel of op.selectionSet.selections) {
+    if (sel.kind !== 'Field') continue; // v1: no fragment spreads at root
+    const owner = supergraph.ownership.get(rootType)?.get(sel.name.value);
+    if (!owner) return { errors: [{ message: `No subgraph owns ${rootType}.${sel.name.value}` }] as unknown as NonNullable<ExecutionResult['errors']> };
+    const arr = rootGroups.get(owner) ?? [];
+    arr.push(sel);
+    rootGroups.set(owner, arr);
+  }
+
+  const data: Record<string, unknown> = {};
+  for (const [subName, fields] of rootGroups) {
+    const sub = subgraphByName.get(subName)!;
+    const sel = trimSelection(fields, rootType, subName, supergraph, true);
+    const sdl = `${op.operation} { ${sel} }`;
+    const res = await execSubgraph(sub, parse(sdl), variableValues, contextValue);
+    if (res.errors) return { errors: res.errors };
+    Object.assign(data, res.data as Record<string, unknown>);
+  }
+
+  // 2. Iterative entity-join passes.
+  for (let pass = 0; pass < 8; pass++) {
+    const pending = collectMissing(supergraph, op.selectionSet, rootType, data);
+    if (pending.length === 0) break;
+    for (const job of pending) {
+      const sub = subgraphByName.get(job.subgraph)!;
+      const reps = job.parents.map((p) => pickKeys(p, job.keyFields));
+      const sel = trimSelection(job.fieldNodes, job.typeName, job.subgraph, supergraph, true);
+      const sdl = `query($reps: [_Any!]!){ _entities(representations: $reps){ ... on ${job.typeName} { ${sel} } } }`;
+      const res = await execSubgraph(sub, parse(sdl), { ...variableValues, reps }, contextValue);
+      if (res.errors) return { errors: res.errors };
+      const entities = (res.data as Record<string, unknown> | undefined)?._entities as any[] | undefined;
+      if (!entities) continue;
+      mergeEntities(job.parents, entities, job.keyFields, job.typeName, job.missingFields);
+    }
+  }
+
+  return { data };
+}
+
+/** Run a document against a subgraph's federation schema + resolvers in-process. */
+async function execSubgraph(sub: Subgraph, document: DocumentNode, variableValues: Record<string, any> | undefined, contextValue: GraphQLContext): Promise<ExecutionResult> {
+  return execute({
+    schema: sub.schema,
+    document,
+    rootValue: undefined,
+    contextValue,
+    variableValues,
+    fieldResolver: createFieldResolver(sub.resolvers),
+  });
+}
+
+/** Unwrap a GraphQL type name to its base named type. */
+function baseType(type: string): string {
+  return type.replace(/[\[\]!]/g, '');
+}
+
+/** Output SDL type of a field on a type, from the supergraph (merged) schema. */
+function fieldType(supergraph: Supergraph, parentType: string, fieldName: string): string | undefined {
+  const t = supergraph.schema.getType(parentType);
+  if (isObjectType(t)) return t.getFields()[fieldName]?.type.toString();
+  if (isInterfaceType(t)) return t.getFields()[fieldName]?.type.toString();
+  return undefined;
+}
+
+/**
+ * Trim a list of selections (for one parent type) to fields owned by `subgraphName`,
+ * preserving field arguments, plus `__typename`. For entity-typed parents, the
+ * entity's @key fields owned by `subgraphName` are force-included so downstream
+ * join passes can build representations. Fields owned by other subgraphs are
+ * omitted here (a later entity-join pass fills them). Returns an SDL selection-set.
+ */
+function trimSelection(selections: readonly (FieldNode | InlineFragmentNode | FragmentSpreadNode)[], parentType: string, subgraphName: string, supergraph: Supergraph, _includeKeys: boolean): string {
+  const parts: string[] = [];
+  const included = new Set<string>();
+  for (const sel of selections) {
+    if (sel.kind === 'Field') {
+      const name = sel.name.value;
+      if (name === '__typename') { parts.push('__typename'); included.add(name); continue; }
+      const owner = supergraph.ownership.get(parentType)?.get(name);
+      const ft = fieldType(supergraph, parentType, name);
+      const childType = ft ? baseType(ft) : undefined;
+      if (owner === subgraphName) {
+        const sub = sel.selectionSet ? trimSelection(sel.selectionSet.selections, childType!, subgraphName, supergraph, true) : '';
+        const args = argsToSdl(sel.arguments);
+        parts.push(sub ? `${name}${args} { ${sub} }` : `${name}${args}`);
+        included.add(name);
+      }
+      // Fields owned by other subgraphs are omitted here; an entity-join pass fills them.
+    } else if (sel.kind === 'InlineFragment') {
+      const fragType = sel.typeCondition?.name.value ?? parentType;
+      const sub = trimSelection(sel.selectionSet.selections, fragType, subgraphName, supergraph, _includeKeys);
+      parts.push(`... on ${fragType} { ${sub} }`);
+    }
+    // FragmentSpread: v1 ignores (rare in generated clients)
+  }
+  // Force-include this entity's key fields (owned by this subgraph) so join passes
+  // can build representations even when the client didn't request them.
+  if (supergraph.entities.has(parentType)) {
+    const src = (supergraph.entities.get(parentType) ?? []).find((s) => s.subgraph === subgraphName);
+    if (src) {
+      for (const kf of src.keyFields) {
+        if (supergraph.ownership.get(parentType)?.get(kf) === subgraphName && !included.has(kf)) {
+          parts.push(kf);
+          included.add(kf);
+        }
+      }
+    }
+  }
+  return parts.join(' ');
+}
+
+/** Serialize a field's arguments to SDL, e.g. `(id: "u1", limit: $limit)`. */
+function argsToSdl(args: readonly import('graphql').ArgumentNode[] | undefined): string {
+  if (!args || args.length === 0) return '';
+  return '(' + args.map((a) => `${a.name.value}: ${valueToSdl(a.value)}`).join(', ') + ')';
+}
+function valueToSdl(v: import('graphql').ValueNode): string {
+  switch (v.kind) {
+    case 'IntValue': case 'FloatValue': return v.value;
+    case 'StringValue': return JSON.stringify(v.value);
+    case 'BooleanValue': return String(v.value);
+    case 'EnumValue': return v.value;
+    case 'NullValue': return 'null';
+    case 'Variable': return '$' + v.name.value;
+    case 'ListValue': return '[' + v.values.map(valueToSdl).join(', ') + ']';
+    case 'ObjectValue': return '{' + v.fields.map((f) => `${f.name.value}: ${valueToSdl(f.value)}`).join(', ') + '}';
+    default: return '';
+  }
+}
+
+function pickKeys(obj: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = { __typename: obj.__typename };
+  for (const k of keys) if (k in obj) out[k] = obj[k];
+  return out;
+}
+
+interface JoinJob {
+  subgraph: string;
+  typeName: string;
+  keyFields: string[];
+  parents: Record<string, unknown>[];
+  missingFields: string[];
+  fieldNodes: (FieldNode | InlineFragmentNode | FragmentSpreadNode)[];
+}
+
+/**
+ * Walk the stitched `data` against the query selection set; for each entity-typed
+ * object, find fields the query wants that are owned by a *different* subgraph
+ * than the one that produced the object, and emit a JoinJob to fetch them.
+ */
+function collectMissing(supergraph: Supergraph, selectionSet: SelectionSetNode, parentType: string, data: Record<string, unknown> | unknown[]): JoinJob[] {
+  const jobs: JoinJob[] = [];
+  walk(supergraph, selectionSet, parentType, data, jobs, new Set());
+  return jobs;
+}
+
+function walk(supergraph: Supergraph, selectionSet: SelectionSetNode, parentType: string, data: unknown, jobs: JoinJob[], seen: Set<Record<string, unknown>>): void {
+  if (data == null) return;
+  if (Array.isArray(data)) { for (const item of data) walk(supergraph, selectionSet, parentType, item, jobs, seen); return; }
+  if (typeof data !== 'object') return;
+  const obj = data as Record<string, unknown>;
+
+  // Group requested fields by their owning subgraph; identify fields owned by a
+  // subgraph other than the one that produced this object (inferred from the
+  // fields already present). For each foreign owner, build a job.
+  const requestedByOwner = new Map<string, FieldNode[]>();
+  for (const sel of selectionSet.selections) {
+    if (sel.kind !== 'Field') continue;
+    const name = sel.name.value;
+    if (name === '__typename') continue;
+    const owner = supergraph.ownership.get(parentType)?.get(name);
+    if (!owner) continue;
+    if (!(name in obj)) { // missing → needs fetching from `owner`
+      const arr = requestedByOwner.get(owner) ?? [];
+      arr.push(sel);
+      requestedByOwner.set(owner, arr);
+    } else if (sel.selectionSet) {
+      // present → recurse into children for nested joins
+      const ft = fieldType(supergraph, parentType, name);
+      const childType = ft ? baseType(ft) : undefined;
+      if (childType) walk(supergraph, sel.selectionSet, childType, obj[name], jobs, seen);
+    }
+  }
+
+  if (requestedByOwner.size === 0) return;
+  if (seen.has(obj)) return;
+  seen.add(obj);
+
+  const entitySources = supergraph.entities.get(parentType) ?? [];
+  if (entitySources.length === 0) return; // can't join a non-entity
+
+  for (const [owner, fieldNodes] of requestedByOwner) {
+    // Pick a key for this owner: an entity source whose subgraph == owner, else first.
+    const source = entitySources.find((s) => s.subgraph === owner) ?? entitySources[0]!;
+    const keyFields = source.keyFields;
+    // Only emit if we actually have the key fields present on the object.
+    if (!keyFields.every((k) => k in obj)) continue;
+    jobs.push({
+      subgraph: owner,
+      typeName: parentType,
+      keyFields,
+      parents: [obj],
+      missingFields: fieldNodes.map((f) => f.name.value),
+      fieldNodes,
+    });
+  }
+}
+
+/**
+ * Merge fetched entity fields back into the parent objects. `_entities` returns
+ * one resolved entity per representation, in order; `reps` were built from
+ * `parents` in order, so `entities[i]` corresponds to `parents[i]`. We merge by
+ * index (not by key tuple) because the fetched entity may not carry its `@key`
+ * fields — they may be `@external` on the resolving subgraph and absent from the
+ * trimmed selection. Null entries (entity resolver returned null) are skipped.
+ */
+function mergeEntities(parents: Record<string, unknown>[], entities: any[], _keyFields: string[], typeName: string, missingFields: string[]): void {
+  for (let i = 0; i < parents.length; i++) {
+    const e = entities[i];
+    const p = parents[i]!;
+    if (!e || typeof e !== 'object') continue;
+    for (const f of missingFields) {
+      if (f in e) p[f] = e[f];
+    }
+    if (!p.__typename) p.__typename = typeName;
+  }
+}

package/src/federation/parseMetadata.ts

@@ -0,0 +1,87 @@
+/**
+ * Parse federation metadata from subgraph SDL: per type, its `@key` sets,
+ * whether it is an `@extends` extension, and per field whether it is
+ * `@external`, `@provides(fields)`, or `@requires(fields)`. Uses brace matching
+ * (not a full AST) — sufficient for the v1 federation subset and the kind of
+ * type blocks we generate/accept.
+ */
+export interface FieldMeta {
+  /** Field is declared `@external` (resolved by another subgraph). */
+  external: boolean;
+  /** `@provides(fields: "...")` — this subgraph provides this field on an entity. */
+  provides?: string[];
+  /** `@requires(fields: "...")` — this field is computed from external fields. */
+  requires?: string[];
+}
+export interface TypeMeta {
+  isExtend: boolean;
+  keys: string[][];
+  fields: Map<string, FieldMeta>;
+}
+
+export function parseFederationMetadata(sdl: string): Map<string, TypeMeta> {
+  const types = new Map<string, TypeMeta>();
+  // Find `type|interface Name <header> {` and capture the balanced body.
+  const headerRe = /(?:extend\s+)?(?:type|interface)\s+(\w+)([^{]*)\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = headerRe.exec(sdl)) !== null) {
+    const name = m[1]!;
+    const header = m[2]!;
+    const bodyStart = m.index + m[0].length;
+    const body = balancedBody(sdl, bodyStart);
+    headerRe.lastIndex = bodyStart + body.length + 1; // skip past closing brace
+
+    const isExtend = /\bextends\b/.test(header) || /@extends\b/.test(header);
+    const keys: string[][] = [];
+    const keyRe = /@key\s*\(\s*fields:\s*"([^"]+)"\s*\)/g;
+    let k: RegExpExecArray | null;
+    while ((k = keyRe.exec(header)) !== null) keys.push(k[1]!.split(/\s+/).filter(Boolean));
+
+    const fields = parseFields(body);
+    const existing = types.get(name);
+    if (existing) {
+      existing.keys.push(...keys);
+      for (const [fn, fm] of fields) existing.fields.set(fn, fm);
+    } else {
+      types.set(name, { isExtend, keys, fields });
+    }
+  }
+  return types;
+}
+
+/** Extract the balanced `{ ... }` body starting just after an opening brace at `start-1`. */
+function balancedBody(s: string, start: number): string {
+  let depth = 1;
+  let i = start;
+  for (; i < s.length; i++) {
+    const c = s[i];
+    if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) break; }
+  }
+  return s.slice(start, i);
+}
+
+/** Parse field definitions in a type body into name → FieldMeta. */
+function parseFields(body: string): Map<string, FieldMeta> {
+  const out = new Map<string, FieldMeta>();
+  // Each field line roughly: `name(args): Type <directives>` separated by newlines.
+  // We scan line-ish fragments split on top-level commas/newlines.
+  const lines = body.split('\n').map((l) => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    // Strip leading modifiers; capture field name as the first identifier.
+    const nameMatch = /^(\w+)/.exec(line);
+    if (!nameMatch) continue;
+    const name = nameMatch[1]!;
+    const external = /@external\b/.test(line);
+    const provides = matchFields(line, '@provides');
+    const requires = matchFields(line, '@requires');
+    out.set(name, { external, provides, requires });
+  }
+  return out;
+}
+
+function matchFields(line: string, directive: string): string[] | undefined {
+  const re = new RegExp(`${directive}\\s*\\(\\s*fields:\\s*"([^"]+)"\\s*\\)`);
+  const m = re.exec(line);
+  return m ? m[1]!.split(/\s+/).filter(Boolean) : undefined;
+}