graph_weaver 0.7.0 → 0.7.2

data/docs/federation.md

@@ -1,36 +1,31 @@
 # Federation
 
-For an app that is a client of a federated graph, a subgraph in one, or both.
-Two halves: **generating** against a composed supergraph (which mostly means
-"point it at the file and forget"), and the **local router**, which runs a
-stitched query against your own resolvers in-process so specs need no gateway.
-
-GraphWeaver takes any federation artifact — a supergraph, an API schema, a
-subgraph SDL, or a live router — and recognizes which it got.
-`SchemaLoader.load` (and `Client.new(path_or_sdl)`) accept each as an SDL file
-or an introspection dump.
-
-**Which half is yours** depends on what your app does with the graph, and most
-of them are only one:
-
-- **You call the gateway and compose nothing.** [Generating against a
-  supergraph](#generating-against-a-supergraph) and [the local
-  router](#the-local-router) are the whole document for you. Skip
-  [producing a supergraph](#producing-a-supergraph) and [has the supergraph
-  been recomposed?](#has-the-supergraph-been-recomposed) — those are the
-  composer's.
+For an app that is a client of a federated graph, a subgraph in one, or both. Two
+halves: **generating** against a composed supergraph, which mostly means "point it
+at the file and forget", and the **local router**, which runs a stitched query
+against your own resolvers in-process so specs need no gateway. Any federation
+artifact works — a supergraph, an API schema, a subgraph SDL, or a live router;
+`SchemaLoader.load` (and `Client.new(path_or_sdl)`) recognize which they got, as an
+SDL file or an introspection dump.
+
+**Which half is yours** depends on what your app does with the graph, and most apps
+are only one:
+
+- **You call the gateway and compose nothing.** [Generating for a federated
+  graph](#generating-for-a-federated-graph) and [the local
+  router](#the-local-router) are the whole document for you.
 - **You publish a subgraph.** Add [generating against a
-  subgraph](#generating-against-a-subgraph) and `federation:diff`, which is
-  what tells you your change needs a recompose.
-- **You own the supergraph.** All of it, plus [in CI](#in-ci): the checks here
-  compare an app to its own artifacts, and the pre-deploy check against the
-  live graph is `rover`'s.
+  subgraph](#generating-against-a-subgraph) and [a subgraph that calls its own
+  graph](#a-subgraph-that-calls-its-own-graph).
+- **You own the supergraph.** All of it, plus [producing
+  one](#producing-a-supergraph), [`federation:diff`](#has-the-supergraph-been-recomposed)
+  and [in CI](#in-ci).
 
 ## Generating for a federated graph
 
 **Queries go through the gateway?** Generate against the supergraph. It is the
-whole graph in one schema, so every registration matches and there is nothing
-else to decide.
+whole graph in one schema, so every registration matches and there is nothing else
+to decide.
 
 **Calling subgraphs directly?** One graph per subgraph, declared once:
 
@@ -42,289 +37,467 @@ GraphWeaver.graph :billing do
   namespace "Billing"
   register_scalar "Money", Money
 end
-
-GraphWeaver.graph :directory do
-  schema    "directory.graphql"
-  queries   "app/graphql/directory"
-  output    "app/graphql/generated/directory"
-  namespace "Directory"
-  register_scalar "Person.birthday", Date
-end
 ```
 
-One `rake graph_weaver:generate` generates both, and each subgraph is held only
-to the registrations declared for it. (Naming a live subgraph *class* from a
+One `rake graph_weaver:generate` generates every graph, and each subgraph is held
+only to the registrations declared for it. (Naming a live subgraph *class* from a
 Rails initializer takes a lambda — `schema -> { Billing::Schema }` — see
 [getting started](getting_started.md#more-than-one-schema).)
 
 Registrations made at the *top* level still reach every graph, because names
-compose by identity across a graph — `Money` is one Ruby type wherever it
-appears, and `Person` is one entity even though a single subgraph owns
-`birthday`. So a registration a given subgraph doesn't declare is not an error;
-generation warns and carries on. `rake graph_weaver:generate` and `verify` print
-the list once per run, after the files:
+compose by identity across a graph — `Money` is one Ruby type wherever it appears,
+and `Person` is one entity even though a single subgraph owns `birthday`. So a
+registration a given subgraph doesn't declare is not an error; generation warns
+and carries on, printing the list once per run:
 
 ```
 register_scalar("Money") matches no scalar in Billing::Schema — a typo, or a registration for another schema
 ```
 
-`GraphWeaver.unmatched_registrations` is that same list as data, for a Rakefile
-or a spec that would rather gate on it than read it. Moving a registration into
-the graph block that needs it is what makes those lines go away.
+`GraphWeaver.unmatched_registrations` is that same list as data, and moving a
+registration into the graph block that needs it is what makes the lines go away.
+Entity fields work the same way: a subgraph carrying `Person` for its `@key` alone
+sees a top-level `register_scalar("Person.birthday", Date)` as a field it doesn't
+own — a warning, not a failure. What a subgraph *can* disprove still fails
+generation: a name it declares as something else, or a coordinate whose field it
+declares as a composite. Neither is redeemable by any schema in the graph.
 
-This holds for entity fields too, which is the case that would otherwise bite:
-every subgraph referencing an entity declares it, so a subgraph carrying
-`Person` for its `@key` alone sees a top-level
-`register_scalar("Person.birthday", Date)` as a field it doesn't own — a
-warning, not a failure.
+### Generating against a supergraph
 
-What a subgraph *can* disprove still fails generation: a name it declares as
-something else (`register_scalar("Species")` where `Species` is an enum), and a
-coordinate whose field it declares as a composite. Neither is redeemable by any
-schema in the graph.
+A supergraph SDL works as-is. On load, GraphWeaver strips the composition
+machinery — the synthetic `join__*`/`link__*` types and directive definitions, and
+every `@join__*`/`@link` application on the real types — so codegen sees the
+merged graph's ordinary type shapes. Field shapes (nullability, args, enums,
+inputs) are identical to the API schema, so your generated structs are correct.
 
-## Producing a supergraph
+**Which names count as machinery is read off the schema**, not a fixed list.
+Federation namespaces itself through [`@link`](https://specs.apollo.dev/link/v1.0/)
+(v2) or [`@core`](https://specs.apollo.dev/core/v0.2/) (v1), and those declarations
+are applied as written: the spec URL's name segment gives the namespace
+(`https://specs.apollo.dev/join/v0.3` → `join__`), `as:` renames it, `import:`
+binds names into the root namespace. So a fed 2.5+ graph's `@requiresScopes` /
+`@policy` / `@context` machinery strips the same way `join__` does, a renamed
+`@inaccessible` still hides what it marks, and v1 supergraphs load identically. A
+schema that declares nothing still gets the `join__`/`link__`/`core__` floor.
+
+A supergraph is also a **superset** of the API schema: it carries elements the
+public API hides, marked `@inaccessible`. Loading strips every `@inaccessible`
+element and cascades — a field, argument, union member or interface referencing a
+removed type goes too, and a type left empty is removed in turn — so codegen
+validates against what clients can actually query, with no need for Apollo's JS
+tooling to subtract the API schema first. (The derivation is diffed against
+Apollo's own `composeServices` + `toAPISchema()` in
+[`spec/integration/api_schema_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/integration/api_schema_spec.rb).)
+Two bounds: the directive is matched by the **local name it was linked under**, so
+an `import:` alias subtracts what that alias marks; and the subtraction runs **only
+on the supergraph path** — plain and subgraph SDL are taken at face value.
+Directives that hide nothing keep their field: `@requiresScopes` / `@policy` /
+`@authenticated` enforce at runtime, `@tag` / `@requires` / `@provides` /
+`@external` are metadata.
 
-GraphWeaver consumes a supergraph; composing one is Apollo's job. Composition
-takes one SDL file per subgraph, so the question is where each file comes from.
+### Contracts and variants
 
-**Yours.** [`apollo-federation`](https://github.com/Gusto/apollo-federation-ruby)
-is the gem that makes a graphql-ruby schema a subgraph — `@key`,
-`resolve_reference`, the directives — and it adds `federation_sdl` to the schema
-class, which prints exactly what a composer wants:
+A contract variant is a supergraph built from the same subgraphs with some
+coordinates filtered out: a subgraph marks them `@tag(name: "internal")`, and
+GraphOS builds a second supergraph where everything carrying that tag is
+`@inaccessible`. Nothing special is needed to generate against one — the
+subtraction above is exactly what makes it the narrower schema its clients see. A
+query selecting an internal-only field generates against **internal** and, against
+**public**, fails codegen with a `QueryValidationError` naming the field, because
+the load subtracted it before validation saw it. That is the guarantee: a client
+generated against the variant it calls cannot select something the router will
+reject.
+
+One app calling two variants is
+[two graphs](getting_started.md#more-than-one-schema), each with its own `schema`,
+`queries`, `output` and a `namespace` if any module name would collide; a variant
+is mechanically just another graph. But **nothing cross-checks the variant you
+generated against with the endpoint you call** — generate against internal, deploy
+against public, and every check stays green until a live 400 — and
+**`federation:diff` can't tell the variants apart** either, since it reads the
+routing table and `@inaccessible` is a directive the table doesn't carry. Point
+each graph at the variant it actually calls.
+
+## The local router
+
+Specs for a federated app have a bad choice: fake the whole graph, or boot a
+gateway. `Testing::Router` is the third one. It takes the composed supergraph and
+the Ruby schema classes serving its subgraphs, plans the query, and satisfies the
+[client contract](transports.md) — so a generated module runs against your **real
+resolvers**, in-process, with no gateway, no node and no sockets. It is not a mock:
+your resolvers run, which is the whole point.
+
+In rspec that's the [`graphql: :router`](testing.md#a-federated-graph--graphql-router)
+tag and there is nothing to pass — the tag builds it, once for the suite. It finds
+the supergraph where you have already said it is: the schema a
+[graph](getting_started.md#more-than-one-schema) declares when that schema is
+composed, else `Testing.config.router = { supergraph: … }` if you named one
+there, else the committed dump when *that* is, else the dump your own client was
+built from (`GraphWeaver.new("supergraph.graphql")` keeps its path). Two graphs
+may name one supergraph; two naming different ones is refused rather than picked
+between.
+Outside rspec, build it yourself:
 
 ```ruby
-File.write("supergraph/accounts.graphql", Accounts::Schema.federation_sdl)
+GraphWeaver.client = GraphWeaver::Testing::Router.new(
+  supergraph: Rails.root.join("supergraph.graphql"),
+  context: { current_user: user },
+)
 ```
 
-One ordering trap in that gem: declare `orphan_types` **before** `query` in the
-schema class. It computes the `_Entity` union when `query` is called, so an
-`orphan_types` after it drops those types from the printed SDL and from
-`_entities` with no error at all, while `Schema.types` still lists them.
+`context:` reaches every subgraph, because every subgraph is a Ruby call here. A
+request's **headers** don't: the gateway and the Apollo Router both start a subgraph
+call with none of the client's unless you configure forwarding, so don't let a spec
+conclude an auth header arrived somewhere it wouldn't.
 
-`orphan_types` is also what an **extend-only type** needs — one this subgraph
-contributes fields to but never returns from its own `Query`, the shape a
-warehouse/inventory split produces. Nothing reaches it from a root field, so
-graphql-ruby never visits it, `federation_sdl` never prints it, and the fields
-simply don't compose: no error from graphql-ruby, none from apollo-federation,
-and the first sign is a supergraph missing fields you wrote. Name every such
-type in `orphan_types`, before `query`.
+`router.trace` records the fetches made since the last `reset_trace`, in order
+(subgraph, query, variables); the same lines go to `GraphWeaver.logger` at
+`:debug`, and the rspec tag resets it before each example. It **accumulates across
+executes**, because the question worth asking is which subgraphs a code path
+touched. But the count is the **local router's plan, not the gateway's**: the data
+is faithful — a real gateway answers byte-identically, or this refuses — while a
+[`@requires` prefetch](#what-it-plans) is still its own call where a gateway merges
+it into the read beside it. So assert on a **bound**
+(`expect(router.trace.size).to be <= 8`) or on the **subgraph set**
+(`router.trace.map { _1[:subgraph] }.uniq`): both move when an N+1 appears, and
+neither pins a number production doesn't have.
 
-**Everyone else's.** From the team that runs it: a file they publish, `rover
-subgraph fetch` against their endpoint, or your schema registry.
+The router hands back a result hash *above* the wire, so the transport your app
+ships never runs. When that transport is the thing under test — a caller tag, an
+APM header, mTLS — [`graphql: :wire`](testing.md#over-the-wire--graphql-wire) serves
+this same router at the endpoint your client posts to and leaves your client in
+place: real serialization, the same plan over the same resolvers, `from_h` over the
+server's own bytes, and a `context:` proc reading the headers that arrived. It
+refuses exactly what the router refuses — a hop, not a capability — and the hop is
+served through webmock, so that tag needs `require "webmock/rspec"`.
+
+**[`examples/federation.rb`](https://github.com/dpep/graph_weaver/blob/main/examples/federation.rb)**
+is the whole shape in one runnable file, and
+[`spec/router_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/router_spec.rb)
+is the exhaustive reference — every plan shape and every refusal, each as a named
+example.
 
-**Composed.** [`rover supergraph compose`](https://www.apollographql.com/docs/rover/commands/supergraphs)
-reads a config naming each subgraph's routing url and SDL file, and prints the
-supergraph to stdout:
+### What it refuses
 
-```yaml
-# supergraph-config.yaml
-federation_version: =2.14.4   # rover wants an exact one
-subgraphs:
-  accounts:
-    routing_url: https://accounts.internal/graphql
-    schema: { file: ./accounts.graphql }
-```
+Everything it can't plan **faithfully** raises `GraphWeaver::Testing::Unplannable`
+(a `GraphWeaver::Error`), at plan time, before any subgraph runs — so a refusal is
+never a half-executed query. A double that approximated the rest of Apollo's
+planner would let a test pass on an answer production disagrees with, which is the
+most expensive thing this library can produce. Each refusal names the coordinate
+that stopped it and what to do.
 
-```sh
-rover supergraph compose --config supergraph-config.yaml \
-  --elv2-license accept > supergraph.graphql
-```
+Every category, in the words `Unplannable#label` uses (`#category` is the matching
+symbol):
 
-`--elv2-license accept` accepts the Elastic license on the composition binary
-rover downloads; without it rover asks, and a CI job has nobody to answer.
-Commit the result — from here it is an ordinary schema dump, and
-[`federation:diff`](#has-the-supergraph-been-recomposed) is what catches it
-going stale.
+| Refusal | Why |
+|---|---|
+| no `@key` to cross the boundary on | an entity fetch sends a representation built from a `@key`; with none there is nothing to send |
+| an abstract type the supergraph doesn't break down | bucketing needs the concrete types a subgraph answers a union or interface with, and `@join__unionMember`/`@join__implements` is where a supergraph records that. A composition old enough to carry neither leaves nothing but a guess |
+| an `@interfaceObject` the routing table can't attribute | one subgraph resolves a whole interface's implementations, so the supergraph never says which subgraph answers each of its fields. Per query, not per graph: a query that doesn't reach the type plans as if the directive weren't there |
+| a `@fromContext` argument no fetch here can supply | federation 2.8's `@context`/`@fromContext` fills a field's argument from a selection on an ancestor, and only the gateway that planned the fetch knows what to put there — a subgraph's own resolver never fills one, so this is refused on any path, including the one where a single subgraph answers the whole query. Per query, like `@interfaceObject` |
+| a response delivered in more than one payload | `@defer`/`@stream` stream the rest of the answer over a multipart body after the first payload, and this router answers in one. Refused by name rather than left to validation, so the guarantee doesn't rest on whether the composed schema happens to declare the directive |
+| a progressive `@override` still rolling out | federation 2.7's `@override(label:)` leaves *both* subgraphs resolving the field — the gateway splits traffic per request by the label's rule, and a local router can't evaluate a rollout percentage. Finish the rollout (drop the label) and composition drops the losing copy, which plans normally |
+| a `@requires` whose field set names another `@requires` field | the router satisfies a `@requires` with one fetch, so it can't first satisfy that field's own requirement |
+| a nested field set no one fetch can build | a nested field set crosses as one object, so one fetch has to answer the whole of it. Nesting itself is fine — this is the set whose fields are split across subgraphs, so the object would arrive half-built from each |
+| `@skip`/`@include` on both a fragment and its field | one selection can't carry two conditions of the same name. Spell the condition once |
+| an alias shadowing an injected `@key` | a fetch carries the `@key` it crosses on under a response key — Apollo under the field's own name, the local router under a reserved one — and an alias spelling either claims a key the fetch needs |
+| a mutation's root fields span subgraphs | root mutation fields run in series, and splitting them across subgraphs would run them in whatever order the plan happened to. Sharing one subgraph they're fine, stitching below them and all. Query roots are independent, so those are always fine |
+| the routing table names no subgraph | nothing can route a field the supergraph doesn't place |
+| a subgraph nothing here serves | it's served by another process, so there is nothing here to ask — unless you [fake it](#a-supergraph-only-partly-local) |
+| introspection mixed with data | introspection is answered from the composed API schema and data from the subgraphs, and the two can't be merged. Split them into two operations |
+| the document isn't one operation | pass `operation_name:` naming one of them |
+| not a query or a mutation | the router plans against the composed schema's query and mutation roots; a subscription has neither |
+| a fragment the document never defines | define it, or point the query at the file that does — validation rejects it first, so what you actually get back is an `errors` response |
+| a federation construct the routing table doesn't read | an incomplete table makes every answer about this supergraph a guess. The one refusal raised **at construction**, before a single query |
+| nested deeper than the router walks | past the walk's depth limit, which validation would have rejected first |
 
-Already on a node toolchain? `@apollo/composition` composes in-process with no
-rover install. The suite does it that way, and its two files are the whole loop
-end to end — schema classes, `federation_sdl`, composed supergraph:
-[`recompose.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/support/federation/recompose.rb)
-driving [`compose.mjs`](https://github.com/dpep/graph_weaver/blob/main/spec/support/federation/compose.mjs).
+A document that fails ordinary GraphQL validation never reaches any of this: it
+gets the same `errors` response a plain client gets. The construction-time refusal
+is worth planning around, though — a `@join__` directive the table doesn't read
+refuses `Router.new` for the **whole graph**, so one team adopting a newer
+federation feature is an upgrade-timing event for every team that tests with
+`:router`. A subgraph two loaded schemas both fit raises a `ConfigurationError`
+instead, being a wiring mistake rather than a query the router declines, but it
+raises where every other one does: on the query that reaches the subgraph.
 
-## Generating against a supergraph
+### Which schema serves which subgraph
 
-A supergraph SDL works as-is. On load, GraphWeaver strips the composition
-machinery — the synthetic `join__*`/`link__*` types and directive definitions,
-and every `@join__*`/`@link` application on the real types — so codegen sees the
-merged graph's ordinary type shapes with no federation plumbing in
-`schema.types`. Field shapes (nullability, args, enums, inputs) are identical to
-the API schema, so your generated structs are correct.
+`subgraphs:` is optional. Left out, each one is **derived from what the loaded
+schemas define**: a schema serves subgraph `s` when it defines every type and field
+the routing table says `s` resolves, plus at least one coordinate attributed to
+that subgraph **alone** (what two subgraphs share can't tell them apart). That's
+evidence rather than a guess, and a wrong guess would point a suite at the wrong
+resolvers and still pass — so exactly one match is used. Neither other outcome
+refuses at construction, since which classes are loaded is not a fact about the
+query you're running: **no** match means the subgraph is served somewhere else
+(below), and **two** means detection can't say which class serves it. Both are
+refused by the query that reaches the subgraph's fields, each naming its own fix —
+for two, `subgraphs: { "reviews" => App::Reviews::Schema }` pins it, and
+`router.ambiguous` lists them.
 
-**Which names count as machinery is read off the schema**, not a fixed list.
-Federation namespaces itself through [`@link`](https://specs.apollo.dev/link/v1.0/)
-(v2) or [`@core`](https://specs.apollo.dev/core/v0.2/) (v1), and those
-declarations are applied as written: the spec URL's name segment gives the
-namespace (`https://specs.apollo.dev/join/v0.3` → `join__`), `as:` renames it,
-`import:` binds names into the root namespace. So a fed 2.5+ graph's
-`@requiresScopes` / `@policy` / `@context` machinery strips the same way
-`join__` does, a renamed `@inaccessible` still hides what it marks, and v1
-supergraphs (`@core` + `@join__owner`) load identically. A schema that declares
-nothing still gets the `join__`/`link__`/`core__` floor.
-
-### `@inaccessible`
-
-A supergraph is a **superset** of the API schema: it carries elements the public
-API hides, marked `@inaccessible`. You'll meet the directive rolling out a change
-to a **shared type** — add the field to one subgraph marked `@inaccessible` so
-composition doesn't require every subgraph to have it yet, roll it out, then drop
-the directive to publish it. Apollo **contracts** use the same directive the
-other way round, and get a section of their own [below](#contracts-and-variants).
-
-Loading strips every `@inaccessible` element and cascades: a
-field/argument/union-member/interface referencing a removed type goes too, and a
-type left empty is removed in turn. So codegen validates against what clients can
-actually query, with no need for Apollo's JS tooling to subtract the API schema
-first — feed it the raw supergraph and you get the router's contract. The
-derivation is diffed against Apollo's own `composeServices` + `toAPISchema()` in
-[`spec/integration/api_schema_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/integration/api_schema_spec.rb).
-
-Two bounds. The directive is matched by the **local name it was linked under**, so
-an `import:` alias subtracts what that alias marks. And the subtraction runs
-**only on the supergraph path** — plain and subgraph SDL are taken at face value,
-where `@inaccessible` stays a directive and its fields stay queryable. Directives
-that hide nothing keep their field and are ignored: `@requiresScopes` / `@policy`
-/ `@authenticated` enforce at runtime, `@tag` / `@requires` / `@provides` /
-`@external` are metadata.
+Name them yourself when you'd rather have the wiring committed, or when detection
+can't settle it — including partially, with the rest derived. Either way the map is
+**checked** at construction, so a swapped pair fails naming what's missing rather
+than surfacing as a mystery three fetches later:
 
-### Contracts and variants
+```
+subgraphs["accounts"] is Products::Schema, which doesn't define Query.me,
+Query.user, Query.users, User, User.email and 1 more — the supergraph says
+accounts resolves them. Did two entries get swapped?
+```
 
-A contract variant is a supergraph built from the same subgraphs with some
-coordinates filtered out: a subgraph marks them `@tag(name: "internal")`, and
-GraphOS builds a second supergraph where everything carrying that tag is
-`@inaccessible`. Nothing special is needed to generate against one — it is a
-supergraph, and the `@inaccessible` subtraction above is exactly what makes it
-the narrower schema its clients see:
-
-```graphql
-# reviews, the subgraph
-type User @key(fields: "id") {
-  id: ID!
-  supportTier: String! @tag(name: "internal")
+Detection only sees what's **loaded**, and in Rails an autoloaded schema isn't until
+something references it — which is why an unmatched subgraph reads as absent. The
+`federation:*` rake tasks eager-load the app for you; a spec suite is your own
+`config.eager_load`, which Rails leaves off outside CI. To see what detection sees,
+and get a map to paste:
+
+```
+$ rake graph_weaver:federation:subgraphs
+subgraphs: {
+  "accounts" => Accounts::Schema,  # matched: defines Query.me, Query.user, Query.users
+  "products" => Products::Schema,  # matched: defines Product.name, Product.price, Product.weight
 }
 ```
 
-```graphql
-# the internal variant's supergraph — the tag rides along, nothing is hidden
-supportTier: String! @join__field(graph: REVIEWS)
-# the public variant's supergraph — what the contract build adds
-supportTier: String! @inaccessible @join__field(graph: REVIEWS)
+A row nothing matched comes back `nil`, naming the coordinates it looked for —
+that's the map to fill in, or the subgraph that lives elsewhere.
+
+### A supergraph only partly local
+
+The usual migration shape: the supergraph is composed from several services and
+only **some** of them run in your process. Requiring a Ruby schema for the rest
+would refuse the whole suite over fields most of your queries never touch, so a
+subgraph nothing here defines is **absent**, and the router builds and runs anyway.
+Absence costs you exactly the queries that reach into it:
+
+```ruby
+router.absent                                            # => ["shipping"]
+router.execute("{ me { username reviews { body } } }")   # real data, as always
+router.execute("{ shipments { carrier } }")              # GraphWeaver::Testing::Unplannable
+```
+
+That refusal is a plan-time one like every other, so nothing has executed when it
+raises, and it names the subgraph, the field that reached for it, and both ways out
+— name a schema for it, or fake it:
+
+```ruby
+subgraphs: { "shipping" => :fake }   # any other absent subgraph still refuses
 ```
 
-Generate a query selecting `supportTier` against **internal** and it generates;
-against **public**, codegen refuses at the boundary —
-`QueryValidationError` naming `supportTier`, because the load subtracted the
-field before validation saw it. That is the guarantee: a client generated
-against the variant it calls cannot select something the router will reject.
-
-Two things to know, both of which bit this document into existence:
-
-- **`federation:diff` can't tell the variants apart.** It reads the routing
-  table, and `@inaccessible` is a directive the table doesn't carry, so both
-  variants report "matches the schemas here" against the same subgraphs. That
-  is the same [directive blindness](#has-the-supergraph-been-recomposed) as
-  everywhere else, not a contract-specific hole.
-- **Nothing cross-checks the variant you generated against with the endpoint
-  you call.** `verify`, `queries:check` and `generate` take the schema as
-  given; generate against internal, deploy against public, and every check
-  stays green until a live 400. Point each graph at the variant it actually
-  calls, and let the graph declaration be the single place that says so.
-
-One app calling two variants is [two graphs](getting_started.md#more-than-one-schema)
-— each with its own `schema`, `queries`, `output` and a `namespace` if any
-module name would collide. There is no contract-specific spelling; a variant is
-mechanically just another graph.
+If the subgraph *is* here and detection just couldn't see it — a Rails schema class
+nothing has referenced yet — loading it is the fix, which in a spec suite means
+`config.eager_load = true`. `=> :fake` is the other one: mid-migration, letting an
+absent subgraph answer with schema-correct fabricated data exercises the rest of
+the query. It speaks the whole subgraph contract, `_entities(representations:)`
+included, so it works under a stitched fetch as well as at a root field.
+
+Refusing stays the default, and the opt-in is **per subgraph** on purpose: silently
+substituting invented data is the failure mode this library keeps designing
+against. For the same reason faking is **loud** — every faked fetch is marked
+`faked: true` in `router.trace` and logged at `:warn`, `router.faked` lists them,
+and `router.inspect` shows what's served, faked and absent. Values come from the
+same engine as [`graphql: :fake`](testing.md#fabricated-data--graphql-fake), and
+`fake:` says how they fabricate: the [pins](testing.md#pins) and options a fake
+takes, in one hash, on `Router.new` outside rspec, on `Testing.config.router` for
+the suite, or on `graphql_router(fake: { "Shipment.carrier" => "UPS" })` for the one
+example that cares. One `fake:` covers every faked subgraph, since a pin's key
+already says which type it means, and the router is still built once for the suite —
+only the options last one example.
 
-### The routing table
+## Generating against a subgraph
 
-Stripping the machinery answers "what does this graph look like". The other
-question a supergraph answers is "who resolves what", and
-`SchemaLoader.routing_table` keeps that side rather than discarding it:
+A raw subgraph SDL — `rover subgraph fetch`, `_service { sdl }`, or the `.graphql`
+in a service repo — loads too. It applies `@key`/`@external`/`@shareable`/… without
+declaring them (federation v1 leaves them implicit, v2 imports them via `@link`),
+so the missing definitions are supplied on load; anything the file declares itself
+wins. Whatever the `@link` header says the directives are called is what's supplied
+— the bare `@key`, the namespaced `@federation__key`, or `@primaryKey` from
+`import: [{name: "@key", as: "@primaryKey"}]`. The header itself is read and then
+dropped: it describes the file, not the graph. The federation directives generate
+no code either way — codegen is query-driven.
+
+Reach for this when the subgraph is what you have, or to type an `_entities` query.
+But a subgraph is one service's slice of the graph, and its field shapes are not
+always the composed ones (an `@external` field is a reference, not something that
+subgraph serves) — for a client of the whole graph, feed the composed artifact.
+
+### `_entities`
+
+Every subgraph serves the entity resolver
+`_entities(representations: [_Any!]!): [_Entity]!`, and **no subgraph SDL contains
+it**: `_service { sdl }` and `rover subgraph fetch` print the *published* schema,
+where the plumbing is implicit. So it's supplied on the subgraph path — `_Any`,
+`_Service`, and an `_Entity` union over the file's own `@key`'d types — the same
+way the `@key`/`@external` definitions are. A file that declares its own keeps it.
+
+The read side is a normal union selection; `alias:` turns the single-entity case
+into a clean accessor (see
+[flat accessors](generated_modules.md#flat-accessors-with-alias)):
 
 ```ruby
-table = GraphWeaver::SchemaLoader.routing_table("supergraph.graphql")
+GraphWeaver.extend_type("Query", alias: { entity: "_entities.first" }, optional: true)
+```
 
-table.subgraphs                                # => ["accounts", "products", "reviews"]
-table.owners("Product", "shippingEstimate")    # => ["reviews"]
-table.owners("User", "username")               # => ["accounts"] — the @external copy isn't an owner
-table.keys("User", "accounts")                 # => [["id"]]
-table.field("Product", "shippingEstimate").requires  # => "price weight"
-table.possible_types("Purchasable", "products")      # => ["Bundle", "Product"]
+The **input** side is generated. A representation must carry `__typename` and
+satisfy one of the entity's `@key` field sets — both hard requirements of the
+subgraph spec, and neither expressible in a bare `[_Any!]!` — so a query selecting
+entities gets a `Representations` builder per entity it reaches, typed from the
+`@key` directives:
+
+```ruby
+UserQuery::Representations.user(id: "1")
+# => {"__typename" => "User", "id" => "1"}
+
+UserQuery.execute(reps: [UserQuery::Representations.user(id: "1")])
+```
+
+Key field sets are selection sets, so they're parsed as such:
+
+| `@key(fields:)` | Builder |
+|---|---|
+| `"id"` | `Representations.user(id: "1")` |
+| `"upc sku"` (compound) | `Representations.product(upc: "u", sku: 42)` |
+| `"id organization { id }"` (nested) | `Representations.listing(id: "1", organization: { id: "o" })` |
+| `"id lineItems { sku }"` over a `[LineItem!]!` | `Representations.order(id: "1", line_items: [{ sku: "a" }, { sku: "b" }])` |
+| `"id"` **and** `"serial"` (alternatives) | `Representations.variant(id: "1")` *or* `(serial: "s")` |
+
+A key field the schema declares as a **list** takes a list, and stays one on the
+wire — a single object there would describe an entity that doesn't exist. A type
+with one `@key` types its fields as **required kwargs**, so an incomplete
+representation is an `srb tc` error rather than a round trip; what a sig can't say
+is checked at runtime and raises `GraphWeaver::InputError` naming the type and the
+field:
+
+```
+Variant representation satisfies none of its @keys — supply "id", or "serial"
+Listing representation is missing @key "organization.id"
+Product representation sku: expected an Int, got "forty-two"
 ```
 
-Subgraphs are named the way `@join__graph(name:)` names them — the strings a
-router config and `rover` use, not the SDL's uppercase enum spelling. A `@key`
-field set comes back as dotted paths (`"id organization { id }"` → `["id",
-"organization.id"]`), so a nested one is recognizable by its shape. A field
-with no `@join__field` at all lives wherever its type does; that omission is
-how the composer says "everywhere". `possible_types` answers the abstract
-side — the concrete types one subgraph can answer a union or interface with,
-from `@join__unionMember`/`@join__implements` — and `nil` where the supergraph
-doesn't say, which is a different fact from "none".
-
-A `@join__` directive the table hasn't been taught lands in `#unsupported`
-rather than being skipped, and callers refuse on a non-empty list: a table that
-silently ignores half a spec version answers confidently and wrongly.
-`#interface_objects` is the one construct kept out of that list
-(`{"Media" => ["catalog"]}`), because it's a fact about one *type* rather than
-about the table — the router refuses the queries that reach it and plans the rest.
-
-The table is what [`Testing::Router`](#the-local-router) plans against, and it's
-a reasonable read on its own — "which subgraph owns this field" is the sentence a
-good error message wants. So when the schema dump is a composed supergraph,
-`rake graph_weaver:queries:check` brands each validation error with the subgraphs
-behind the type it names:
+Key fields take the same loose input an `execute` kwarg does, so a `params[:sku]`
+String converts to the `Int` the `@key` declares. A `@key` field whose name a
+generated method can't take as a kwarg — `class`, `hash`, or a Ruby keyword — takes
+a trailing underscore, the same one its prop took, and still sends the schema's
+spelling on the wire: a subgraph's `@key` field is not yours to rename, so weaver
+renames its own side rather than refusing. Only the declared key fields reach the
+wire, builders are emitted only for the entities a query actually selects, and a
+`@key(..., resolvable: false)` builds nothing, since it declares a key this subgraph
+does *not* answer for. Every shape above is a named example in
+[`spec/federation_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/federation_spec.rb).
 
+**Off-label**, a subgraph that generates against its *own* SDL gets a typed gate for
+a raw incoming representation, before `resolve_reference` sees one — with two
+bounds: a single-`@key` builder takes required kwargs, so splatting a hash that is
+short a field raises Ruby's `ArgumentError` rather than an `InputError`, and where
+two key sets overlap the first fully supplied one wins silently.
+
+## A subgraph that calls its own graph
+
+A subgraph resolver that reaches for the composed graph — a cross-cutting report, a
+field easier to answer through the gateway than by hand — is an ordinary thing to
+write and the one shape **every** test tier is blind to, because each of them
+intercepts exactly that call. Under `:in_process` the client points back at the
+subgraph under test, so the loopback runs against a schema with none of those root
+fields. Under `:router` it re-enters the router it is already inside. Under `:wire`
+it is a second POST to the endpoint WebMock has stubbed. All three answer; none of
+them is the address production will use.
+
+So give the call its own graph, beside the one for the subgraph itself, with a
+client distinct from the one the app uses to reach the gateway from outside:
+
+```ruby
+# config/initializers/graph_weaver.rb — beside GraphWeaver.graph :reviews,
+# whose client is Reviews::Schema
+GraphWeaver.graph :platform do
+  schema    "app/graphql/supergraph.graphql"
+  queries   "app/graphql/platform/queries"
+  output    "app/graphql/platform/generated"
+  client    GraphWeaver.new(ENV.fetch("PLATFORM_GRAPHQL_URL"))
+  namespace "Platform"
+end
 ```
-app/graphql/queries/product.graphql
-  4:5  Field 'dimensions' doesn't exist on type 'Product' (products, reviews)
+
+The resolver then calls `Platform::ProductsQuery.execute!` instead of
+`GraphWeaver.client`, which buys three things. The target is named where someone
+deploying can see it (`rake graph_weaver:graphs` prints it, and `ENV.fetch` fails at
+boot rather than at the first request). A helper stands in for one graph at a time,
+so a spec has to say `graphql_router(graph: :reviews)`, and can't cover the
+loopback by accident. And with two graphs `GraphWeaver.client` under a mode refuses
+by name rather than reaching a real endpoint, so a stray call is loud.
+
+What none of that gives you is proof the url resolves. That is a smoke request
+against a running gateway, and it is the only thing that will.
+
+## Producing a supergraph
+
+GraphWeaver consumes a supergraph; composing one is Apollo's job. Composition takes
+one SDL file per subgraph, so the question is where each file comes from.
+
+**Yours.** [`apollo-federation`](https://github.com/Gusto/apollo-federation-ruby)
+is the gem that makes a graphql-ruby schema a subgraph — `@key`,
+`resolve_reference`, the directives — and it adds `federation_sdl`, which prints
+exactly what a composer wants:
+
+```ruby
+File.write("supergraph/accounts.graphql", Accounts::Schema.federation_sdl)
 ```
 
-`Product.dimensions` says what broke; `(products, reviews)` says whose code to
-look at. `check_queries` carries the same list as a `"subgraphs"` key. A plain
-schema has no routing table, so nothing changes for it.
+Two traps in that gem. Declare `orphan_types` **before** `query`: it computes the
+`_Entity` union when `query` is called, so an `orphan_types` after it drops those
+types from the printed SDL and from `_entities` with no error at all. That is also
+what an **extend-only type** needs — one this subgraph adds fields to but never
+returns from its own `Query` — since nothing reaches it from a root field, so
+`federation_sdl` never prints it and the fields don't compose. Second, it writes its
+directives **un-imported** (`@federation__key`), while `@apollo/composition`
+(2.14.4) asserts on the short spelling: get a `fields:` argument wrong and instead
+of "Cannot query field `nosuchfield` on type `User`" you get `Error: Unexpected
+element: federation__key` and a JS stack. Only the diagnosis is lost — adding
+`@link(import: ["@key", "@provides"])` gets the real message back.
+
+**Everyone else's.** From the team that runs it: a file they publish, `rover
+subgraph fetch` against their endpoint, or your schema registry.
 
-### Has the supergraph been recomposed?
+**Composed.** [`rover supergraph compose`](https://www.apollographql.com/docs/rover/commands/supergraphs)
+reads a config naming each subgraph's routing url and SDL file, and prints the
+supergraph to stdout:
 
-A committed supergraph is a snapshot of a composition. Change a subgraph and
-skip the recompose and it quietly describes a graph that no longer exists —
-the failure that bites a federated app mid-migration, and the one the other
-checks don't ask about. `graph_weaver:verify` asks whether the generated Ruby
-is fresh, `schema:diff` whether whatever your dump came from has drifted,
-`queries:check` whether drift broke a query. This asks whether the supergraph
-still describes your subgraphs:
+```yaml
+# supergraph-config.yaml
+federation_version: =2.14.4   # rover wants an exact one
+subgraphs:
+  accounts:
+    routing_url: https://accounts.internal/graphql
+    schema: { file: ./accounts.graphql }
+```
 
 ```sh
-rake graph_weaver:federation:diff
+rover supergraph compose --config supergraph-config.yaml \
+  --elv2-license accept > supergraph.graphql
 ```
 
-**Every `federation:*` task finds the supergraph the same way: it runs once per
-declared graph whose schema is a composed one, and heads each report with that
-graph's name.** An app that wrote `GraphWeaver.graph(:accounts) { schema
-"app/graphql/accounts/supergraph.graphql" }` has already said where its
-supergraph is, and a graph that is in none — a plain API schema, a live schema
-class — is simply not a subject for these tasks. A single-schema app whose
-committed dump is a composed supergraph is that one graph, unnamed, and its
-output says nothing about graphs at all — until it declares a second graph
-beside it, at which point it has to name the first one too
-([why](getting_started.md#more-than-one-schema)). `SUPERGRAPH=supergraph.graphql`
-overrides all of that for one run.
-
-`SUPERGRAPH=` reaches the `federation:*` tasks and **nothing else**: every other
-task reads the schema its graph declares, and one pointed at an ad-hoc
-supergraph would collapse a multi-graph app into a single unnamed graph — which
-for `generate` means pruning the generated files of every graph that graph
-didn't cover. So they refuse it rather than ignore it, which is what
-`SUPERGRAPH=… rake graph_weaver:queries:check` used to do while reporting every
-query valid. To check queries against a supergraph, declare it:
-`GraphWeaver.graph(:api) { schema "supergraph.graphql" }`.
+`--elv2-license accept` accepts the Elastic license on the composition binary rover
+downloads; without it rover asks, and a CI job has nobody to answer. Commit the
+result — from here it is an ordinary schema dump, and
+[`federation:diff`](#has-the-supergraph-been-recomposed) is what catches it going
+stale. Already on a node toolchain? `@apollo/composition` composes in-process with
+no rover install; the suite does it that way, in
+[`recompose.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/support/federation/recompose.rb)
+driving [`compose.mjs`](https://github.com/dpep/graph_weaver/blob/main/spec/support/federation/compose.mjs).
+
+## Has the supergraph been recomposed?
 
-It reads the routing table and the subgraph schemas loaded in this process —
-**no network** — and exits non-zero on drift, so CI can gate on it ([in
-CI](#in-ci)):
+A committed supergraph is a snapshot of a composition. Change a subgraph and skip
+the recompose and it quietly describes a graph that no longer exists — the failure
+that bites a federated app mid-migration, and the one the other checks don't ask
+about. `verify` asks whether the generated Ruby is fresh, `schema:diff` whether
+whatever your dump came from has drifted, `queries:check` whether drift broke a
+query. This asks whether the supergraph still describes your subgraphs, reading the
+routing table and the subgraph schemas loaded in this process — **no network** —
+and exiting non-zero on drift, so CI can gate on it:
 
 ```
+$ rake graph_weaver:federation:diff
 supergraph.graphql: 1 stale, 1 shape, 1 not composed in (checked 1 of 3 subgraphs)
 
 stale — the supergraph carries these, no schema here defines them (recompose):
@@ -344,160 +517,124 @@ not checked — answered with fabricated data:
 ```
 
 Three kinds, because they mean different things: **stale** is "recompose",
-**shape** is "recompose" for a field neither side dropped, and **not composed
-in** is "publish the subgraph". Stale and shape name the subgraph the
-supergraph blames — whose code to look at, whose team to talk to. Field-set
-comparison is deliberately looser than equality, since a subgraph carries
-plumbing (`_entities`, `_service`) no supergraph has and a field can
-legitimately sit in more than one subgraph (`@external` copies, `@shareable`) —
-so one candidate schema agreeing settles it.
-
-**What is compared is a coordinate's presence and its type, and nothing else.**
-`Warehouse.code` going from `String!` to `ID!` under a committed composition is
-the shape row above; the `@key` it is part of, a field's arguments, its
-directives, and everything a type says about itself beyond its fields are not
-read, and a change to any of them still reports clean. The one asymmetry worth
-knowing is an `@override` migration: a supergraph
-published *ahead* of the code is caught (the old side's field is `stale`), but
-code ahead of the supergraph — the new side declaring the field with
-`@override` before the recompose — is not, because both sides carry the field
-and its type, and only the `@override` marker, which lives in
-apollo-federation's own bookkeeping rather than in the schema this reads, says
-ownership is moving. Recompose and the report catches up; until then it is the
-one drift this check can't see. The check compares **schema objects**, not SDL
-text, so how a subgraph spells its directives — `@key`, `@federation__key`, or a
-name it imported them under — can't affect what it reports.
-
-**Finish an `@override` migration from the old side.** Once the new owner
-resolves the field, the original owner's copy is dead code that composition
-still reads — so deleting the *new* side's `@override` copy first doesn't remove
-the field from the graph, it hands ownership back to the subgraph you were
-migrating away from, and every check here reports clean because the coordinate
-and its type never moved. Delete the old owner's copy first; the recompose after
-that is what makes the field's removal visible at all.
-
-### Two changes every gate calls clean
-
-`federation:diff` reads coordinates and types; `queries:check` and `generate`
-read what a query *says*. Two ordinary schema changes fall between them, and on
-both, `schema:diff`'s `breaking: true` line is the only warning anyone gets —
-once, in the run that first sees it:
-
-- **A scalar swapped for one that serializes the same way.** `Widget.price`
-  going `String!` → `Currency!` is a breaking row in `schema:diff`. But a client
-  that hasn't regenerated has `const :price, String`, and a `Currency` that
-  still arrives as a JSON string — `"$19.99"` where `"19.99"` used to be —
-  satisfies that prop exactly. Sorbet asks whether it is *a* String, which it
-  is; nothing downstream of that knows the format changed, and `"$19.99".to_f`
-  is `0.0`. Regenerating is what surfaces it, and only if the client
-  [registers the scalar](scalars.md#registering-a-class-of-your-own) rather than
-  leaving it a String.
-- **An enum value removed.** `Status.ACTIVE` disappearing is a breaking row too,
-  and `queries:check` and `generate` are both clean for every query that selects
-  a `status` field without naming `ACTIVE` in the document — validation has
-  nothing to check a value against unless the value is written down. The
-  generated `T::Enum` keeps the constant and keeps deserializing it; the server
-  simply never sends it again. Harmless in itself, and a live signal that the
-  branch handling it is dead.
-
-So a supergraph owner announcing either of these should not expect a client's CI
-to notice. Deprecate first — `schema:diff` reports a deprecation's arrival, and
-that is the one place it shows up, since generated code carries no trace of it.
-
-**A supergraph is routinely only partly local**, so the report names three
-states rather than two: checked, not here (running elsewhere — or the subgraph
-is gone), and [faked](#the-local-router). A clean report that quietly checked one
-subgraph of three would be actively misleading, so the headline counts them and
-the sections name them. Only drift fails the task; absence is a supported
-setup. Checking **none** of them fails too — "checked 0 of 4" attached to exit 0
-is a gate that passes whatever the subgraphs say. (It won't come up in a Rails
-app whose subgraphs are here: the `federation:*` tasks eager-load for you — see
-[which schema serves which subgraph](#which-schema-serves-which-subgraph).)
-
-The mirror of all that is a subgraph **retired** from the composition whose Ruby
-class is still loaded. Every check here walks the supergraph's subgraph list, so
-that one sat on the only side nothing looked at, and the report read "matches
-the schemas here (checked 3 of 3 subgraphs)". It is now named, on stderr:
-
-```
-not placed — no subgraph of any supergraph read here is:
-  Reviews::Schema
-```
+**shape** is "recompose" for a field neither side dropped, and **not composed in**
+is "publish the subgraph". Stale and shape name the subgraph the supergraph blames.
+Field-set comparison is deliberately looser than equality, since a subgraph carries
+plumbing no supergraph has and a field can legitimately sit in more than one
+(`@external` copies, `@shareable`), so one candidate schema agreeing settles it.
+
+**A supergraph is routinely only partly local**, so the report counts three states:
+checked, not here, and [faked](#a-supergraph-only-partly-local). Only drift fails
+the task — absence is a supported setup — but checking **none** of them fails too,
+since "checked 0 of 4" attached to exit 0 is a gate that passes whatever the
+subgraphs say. The mirror of that is a subgraph **retired** from the composition
+whose Ruby class is still loaded: every check walks the supergraph's subgraph list,
+so that one sits on the side nothing looks at, and it is named on stderr as `not
+placed`. A warning rather than drift, deliberately — a process that loads a
+subgraph of a supergraph this run never reads is the same picture. (A schema is a
+subgraph here if it serves `Query._service`.)
+
+**Every `federation:*` task finds the supergraph the same way**: once per declared
+graph whose schema is a composed one, each report headed with that graph's name. A
+graph that is in none is simply not a subject for these tasks.
+`SUPERGRAPH=supergraph.graphql` overrides that for one run and reaches the
+`federation:*` tasks and **nothing else** — every other task reads the schema its
+graph declares, and one pointed at an ad-hoc supergraph would collapse a
+multi-graph app into a single unnamed graph, so they refuse it rather than ignore
+it. To check queries against a supergraph, declare it:
+`GraphWeaver.graph(:api) { schema "supergraph.graphql" }`.
 
-A **warning, not drift**, deliberately: a process that loads a subgraph of a
-supergraph this run never reads is the same picture, and nothing on either side
-tells the two apart. A schema is a subgraph here if it serves `Query._service`,
-which is how a gateway reads one to compose it. `Drift#unplaced` is the list for
-one supergraph; the task asks every graph in the run, so a multi-graph app's
-second supergraph places its own schemas rather than having them reported
-against the first.
-
-A schema is recognized by the types the supergraph says its subgraph declares,
-plus at least one coordinate attributed to that subgraph **alone**. What two
-subgraphs share can't tell them apart — every subgraph has a `Query`, and the
-entity `accounts` and `prefs` both extend is declared by both — so a subgraph
-whose own fields are nowhere in this process is "not here", not stale.
-Detection is therefore what drift breaks, so the same
-`subgraphs:` map [`Testing::Router`](#the-local-router) takes is accepted here,
-and a named schema skips detection:
+`Drift` is the API under the task, and it takes the same `subgraphs:` map
+[`Testing::Router`](#the-local-router) does — which matters twice. **Name the schema
+whenever you are diffing a *proposal***, since detection unions every loaded schema
+that fits a subgraph, so a console session holding both the changed SDL and the
+unmodified class reports clean. And because `Drift` **never calls a resolver**, it
+takes what the router can't — a **subgraph SDL** from a non-Ruby team loads into a
+resolver-less schema it compares like any other:
 
 ```ruby
 require "graph_weaver/federation"   # the rake tasks do this for you
 
 GraphWeaver::Federation::Drift.new(
   supergraph: "supergraph.graphql",
-  subgraphs: { "products" => Products::Schema, "inventory" => :fake },
+  subgraphs: { "products" => Products::Schema, "inventory" => :fake,
+               "accounts" => GraphWeaver::SchemaLoader.load(File.read("accounts.graphql")) },
 ).report
 ```
 
 `#to_h` is the JSON-ready `{"stale" => …, "shape" => …, "uncomposed" => …,
 "skipped" => …, "faked" => …}` — a `shape` entry is `{"subgraphs" => […],
-"supergraph" => "String!", "here" => ["ID!"]}` — and `#drift?` is what the task
-exits on. `#unplaced` sits
-outside both, being the warning above rather than drift.
+"supergraph" => "String!", "here" => ["ID!"]}` — `#drift?` is what the task exits
+on, and `#unplaced` is the warning above rather than drift.
 
-**`Drift` never calls a resolver**, so what it accepts in that map is wider than
-what `Testing::Router` needs. A **subgraph SDL** — `rover subgraph fetch`,
-`_service { sdl }`, whatever a non-Ruby team publishes — loads into a
-resolver-less schema that `Drift` compares like any other:
+### What federation:diff can't see
 
-```ruby
-GraphWeaver::Federation::Drift.new(
-  supergraph: "supergraph.graphql",
-  subgraphs: { "accounts" => GraphWeaver::SchemaLoader.load(File.read("accounts.graphql")) },
-).report
+**What is compared is a coordinate's presence and its type, and nothing else.** The
+`@key` it is part of, a field's arguments, its directives, and everything a type
+says about itself beyond its fields are not read, and a change to any of them
+reports clean. Two ordinary subgraph edits land in that gap, and both break the
+*next* composition while the report stays green: a **`@key` added, removed or
+turned `resolvable: false`** is a directive, so nothing here reads it (the last of
+those makes recomposition impossible and still reports clean); and a **field one
+subgraph adds that another already owns, neither marked `@shareable`**, is
+invisible because the coordinate is already in the supergraph, so "not composed in"
+doesn't fire, while its original owner still declares it, so neither does "stale".
+
+So **`federation:diff` answers "did you forget to recompose the schema you have",
+never "would the next recompose succeed"** — the second question needs the JS
+composer, a network and npm dependency this deliberately doesn't take. A clean
+report says so on its own line rather than leaving you to infer it:
+
+```
+supergraph.graphql: matches the schemas here, field for field and type for type (checked 3 of 3 subgraphs)
+not compared: @key (added, removed, or made unresolvable), and one field two subgraphs define without @shareable — recompose to catch those
 ```
 
-That is the real answer to "what does a Python subgraph look like to these
-tasks": to the router it is `:fake` or absent, but to `federation:diff` it is a
-fully compared citizen.
+An `@override` migration is asymmetric for the same reason: a supergraph published
+*ahead* of the code is caught (the old side's field is `stale`), but code ahead of
+the supergraph is not, because both sides carry the field and its type and only the
+`@override` marker says ownership is moving. **Finish an `@override` migration from
+the old side** — deleting the *new* side's copy first hands ownership back to the
+subgraph you were migrating away from, and every check reports clean because the
+coordinate never moved.
 
-**Name the schema whenever you are diffing a *proposal*.** Detection unions
-every loaded schema that fits a subgraph, so a console session that builds the
-changed SDL while the unmodified `Reviews::Schema` is still loaded reports
-clean — the real class supplies the field the proposal dropped, and both are
-candidates for "reviews". `subgraphs:` naming the one you mean is what makes
-the answer about your proposal.
+### Two changes every gate calls clean
+
+`federation:diff` reads coordinates and types; `queries:check` and `generate` read
+what a query *says*. Two ordinary schema changes fall between them, and on both,
+`schema:diff`'s `breaking: true` line is the only warning anyone gets — once, in
+the run that first sees it:
+
+- **A scalar swapped for one that serializes the same way.** `Widget.price` going
+  `String!` → `Currency!` leaves a client that hasn't regenerated with
+  `const :price, String`, which a `Currency` arriving as a JSON string — `"$19.99"`
+  where `"19.99"` used to be — satisfies exactly. Sorbet asks whether it is *a*
+  String, which it is, and `"$19.99".to_f` is `0.0`. Regenerating surfaces it, and
+  only if the client [registers the scalar](scalars.md#registering-a-class-of-your-own).
+- **An enum value removed.** `queries:check` and `generate` are clean for every
+  query that selects a `status` field without naming `ACTIVE` in the document —
+  validation has nothing to check a value against unless the value is written down.
+  The generated `T::Enum` keeps the constant and keeps deserializing it; the server
+  simply never sends it again.
+
+So a supergraph owner announcing either of these should not expect a client's CI to
+notice. Deprecate first: `schema:diff` reports a deprecation's arrival, and that is
+the one place it shows up, since generated code carries no trace of it.
 
 ## In CI
 
 `federation:diff` needs no network, so it belongs beside the other checks in the
-normal PR run — the [GitHub Actions job](getting_started.md#5-verify-in-ci) has
-the step. Add it where the subgraph classes live: an app that only *calls* the
-gateway loads none of them, and the task aborts rather than pass having checked
-nothing ([above](#has-the-supergraph-been-recomposed)).
-
-**What that job does not do is look at the schema production is serving**, and
-on a federated graph nothing here can. Every check in it compares the app to
-artifacts checked in beside it: `verify` to the generated Ruby, `queries:check`
-and `unused` to the dump, `federation:diff` to the subgraph classes in this
-process. `schema:diff` is the one that reads a live source, and it can't be
-pointed at a supergraph — a composed supergraph records no source url because no
-endpoint serves one, and a production router refuses introspection by default
-(`{"message": "introspection has been disabled", "extensions": {"code":
-"INTROSPECTION_DISABLED"}}`). Hot-reload a router onto a supergraph that dropped
-a field your queries select and all of it still exits 0 while every one of those
-requests fails.
+normal PR run — the [GitHub Actions job](getting_started.md#5-verify-in-ci) has the
+step. Add it where the subgraph classes live: an app that only *calls* the gateway
+loads none of them, and the task aborts rather than pass having checked nothing.
+
+**What that job does not do is look at the schema production is serving**, and on a
+federated graph nothing here can: every check in it compares the app to artifacts
+checked in beside it. `schema:diff` is the one that reads a live source, and it
+can't be pointed at a supergraph — a composed supergraph records no source url
+because no endpoint serves one, and a production router refuses introspection by
+default. Hot-reload a router onto a supergraph that dropped a field your queries
+select and all of it still exits 0 while every one of those requests fails.
 
 That gap is Apollo's to close, and it has two commands for it:
 
@@ -506,209 +643,73 @@ rover subgraph check my-graph@prod --name products --schema products.graphql
 rover supergraph fetch my-graph@prod   # then recompose and diff what you get back
 ```
 
-`rover subgraph check` asks GraphOS whether publishing this subgraph would break
-the composition or a client operation registered against the variant — the
-pre-merge half. `rover supergraph fetch` hands you the supergraph the router is
-running, which is the artifact `federation:diff` should be pointed at when what
-you want to know is "does the deployed graph still answer my queries", rather
-than "is my checked-in supergraph consistent with my checked-in subgraphs".
+`rover subgraph check` asks GraphOS whether publishing this subgraph would break the
+composition or a client operation registered against the variant — the pre-merge
+half. `rover supergraph fetch` hands you the supergraph the router is running, which
+is what `federation:diff` should be pointed at when the question is "does the
+deployed graph still answer my queries".
 
-Nothing in this gem talks to GraphOS, and the runtime half is where a federated
-app finds out: a query the served supergraph rejects comes back with
+Nothing in this gem talks to GraphOS, so without them the runtime is where a
+federated app finds out: a query the served supergraph rejects comes back with
 `schema_stale?` true and a message naming the repair
-([errors → stale schemas](errors.md#stale-schemas)). That is detection at the
-point of damage, which is exactly why the two `rover` commands belong in the
-same job as the five tasks.
-
-## The local router
-
-Specs for a federated app have a bad choice: fake the whole graph, or boot a
-gateway. `Testing::Router` is the third one. It takes the composed supergraph
-and the Ruby schema classes serving its subgraphs, plans the query, and
-satisfies the [client contract](transports.md) — so a generated module runs
-against your **real resolvers**, in-process, with no gateway, no node and no
-sockets. It is not a mock: your resolvers run, which is the whole point.
+([errors → stale schemas](errors.md#stale-schemas)). That is detection at the point
+of damage, which is why those two commands belong in the same job as the five tasks.
 
-```ruby
-GraphWeaver.client = GraphWeaver::Testing::Router.new(
-  supergraph: Rails.root.join("supergraph.graphql"),
-  context: { current_user: user },
-)
-```
+## Details
 
-`context:` reaches every subgraph, because every subgraph is a Ruby call here.
-Neither real transport does that with a request's **headers** — the gateway and
-the Apollo Router both start a subgraph call with none of the client's, unless
-you configure the forwarding — so don't let a spec conclude an auth header
-arrived somewhere it wouldn't.
-
-In rspec that's the [`graphql: :router`](testing.md#a-federated-graph--graphql-router)
-tag and there is nothing to pass — the tag builds it, once for the suite. It
-finds the supergraph where you have already said it is: `Testing.config.router
-= { supergraph: … }` if you named one there, else the schema a
-[graph](getting_started.md#more-than-one-schema) declares when that schema is
-composed, else the committed dump when *that* is. Two graphs may name one
-supergraph; two naming different ones is refused rather than picked between.
-`router.trace` records the fetches made since the last `reset_trace`, in order
-(subgraph, query, variables); the same lines go to `GraphWeaver.logger` at
-`:debug`. It **accumulates across executes**, because the question worth asking
-is which subgraphs a code path touched and a service object rarely runs one
-query. The rspec tag resets it before each example; outside rspec call
-`router.reset_trace` around the code path you're measuring.
-
-The count is the **local router's plan, not the gateway's**. The data is
-faithful — a real gateway answers byte-identically, or this refuses — but the
-cost isn't quite: everything crossing into one subgraph from one level rides one
-call, and a [`@requires` prefetch](#what-it-plans) is still its own call even
-when it goes to the same subgraph as the plain read beside it, where a gateway
-merges the two. A dashboard query a gateway does in 4 fetches takes 5 here. So
-assert on a **bound** (`expect(router.trace.size).to be <= 8`) or on the
-**subgraph set** (`router.trace.map { _1[:subgraph] }.uniq`): both move when an
-N+1 appears, and neither pins a number production doesn't have.
-
-The router hands back a result hash *above* the wire, so the transport your app
-ships never runs. When that transport is the thing under test — a caller tag, an
-APM header, mTLS — [`graphql: :wire`](testing.md#over-the-wire--graphql-wire)
-serves this same router at the endpoint your client posts to and leaves your
-client in place: real serialization, the same plan over the same resolvers,
-`from_h` over the server's own bytes, and a `context:` proc reading the headers
-that arrived. It refuses exactly what the router refuses — a hop, not a
-capability. The hop is served through webmock, so that tag needs
-`require "webmock/rspec"` in the spec helper —
-[testing](testing.md#over-the-wire--graphql-wire) has the rest.
-
-**[`examples/federation.rb`](https://github.com/dpep/graph_weaver/blob/main/examples/federation.rb)** is the whole shape
-in one runnable file, and the only example that needs no network: three real
-subgraphs, a boundary-crossing query through a generated module, the trace,
-and a refusal. [`spec/router_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/router_spec.rb) is the
-exhaustive reference — every plan shape, every refusal, the partly-local
-graph and the `:fake` opt-in, each as a named example.
-
-### Which schema serves which subgraph
-
-`subgraphs:` is optional. Left out, each one is **derived from what the loaded
-schemas define**: a schema serves subgraph `s` when it defines every type and
-field the routing table says `s` resolves. That's evidence rather than a guess,
-and a wrong guess would point a suite at the wrong resolvers and still pass — so
-exactly one match is used. Neither other outcome refuses at construction, since
-which classes are loaded is not a fact about the query you're running: **no**
-match means the subgraph is served somewhere else (next section), and **two**
-means detection can't say which loaded schema class serves it. Both are refused
-by the query that reaches the subgraph's fields, each naming its own fix — for
-two, `subgraphs: { "reviews" => App::Reviews::Schema }` pins it, and
-`router.ambiguous` lists them.
+### The routing table
 
-Name them yourself when you'd rather have the wiring committed, or when
-detection can't settle it — including partially, with the rest derived:
+Stripping the machinery answers "what does this graph look like". The other question
+a supergraph answers is "who resolves what", and `SchemaLoader.routing_table` keeps
+that side rather than discarding it:
 
 ```ruby
-subgraphs: { "accounts" => Accounts::Schema }   # products, reviews derived
-```
-
-Either way the map is **checked** at construction, so a swapped pair fails
-naming what's missing rather than surfacing as a mystery three fetches later:
-
-```
-subgraphs["accounts"] is Products::Schema, which doesn't define Query.me,
-Query.user, Query.users, User, User.email and 1 more — the supergraph says
-accounts resolves them. Did two entries get swapped?
-```
-
-Detection only sees what's **loaded**, and in Rails an autoloaded schema isn't
-until something references it — which is why an unmatched subgraph reads as
-absent. The `federation:*` rake tasks eager-load the app for you; a spec suite
-is your own `config.eager_load`, which Rails leaves off outside CI. To see what
-detection sees, and get a map to paste:
+table = GraphWeaver::SchemaLoader.routing_table("supergraph.graphql")
 
-```
-$ rake graph_weaver:federation:subgraphs
-subgraphs: {
-  "accounts" => Accounts::Schema,  # matched: defines Query.me, Query.user, Query.users
-  "products" => Products::Schema,  # matched: defines Product.name, Product.price, Product.weight
-  "reviews" => Reviews::Schema,    # matched: defines Product.reviews, Product.shippingEstimate, Query.feed
-}
+table.subgraphs                                # => ["accounts", "products", "reviews"]
+table.owners("Product", "shippingEstimate")    # => ["reviews"]
+table.owners("User", "username")               # => ["accounts"] — the @external copy isn't an owner
+table.keys("User", "accounts")                 # => [["id"]]
+table.field("Product", "shippingEstimate").requires  # => "price weight"
+table.possible_types("Purchasable", "products")      # => ["Bundle", "Product"]
 ```
 
-A row nothing matched comes back `nil`, naming the coordinates it looked for —
-that's the map to fill in, or the subgraph that lives elsewhere.
+Subgraphs are named the way `@join__graph(name:)` names them — the strings a router
+config and `rover` use, not the SDL's uppercase enum spelling. A `@key` field set
+comes back as dotted paths (`"id organization { id }"` → `["id",
+"organization.id"]`). A field with no `@join__field` at all lives wherever its type
+does; that omission is how the composer says "everywhere". `possible_types` answers
+the abstract side, from `@join__unionMember`/`@join__implements`, and is `nil` where
+the supergraph doesn't say — a different fact from "none". A `@join__` directive the
+table hasn't been taught lands in `#unsupported` rather than being skipped, and
+callers refuse on a non-empty list: a table that silently ignores half a spec
+version answers confidently and wrongly. `#interface_objects` is the one construct
+kept out of that list (`{"Media" => ["catalog"]}`), being a fact about one *type*
+rather than about the table — the router refuses the queries that reach it and plans
+the rest.
 
-### A supergraph only partly local
-
-The usual migration shape: the supergraph is composed from several services and
-only **some** of them run in your process. The rest are routed over the network,
-so there is no Ruby schema here to serve them — and requiring one would refuse
-the whole suite over fields most of your queries never touch.
+The table is also what a good error message wants. When the schema dump is a
+composed supergraph, `rake graph_weaver:queries:check` brands each validation error
+with the subgraphs behind the type it names, and `check_queries` carries the same
+list as a `"subgraphs"` key:
 
-So a subgraph nothing here defines is **absent**, and the router builds and runs
-anyway. Absence costs you exactly the queries that reach into it:
-
-```ruby
-router.absent                                            # => ["shipping"]
-router.execute("{ me { username reviews { body } } }")   # real data, as always
-router.execute("{ shipments { carrier } }")              # GraphWeaver::Testing::Unplannable
 ```
-
-That refusal is a plan-time one like every other, so nothing has executed when
-it raises, and it names the subgraph, the field that reached for it, and both
-ways out — name a schema for it, or fake it:
-
-```ruby
-subgraphs: { "shipping" => :fake }   # any other absent subgraph still refuses
-```
-
-If the subgraph *is* here and detection just couldn't see it — a Rails schema
-class nothing has referenced yet — loading it is the fix, and in a spec suite
-that means `config.eager_load = true` (naming it in
-`Testing.config.router = { subgraphs: … }` works too). `=> :fake` is the
-other one: mid-migration, letting an absent subgraph answer with
-schema-correct fabricated data exercises the rest of the query. It speaks the
-whole subgraph contract, `_entities(representations:)` included, so it works
-under a stitched fetch as well as at a root field.
-
-Refusing stays the default, and the opt-in is **per subgraph** on purpose:
-silently substituting invented data is the failure mode this library keeps
-designing against. For the same reason faking is **loud** — every faked fetch
-is marked `faked: true` in `router.trace` and logged at `:warn`.
-`router.faked` lists them, and `router.inspect` shows what's served, faked and
-absent. Values come from the same engine as
-[`graphql: :fake`](testing.md#fabricated-data--graphql-fake), so `config.seed`,
-`config.overrides` and the rest apply.
-
-`fake:` says how they fabricate — the [pins](testing.md#pins) and options a
-fake takes, in one hash. It goes on `Router.new` outside rspec, on
-`Testing.config.router` for the suite, and on `graphql_router` for the one
-example that cares:
-
-```ruby
-Testing.config.router = { subgraphs: { "shipping" => :fake },
-                          fake: { list_size: 2 } }
-
-it "shows the carrier" do
-  graphql_router(fake: { "Shipment.carrier" => "UPS" })
-  ...
-end
+app/graphql/queries/product.graphql
+  4:5  Field 'dimensions' doesn't exist on type 'Product' (products, reviews)
 ```
 
-One `fake:` covers every faked subgraph, because a pin's key
-(`"Shipment.carrier"`) already says which type it means. And `graphql_router` is
-`graphql: :router` with somewhere to put arguments — the router itself is still
-built once for the suite, and the options last one example.
-
 ### What it plans
 
 An operation that resolves in **one subgraph** goes over verbatim. One that
 **crosses a boundary** is split at the crossing: the plan injects the entity's
 `@key` under a reserved alias, refetches it from the owning subgraph through
-`_entities(representations:)`, and stitches the answer back. Every node at one
-level goes in **one** `_entities` call, so a list of users and all their
-reviews' products is three fetches, not one per row — and everything that level
-crosses into one subgraph shares that call, a `@requires` field alongside a
-plain one included. Root fields that resolve
-in different subgraphs get one fetch each. A `@provides` copy is read in place,
-so nothing leaves the subgraph for a field the copy already holds.
+`_entities(representations:)`, and stitches the answer back. Every node at one level
+goes in **one** `_entities` call, so a list of users and all their reviews' products
+is three fetches, not one per row. Root fields that resolve in different subgraphs
+get one fetch each, and a `@provides` copy is read in place.
 
-A **`@requires` field set** is supplied by the router rather than by the
-subgraph that declares the field, so it's a fetch before the fetch:
+A **`@requires` field set** is supplied by the router rather than by the subgraph
+that declares the field, so it's a fetch before the fetch:
 
 ```ruby
 router.reset_trace
@@ -717,24 +718,21 @@ router.trace.map { _1[:subgraph] }   # => ["reviews", "products", "reviews"]
 ```
 
 `shippingEstimate` resolves in `reviews` and `@requires "price weight"`, which
-`products` owns — so the plan fetches those into hidden keys, hands them back
-in the representation, and only then asks for the estimate. One hop only: the
-key for the first fetch has to come from the subgraph already in hand, so a
-chain can't grow a chain. And two `@requires` field sets crossing into the same
-subgraph on the same `@key` ride **one** prefetch, as Apollo's do — the
-representations would be identical, so a second call would only re-run the
-resolvers.
-
-A **nested field set** — `@key(fields: "id organization { id }")`,
-`@requires(fields: "origin { lat lon }")` — is a selection set like any other,
-so it crosses as one: the fetch asks for `organization { id }` under a
-reserved alias, and the representation carries the object back in the shape
-the SDL spells it, to any depth, nulls and all. Where a type has more than one
-`@key`, the plan takes the first one the fetching subgraph can supply.
-
-A **union or interface at a boundary** — a feed, a search page, any
-polymorphic list — is planned per concrete type, because a representation names
-one concrete `__typename` and which one an object has isn't in the query:
+`products` owns — so the plan fetches those into hidden keys, hands them back in the
+representation, and only then asks for the estimate. One hop only: the key for the
+first fetch has to come from the subgraph already in hand, so a chain can't grow a
+chain. Two `@requires` sets crossing into the same subgraph on the same `@key` ride
+one prefetch, as Apollo's do.
+
+A **nested field set** — `@key(fields: "id organization { id }")` — crosses as one
+object: the fetch asks for `organization { id }` under a reserved alias, and the
+representation carries it back in the shape the SDL spells, to any depth, nulls and
+all. Where a type has more than one `@key`, the plan takes the first the fetching
+subgraph can supply.
+
+A **union or interface at a boundary** is planned per concrete type, because a
+representation names one `__typename` and which one an object has isn't in the
+query:
 
 ```ruby
 router.reset_trace
@@ -742,136 +740,61 @@ router.execute("{ purchasables { name ... on Product { reviews { body } } } }")
 router.trace.map { _1[:subgraph] }   # => ["products", "reviews"]
 ```
 
-The plan holds a branch per type the supergraph says that subgraph can answer
-with; the fetch asks for `__typename` under a reserved alias, and the objects
-that come back are bucketed by it — one `_entities` fetch per concrete type,
-none for a bucket nothing lands in. A fragment whose condition can't hold there
-(`... on Note` where that subgraph's union has no Note) never matches, so it is
-dropped, which is the answer a real router gives too.
-
-Three things it does that a naive merge doesn't, and that being wrong about
-would be worse than refusing:
-
-- **Null propagation over the merged tree.** A stitched fetch can put a null
-  where the composed schema says non-null, and no subgraph is in a position to
-  notice. The router re-applies GraphQL's propagation rules to the merged
-  result, so a subtree the real router would have nulled comes back null here.
-- **Error re-pathing, and a stamp saying which subgraph failed.** A subgraph
-  reports `_entities.2.shippingEstimate`; you get
-  `topProducts.2.shippingEstimate`, with `extensions.service` naming the
-  subgraph — the Apollo Router's spelling, because it is the current product
-  (the deprecated `@apollo/gateway` says `extensions.serviceName` and adds
-  `code: "DOWNSTREAM_SERVICE_ERROR"`, which isn't a code any subgraph here
-  set). Whatever the resolver put in `extensions` is left alone, including its
-  own `service`. `locations` are dropped rather than pointing into a query you
-  never wrote. That is for a `GraphQL::ExecutionError`, which is what `errors`
-  carries; a resolver that raises anything else propagates as a Ruby exception
-  out of `execute`, the same way it would from graphql-ruby on its own, and
-  nothing here catches it into a response.
-- **`@skip`/`@include` on a stitched field.** A skipped field comes back
-  *absent*, not null.
-
-Introspection is answered from the composed API schema, never from a subgraph,
-which would reply with its own slice — the one split a real router also makes.
-
-**A wire fault at one subgraph has no representation here.** A subgraph is a
-Ruby call, not a socket: `:router` fetches in-process, and `:wire` stubs one
-endpoint in front of the whole router. So a timeout, an HTTP 500, malformed
-JSON, or a bare `errors` with no `data` — anything that is a property of the
-*transport* to one subgraph — is out of reach under `:router`; `:wire` plus
-`Failure` covers those faults for the one stubbed endpoint, which is the whole
-graph rather than any subgraph in it. A subgraph that *fails* is expressible
-— raise from its resolver, or fake it — but partial availability is a
-gateway's property, not this double's.
-
-### What it refuses
-
-Everything it can't plan **faithfully** raises
-`GraphWeaver::Testing::Unplannable` (a `GraphWeaver::Error`), at plan time,
-before any subgraph runs — so a refusal is never a half-executed query. A double
-that approximated the rest of Apollo's planner would let a test pass on an
-answer production disagrees with, which is the most expensive thing this library
-can produce. Each refusal names the coordinate that stopped it and what to do —
-`examples/federation.rb` prints one.
-
-Every category, in the words `Unplannable#label` uses (`#category` is the
-matching symbol):
-
-| Refusal | Why |
-|---|---|
-| no `@key` to cross the boundary on | an entity fetch sends a representation built from a `@key`; with none there is nothing to send |
-| an abstract type the supergraph doesn't break down | bucketing needs the concrete types a subgraph answers a union or interface with, and `@join__unionMember`/`@join__implements` is where a supergraph records that. A composition old enough to carry neither leaves nothing but a guess |
-| an `@interfaceObject` the routing table can't attribute | one subgraph resolves a whole interface's implementations, so the supergraph never says which subgraph answers each of its fields. Per query, not per graph: a query that doesn't reach the type plans as if the directive weren't there |
-| a `@fromContext` argument no fetch here can supply | federation 2.8's `@context`/`@fromContext` fills a field's argument from a selection on an ancestor, and only the gateway that planned the fetch knows what to put there — a subgraph's own resolver never fills one, so this is refused on any path, including the one where a single subgraph answers the whole query. Per query, like `@interfaceObject`: a query that doesn't reach the field plans as if the directive weren't there |
-| a response delivered in more than one payload | `@defer`/`@stream` stream the rest of the answer over a multipart body after the first payload, and this router answers in one. Refused by name rather than left to validation, so the guarantee doesn't rest on whether the composed schema happens to declare the directive |
-| a progressive `@override` still rolling out | federation 2.7's `@override(label:)` leaves *both* subgraphs resolving the field — composition decides nothing, the gateway splits traffic per request by the label's rule. A local router can't evaluate a rollout percentage, so it would answer from one side every time. Finish the rollout (drop the label) and composition drops the losing copy, which plans normally |
-| a `@requires` whose field set names another `@requires` field | the router satisfies a `@requires` with one fetch, so it can't first satisfy that field's own requirement |
-| a nested field set no one fetch can build | a nested field set crosses as one object, so one fetch has to answer the whole of it. Nesting itself is fine — this is the set whose fields are split across subgraphs, so the object would arrive half-built from each |
-| `@skip`/`@include` on both a fragment and its field | one selection can't carry two conditions of the same name. Spell the condition once |
-| an alias shadowing an injected `@key` | a fetch carries the `@key` it crosses on under a response key — Apollo under the field's own name, the local router under a reserved one — and an alias spelling either claims a key the fetch needs |
-| a mutation's root fields span subgraphs | root mutation fields run in series, and splitting them across subgraphs would run them in whatever order the plan happened to. Sharing one subgraph they're fine, stitching below them and all — that's an ordinary read afterwards. Query roots are independent, so those are always fine |
-| the routing table names no subgraph | nothing can route a field the supergraph doesn't place |
-| a subgraph nothing here serves | it's served by another process, so there is nothing here to ask — unless you fake it (above) |
-| introspection mixed with data | introspection is answered from the composed API schema and data from the subgraphs, and the two can't be merged. Split them into two operations |
-| the document isn't one operation | pass `operation_name:` naming one of them |
-| not a query or a mutation | the router plans against the composed schema's query and mutation roots; a subscription has neither |
-| a fragment the document never defines | define it, or point the query at the file that does — validation rejects it first, so what you actually get back is an `errors` response |
-| a federation construct the routing table doesn't read | an incomplete table makes every answer about this supergraph a guess. The one refusal raised **at construction**, before a single query |
-| nested deeper than the router walks | past the walk's depth limit, which validation would have rejected first |
-
-A document that fails ordinary GraphQL validation — an undefined fragment, a
-subscription against a schema with no `Subscription` root — never reaches any of
-this: it gets the same `errors` response a plain client gets, not an
-`Unplannable`.
-
-The construction-time one is worth planning around. A `@join__` directive the
-table doesn't read refuses `Router.new` for the **whole graph**, so one team
-adopting a newer federation feature in their own subgraph is an upgrade-timing
-event for every team that tests with `:router` — including the ones whose
-queries never go near it.
-
-A subgraph two loaded schemas both fit raises a `ConfigurationError` rather than
-an `Unplannable` — it's a wiring mistake, not a query the router declines — but
-it raises where every other one does, on the query that reaches the subgraph.
-Which classes happen to be loaded is not a fact about the query under test.
-Naming a class in `subgraphs:` *is* a claim, so a wrong one still fails at
-construction.
-
-A double that quietly answered *differently* from the router would be worse than
-no double at all, so
+The plan holds a branch per type the supergraph says that subgraph can answer with;
+the fetch asks for `__typename` under a reserved alias and buckets what comes back
+by it — one `_entities` fetch per concrete type, none for an empty bucket. A
+fragment whose condition can't hold there is dropped, as a real router drops it.
+
+Three things it does that a naive merge doesn't, and that being wrong about would be
+worse than refusing: it **re-applies GraphQL's null propagation** to the merged tree,
+where a stitched fetch can put a null the composed schema says can't be there and no
+subgraph is in a position to notice; it **re-paths errors and stamps the subgraph**,
+so a subgraph's `_entities.2.shippingEstimate` reaches you as
+`topProducts.2.shippingEstimate` with `extensions.service` naming it (whatever the
+resolver put in `extensions` is left alone, and `locations` are dropped rather than
+pointing into a query you never wrote — that is for a `GraphQL::ExecutionError`, and
+a resolver raising anything else propagates out of `execute` as a Ruby exception);
+and a field **`@skip`/`@include` removes comes back absent, not null**. Introspection
+is answered from the composed API schema, never from a subgraph, which is the one
+split a real router also makes.
+
+**A wire fault at one subgraph has no representation here.** A subgraph is a Ruby
+call, not a socket: `:router` fetches in-process, and `:wire` stubs one endpoint in
+front of the whole router. So a timeout, an HTTP 500, malformed JSON, or a bare
+`errors` with no `data` — anything that is a property of the *transport* to one
+subgraph — is out of reach. A subgraph that *fails* is expressible (raise from its
+resolver, or fake it), but partial availability is a gateway's property, not this
+double's.
+
+### How faithful is it, really
+
+A double that quietly answered *differently* from the router would be worse than no
+double at all, so
 [`spec/integration/router_parity_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/integration/router_parity_spec.rb)
-serves the demo subgraphs over HTTP, boots a real `@apollo/gateway` on the same
-supergraph, and runs the whole corpus through both — plus boundary probes and
-queries where a subgraph deliberately **fails**, which are the cases where a
-merge that doesn't re-propagate hands back a populated tree while the real router
-answers `data: null`. Three outcomes, one of them a defect: match, refuse, or
-answer differently, and the spec fails on the third. `make integration` runs it
-(node required).
-
-**"A real router" is two things, and they disagree.** Everything measured above
-is against `@apollo/gateway` — the deprecated JS gateway, which is what the
-parity spec boots. The Rust Apollo Router, which is the current product,
-differs from it on a subgraph 500's error shape, on malformed JSON from a
-subgraph, on `@defer` (it supports it, behind an `Accept: multipart/mixed`
-header; the gateway doesn't know the directive), and on introspection, which it
-disables by default. So when a refusal says "run this one against a real
-router", run it against the one you deploy — not against the one these numbers
-came from.
-
-**And a production router shows you less than this one does.** A subgraph error
-arrives here with its message and an `extensions: {"service" => …}` stamp; an
-Apollo Router with `include_subgraph_errors` omitted — the default — answers
-`{"message" => "Subgraph errors redacted", "path" => […]}` with the extensions
-emptied. A spec asserting on the message or the stamp therefore passes here and
-against a dev router and fails in staging. `path` is what survives, so that is
-what to assert on: [testing → production redacts what this router hands
-you](testing.md#production-redacts-what-this-router-hands-you).
+(`make integration`, node required) serves the demo subgraphs over HTTP, boots a
+real `@apollo/gateway` on the same supergraph, and runs the whole corpus through
+both — plus boundary probes and queries where a subgraph deliberately **fails**,
+the cases where a merge that doesn't re-propagate hands back a populated tree while
+the real router answers `data: null`. Match, refuse, or answer differently: the
+spec fails on the third.
+
+**But "a real router" is two things, and they disagree** — and a production one
+shows you less than either. Everything above is measured against `@apollo/gateway`,
+the deprecated JS gateway; the Rust Apollo Router differs on a subgraph 500's error
+shape, on malformed JSON from a subgraph, on `@defer` (it supports it, behind an
+`Accept: multipart/mixed` header) and on introspection, which it disables by
+default — and with `include_subgraph_errors` omitted it answers `{"message" =>
+"Subgraph errors redacted", "path" => […]}` where this router hands you the
+subgraph's own message and its `service` stamp. So run a refusal you're unsure
+about against the router you deploy, and assert on `path` rather than a message
+that only survives locally:
+[testing → production redacts what this router hands you](testing.md#production-redacts-what-this-router-hands-you).
 
 ### Is it worth wiring up? Measure.
 
-The router's value is one number — the fraction of *your* queries it can plan —
-and that depends on the shape of your graph and of your queries, so measure it
-rather than guess:
+The router's value is one number — the fraction of *your* queries it can plan — and
+that depends on the shape of your graph and of your queries, so measure it rather
+than guess:
 
 ```
 $ rake graph_weaver:federation:coverage
@@ -879,129 +802,19 @@ $ rake graph_weaver:federation:coverage
   accounts 4, reviews 4, products+reviews 3, accounts+reviews 2, products 2, accounts+products 1, accounts+products+reviews 1
 ```
 
-**Two numbers, because they answer different questions.** *Plannable* is about
-the graph — could the router split this query faithfully at all. *Servable
-here* is what your suite actually gets: every subgraph that plan reaches is one
-this process serves. In a [partly-local supergraph](#a-supergraph-only-partly-local)
-they differ, and the plannable number alone reads optimistically — sketched
-here on a graph whose `billing` and `shipping` run elsewhere:
-
-```
-5/5 queries plannable locally (100%), 2 servable here
-  accounts 1, billing 1, reviews 1, reviews+shipping 1, shipping 1
-
-plannable, but nothing here serves what they reach (3) — name a schema for those subgraphs, fake them (subgraphs: { "shipping" => :fake }), or run these against a real router:
-  invoices.graphql         billing
-  shipping_quotes.graphql  shipping
-  tracking.graphql         shipping
-```
-
-`QUERIES=` picks the directory; by default each graph's report measures that
-graph's own `queries`, since a query written against one supergraph says
-nothing about the next one along. Planning
-needs the supergraph and nothing else, so this runs in CI with the SDL alone —
-with no subgraph loaded the report drops the second number and says it counted
-planning only. The subgraph line says which subgraphs each query touches, and
-anything refused is listed after it grouped by category, so one glance says
-whether the gap is one construct or many. (The first run above is the demo graph
-in `spec/support/federation`, not a real app's mix.)
-
-## Generating against a subgraph
-
-A raw subgraph SDL — `rover subgraph fetch`, `_service { sdl }`, or the
-`.graphql` in a service repo — loads too. It applies `@key`/`@external`/
-`@shareable`/… without declaring them (federation v1 leaves them implicit, v2
-imports them via `@link`), so the missing definitions are supplied on load;
-anything the file declares itself wins. Whatever the `@link` header says the
-directives are called is what's supplied — the bare `@key`, the namespaced
-`@federation__key`, or `@primaryKey` from
-`import: [{name: "@key", as: "@primaryKey"}]`. The header itself is read and
-then dropped: it describes the file, not the graph. The federation directives
-generate no code either way — codegen is query-driven.
-
-Reach for this when the subgraph is what you have, or to type an `_entities`
-query (below). But a subgraph is one service's slice of the graph, and its
-field shapes are not always the composed ones (an `@external` field is a
-reference, not something that subgraph serves) — for a client of the whole
-graph, feed the composed artifact.
-
-### `_entities`
-
-Every subgraph serves the entity resolver
-`_entities(representations: [_Any!]!): [_Entity]!`, and **no subgraph SDL
-contains it**: `_service { sdl }` and `rover subgraph fetch` print the
-*published* schema, where the plumbing is implicit. So it's supplied on the
-subgraph path — `_Any`, `_Service`, and an `_Entity` union over the file's own
-`@key`'d types — the same way the `@key`/`@external` definitions are. A file
-that declares its own keeps it.
-
-The read side is a normal union selection; `alias:` turns the
-single-entity case into a clean accessor (see
-[flat accessors](generated_modules.md#flat-accessors-with-alias)):
-
-```ruby
-GraphWeaver.extend_type("Query", alias: { entity: "_entities.first" }, optional: true)
-```
-
-The **input** side is generated. A representation must carry `__typename` and
-satisfy one of the entity's `@key` field sets — both hard requirements of the
-subgraph spec, and neither expressible in a bare `[_Any!]!`. So a query
-selecting entities gets a `Representations` builder per entity it can resolve,
-typed from the `@key` directives:
-
-```ruby
-UserQuery::Representations.user(id: "1")
-# => {"__typename" => "User", "id" => "1"}
-
-UserQuery.execute(reps: [UserQuery::Representations.user(id: "1")])
-```
-
-Key field sets are selection sets, so they're parsed as such:
-
-| `@key(fields:)` | Builder |
-|---|---|
-| `"id"` | `Representations.user(id: "1")` |
-| `"upc sku"` (compound) | `Representations.product(upc: "u", sku: 42)` |
-| `"id organization { id }"` (nested) | `Representations.listing(id: "1", organization: { id: "o" })` |
-| `"id lineItems { sku }"` over a `[LineItem!]!` | `Representations.order(id: "1", line_items: [{ sku: "a" }, { sku: "b" }])` |
-| `"id"` **and** `"serial"` (alternatives) | `Representations.variant(id: "1")` *or* `(serial: "s")` |
-
-A key field the schema declares as a **list** takes a list, and stays one on
-the wire — a single object there would describe an entity that doesn't exist,
-so it's refused rather than sent. The error spells the list hop `lineItems[]`,
-which is also how the generated key set records it.
-
-A type with one `@key` types its fields as **required kwargs**, so an
-incomplete representation is an `srb tc` error rather than a round trip. What a
-sig can't say is checked at runtime and raises `GraphWeaver::InputError` naming
-the type and the field:
-
-```
-Variant representation satisfies none of its @keys — supply "id", or "serial"
-Listing representation is missing @key "organization.id"
-```
-
-Key fields take the same loose input an `execute` kwarg does — a `params[:sku]`
-String converts to the `Int` the `@key` declares — and a value that converts to
-nothing raises `GraphWeaver::InputError` naming the representation and the
-field:
-
-```
-Product representation sku: expected an Int, got "forty-two"
-```
-
-A `@key` field whose name a generated method can't take as a kwarg — `class`,
-`hash`, or a Ruby keyword — takes a trailing underscore, the same one its prop
-took: `@key(fields: "class")` builds `Representations.room(class_: "suite")`
-and still sends `"class"` on the wire. A subgraph's `@key` field is not yours
-to rename, so weaver renames its own side rather than refusing.
-
-Only the declared key fields reach the wire — an extra key in a nested hash is
-dropped. Builders are emitted **only for the entities a query's `_entities`
-selection reaches** (codegen is query-driven, so a subgraph with fifty entities
-emits nothing for the forty-nine you didn't name), and a
-`@key(..., resolvable: false)` declares a key this subgraph does *not* answer
-for, so it builds nothing. Key fields typed as scalars get their registered Ruby
-type; anything else (a nested selection) is an open `Hash` the runtime narrows.
-Every shape above is a named example in
-[`spec/federation_spec.rb`](https://github.com/dpep/graph_weaver/blob/main/spec/federation_spec.rb).
+**Two numbers, because they answer different questions.** *Plannable* is about the
+graph — could the router split this query faithfully at all. *Servable here* is what
+your suite actually gets: every subgraph that plan reaches is one this process
+serves. In a [partly-local supergraph](#a-supergraph-only-partly-local) they differ,
+and the plannable number alone reads optimistically — so the report lists the
+queries that plan but reach a subgraph nothing here serves, each with the subgraph
+that stopped it and the three ways out (name a schema, fake it, or run it against a
+real router).
+
+`QUERIES=` picks the directory; by default each graph's report measures that graph's
+own `queries`, since a query written against one supergraph says nothing about the
+next one along. Planning needs the supergraph and nothing else, so this runs in CI
+with the SDL alone — with no subgraph loaded the report drops the second number and
+says it counted planning only. Anything refused is listed grouped by category, so
+one glance says whether the gap is one construct or many. (The run above is the demo
+graph in `spec/support/federation`, not a real app's mix.)