graph_weaver 0.6.1 → 0.7.0

data/docs/federation.md

@@ -10,52 +10,139 @@ 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.
+- **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.
+
 ## 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.
 
-**Calling subgraphs directly?** One client per subgraph, one `generate!` each.
-Registrations stay in one global registry, 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:
-
-```
-register_scalar("Money") matches no scalar in Billing::Schema — a typo, or a registration for another schema
-```
+**Calling subgraphs directly?** One graph per subgraph, declared once:
 
-`GraphWeaver.unmatched_registrations` is that same list as data, for a Rakefile
-or a spec that would rather gate on it than read it.
+```ruby
+GraphWeaver.graph :billing do
+  schema    "billing.graphql"
+  queries   "app/graphql/billing"
+  output    "app/graphql/generated/billing"
+  namespace "Billing"
+  register_scalar "Money", Money
+end
 
-Register everything once and read those lines, or scope each generation to what
-it needs and get a silent build:
+GraphWeaver.graph :directory do
+  schema    "directory.graphql"
+  queries   "app/graphql/directory"
+  output    "app/graphql/generated/directory"
+  namespace "Directory"
+  register_scalar "Person.birthday", Date
+end
+```
 
-```ruby
-GraphWeaver.register_scalar("Money", Money)
-GraphWeaver.generate!(schema: "billing.graphql",
-  queries: "app/graphql/billing", output: "app/graphql/generated/billing")
+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
+Rails initializer takes a lambda — `schema -> { Billing::Schema }` — see
+[getting started](getting_started.md#more-than-one-schema).)
 
-GraphWeaver.reset_registrations!
+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:
 
-GraphWeaver.register_scalar("Person.birthday", Date)
-GraphWeaver.generate!(schema: "directory.graphql",
-  queries: "app/graphql/directory", output: "app/graphql/generated/directory")
 ```
+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.
 
 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 `register_scalar("Person.birthday", Date)` as
-a field it doesn't own — a warning, not a failure.
+`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 (`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.
 
+## 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` to the schema
+class, which prints exactly what a composer wants:
+
+```ruby
+File.write("supergraph/accounts.graphql", Accounts::Schema.federation_sdl)
+```
+
+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.
+
+`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`.
+
+**Everyone else's.** From the team that runs it: a file they publish, `rover
+subgraph fetch` against their endpoint, or your schema registry.
+
+**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:
+
+```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
+rover supergraph compose --config supergraph-config.yaml \
+  --elv2-license accept > 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, 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).
+
 ## Generating against a supergraph
 
 A supergraph SDL works as-is. On load, GraphWeaver strips the composition
@@ -82,8 +169,8 @@ 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 also pair `@tag` + `@inaccessible`
-to build filtered API variants.)
+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
@@ -101,6 +188,54 @@ that hide nothing keep their field and are ignored: `@requiresScopes` / `@policy
 / `@authenticated` enforce at runtime, `@tag` / `@requires` / `@provides` /
 `@external` are metadata.
 
+### Contracts and variants
+
+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")
+}
+```
+
+```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)
+```
+
+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.
+
 ### The routing table
 
 Stripping the machinery answers "what does this graph look like". The other
@@ -156,65 +291,234 @@ 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 the *server* has drifted from your dump,
+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:
 
 ```sh
-rake graph_weaver:federation:diff SUPERGRAPH=supergraph.graphql
+rake graph_weaver:federation:diff
 ```
 
+**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" }`.
+
 It reads the routing table and the subgraph schemas loaded in this process —
-**no network** — so it belongs in the normal PR run, and it exits non-zero on
-drift so CI can gate on it:
+**no network** — and exits non-zero on drift, so CI can gate on it ([in
+CI](#in-ci)):
 
 ```
-supergraph.graphql: 1 stale, 1 not composed in (checked 1 of 3 subgraphs)
+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):
   Product.weight (products)
 
+shape — both carry these, with different types (recompose):
+  Warehouse.code (inventory): String! in the supergraph, ID! here
+
 not composed in — a schema here defines these, the supergraph doesn't carry them:
   Product.dimensions (Products::Schema)
 
-not checked — nothing here defines what the supergraph says these declare (running elsewhere, or the type is gone):
-  shipping (Shipment)
+not checked — no schema here matches what the supergraph says only these resolve (running elsewhere, or the subgraph is gone):
+  shipping (Shipment, Shipment.eta, Order.shipment)
 
 not checked — answered with fabricated data:
   reviews
 ```
 
-Both directions, because they mean opposite things: **stale** is "recompose",
-**not composed in** is "publish the subgraph". The stale side names the
-subgraph the supergraph blames — whose code to look at, whose team to talk to.
-"Defines" is deliberately looser than field-set 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`).
+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 type is
-gone), and [faked](#the-local-router). A clean report that quietly checked one
+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. (Under Rails it won't come up:
-the `federation:*` tasks eager-load the app, because `config.rake_eager_load`
-defaults to false and detection only sees loaded classes.)
+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
+```
 
-Detection is what drift breaks — a schema is recognized by what it defines, and
-a subgraph whose *types* are gone stops being recognizable — so the same
+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:
 
 ```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 },
 ).report
 ```
 
-`#to_h` is the JSON-ready `{"stale" => …, "uncomposed" => …, "skipped" => …,
-"faked" => …}`, and `#drift?` is what the task exits on.
+`#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.
+
+**`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:
+
+```ruby
+GraphWeaver::Federation::Drift.new(
+  supergraph: "supergraph.graphql",
+  subgraphs: { "accounts" => GraphWeaver::SchemaLoader.load(File.read("accounts.graphql")) },
+).report
+```
+
+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.
+
+**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.
+
+## 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.
+
+That gap is Apollo's to close, and it has two commands for it:
+
+```sh
+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".
+
+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
+`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
 
@@ -232,8 +536,19 @@ GraphWeaver.client = GraphWeaver::Testing::Router.new(
 )
 ```
 
+`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.
+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
@@ -241,6 +556,27 @@ 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,
@@ -285,7 +621,7 @@ 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 SUPERGRAPH=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
@@ -365,7 +701,9 @@ An operation that resolves in **one subgraph** goes over verbatim. One that
 `@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. Root fields that resolve
+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.
 
@@ -418,15 +756,34 @@ would be worse than refusing:
   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.** A subgraph reports `_entities.2.shippingEstimate`; you
-  get `topProducts.2.shippingEstimate`. `locations` are dropped rather than
-  pointing into a query you never wrote.
+- **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
@@ -445,7 +802,9 @@ matching symbol):
 | 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. Per query, like `@interfaceObject`: a subtree one subgraph answers whole sets its own context and plans normally |
+| 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 |
@@ -456,10 +815,21 @@ matching symbol):
 | 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 |
+| 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.
@@ -478,6 +848,25 @@ 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).
+
 ### Is it worth wiring up? Measure.
 
 The router's value is one number — the fraction of *your* queries it can plan —
@@ -485,7 +874,7 @@ and that depends on the shape of your graph and of your queries, so measure it
 rather than guess:
 
 ```
-$ rake graph_weaver:federation:coverage SUPERGRAPH=supergraph.graphql
+$ rake graph_weaver:federation:coverage
 17/17 queries plannable locally (100%), 17 servable here
   accounts 4, reviews 4, products+reviews 3, accounts+reviews 2, products 2, accounts+products 1, accounts+products+reviews 1
 ```
@@ -507,7 +896,9 @@ plannable, but nothing here serves what they reach (3) — name a schema for tho
   tracking.graphql         shipping
 ```
 
-`QUERIES=` picks the directory (default `GraphWeaver.queries_paths`). Planning
+`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
@@ -520,10 +911,13 @@ in `spec/support/federation`, not a real app's mix.)
 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`, including under a namespace as
-`@federation__key`), so the missing definitions are supplied on load; anything
-the file declares itself wins. The federation directives themselves generate no
-code — codegen is query-driven.
+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
@@ -569,8 +963,14 @@ Key field sets are selection sets, so they're parsed as such:
 | `"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
@@ -590,6 +990,12 @@ 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