graph_weaver 0.5.0 → 0.6.0

data/docs/federation.md

@@ -1,75 +1,105 @@
 # Federation
 
-Feed weaver any federation artifact: a supergraph, an API schema, a subgraph
-SDL, or the live router. It recognizes which it got — `SchemaLoader.load` (and
-`Client.new(path_or_sdl)`) take each as an SDL file or an introspection dump.
+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.
+
+## 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:
 
-## Pointing weaver at a supergraph
+```
+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.
+
+Register everything once and read those lines, or scope each generation to what
+it needs and get a silent build:
+
+```ruby
+GraphWeaver.register_scalar("Money", Money)
+GraphWeaver.generate!(schema: "billing.graphql",
+  queries: "app/graphql/billing", output: "app/graphql/generated/billing")
+
+GraphWeaver.reset_registrations!
+
+GraphWeaver.register_scalar("Person.birthday", Date)
+GraphWeaver.generate!(schema: "directory.graphql",
+  queries: "app/graphql/directory", output: "app/graphql/generated/directory")
+```
 
-A supergraph SDL works as-is. When `SchemaLoader` recognizes a composed graph it
-strips the composition machinery before building the schema — the synthetic
-`join__*`/`link__*` types and directive definitions, and every `@join__*`/`@link`
-application on the real types — so what codegen sees is the merged graph's
-ordinary type shapes, with no federation plumbing leaking into `schema.types`.
-(A pure AST rewrite of the SDL; plain schemas pass through untouched.) Field
-shapes — nullability, args, enums, inputs — are identical to the API schema, so
-your generated structs are correct.
+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.
+
+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.
+
+## Generating against a supergraph
+
+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.
 
 **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 weaver applies
-those declarations as written: a spec URL's name segment gives the namespace
-(`https://specs.apollo.dev/join/v0.3` → `join__`), `as:` renames it, and
-`import:` binds names into the root namespace, `{name: "@key", as: "@myKey"}`
-renames included. So a graph on fed 2.5+ auth strips its `@requiresScopes` /
-`@policy` / `@context` machinery (`federation__Scope`, `context__ContextFieldValue`,
-…) the same way `join__` goes, and a renamed `@inaccessible` still hides what it
-marks. A schema that declares nothing still gets the `join__`/`link__`/`core__`
-floor.
-
-Federation **v1** supergraphs (`@core` + `@join__owner`/`@join__type`) load the
-same way — the older spelling of the same machinery is stripped too.
-
-A supergraph is a **superset** of the API schema — it carries elements the
-public API hides, marked `@inaccessible`. Weaver removes those on load (below),
-so the schema it generates against is the API schema, not the superset.
+(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 federation-v2 directive marking an element as *present in the federated graph
-but removed from the public API schema*. You'll meet it 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 to the
-rest, then drop the directive to publish it. (Apollo contracts also pair `@tag`
-+ `@inaccessible` to build filtered API variants.)
-
-Weaver derives the API schema from the supergraph for you: 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 query, with no need for Apollo's
-JS tooling (`@apollo/federation-internals`) to subtract the API schema first;
-feed weaver the raw supergraph and you get the router's contract. (A pure SDL
-rewrite at load time — see
-[`SchemaLoader`](../lib/graph_weaver/schema_loader.rb).)
-
-The directive is matched by the **local name it was linked under**, so
-`@link(url: "…/federation/v2.5", import: [{name: "@inaccessible", as: "@private"}])`
-subtracts what `@private` marks.
-
-**Only on the supergraph path.** The subtraction runs when weaver recognizes a
-composed supergraph. Plain SDL and subgraph SDL are taken at face value:
-`@inaccessible` there is left as a directive and its fields stay queryable.
-
-Other federation directives hide nothing from the schema, so weaver keeps the
-field and ignores the directive: `@requiresScopes` / `@policy` / `@authenticated`
-enforce access at runtime; `@tag` / `@requires` / `@provides` / `@external` are
-metadata.
-
-The derivation is diffed against Apollo's own `composeServices` +
-`toAPISchema()` in
-[`spec/integration/api_schema_spec.rb`](../spec/integration/api_schema_spec.rb),
-over composed supergraphs carrying `@interfaceObject`, `@join__unionMember`,
-`@join__enumValue` and an aliased `@inaccessible` — identical in each.
+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.)
+
+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.
 
 ### The routing table
 
@@ -99,21 +129,17 @@ 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 — a table that silently ignores half a spec version
-answers confidently and wrongly. Callers refuse on a non-empty list; that is
-what bounds the maintenance tail across federation spec versions.
+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.
+about the table — the router refuses the queries that reach it and plans the rest.
 
-Weaver says it where it has the coordinate to say it about. 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:
+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:
 
 ```
 app/graphql/queries/product.graphql
@@ -160,34 +186,25 @@ not checked — answered with fabricated data:
 
 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, which is the sentence you want — whose code to
-look at, whose team to talk to.
-
-"Defines" is deliberately looser than field-set equality: a subgraph carries
-federation plumbing (`_entities`, `_service`) no supergraph has, and a field can
+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`).
-So a coordinate is compared only against the schemas that could *be* the
-subgraph the supergraph attributes it to, the uncomposed side reports only a
-field the supergraph's type doesn't carry **at all**, and underscore-prefixed
-fields never count.
 
 **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
 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, not a failure.
-
-Checking **none** of them is a failure, though — "checked 0 of 4" attached to
-exit 0 is a gate that passes whatever the subgraphs say, so the task exits
-non-zero and says so. 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.
+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.)
 
-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
-`subgraphs:` map [`Testing::Router`](#the-local-router)
-takes is accepted here, and a named schema skips detection:
+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
+`subgraphs:` map [`Testing::Router`](#the-local-router) takes is accepted here,
+and a named schema skips detection:
 
 ```ruby
 GraphWeaver::Federation::Drift.new(
@@ -224,10 +241,10 @@ 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.
 
-**[`examples/federation.rb`](../examples/federation.rb)** is the whole shape
+**[`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`](../spec/router_spec.rb) is the
+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.
 
@@ -237,8 +254,13 @@ graph and the `:fake` opt-in, each as a named example.
 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, and **two** matches refuse, naming both. **No** match
-isn't a refusal: that subgraph is simply served somewhere else (next section).
+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.
 
 Name them yourself when you'd rather have the wiring committed, or when
 detection can't settle it — including partially, with the rest derived:
@@ -316,6 +338,26 @@ 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
+```
+
+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
@@ -340,7 +382,10 @@ router.trace.map { _1[:subgraph] }   # => ["reviews", "products", "reviews"]
 `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.
+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,
@@ -392,19 +437,19 @@ 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.
 
-What it refuses, and why:
-
-Every category, spelled as `Unplannable#category` reports it:
+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. Per query, like `@interfaceObject`: a subtree one subgraph answers whole sets its own context and 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` | Apollo's router lets its injected key win over your alias and a spec-conformant server doesn't — there is no one answer to agree with |
+| 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) |
@@ -415,9 +460,23 @@ Every category, spelled as `Unplannable#category` reports it:
 | 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 subgraph two loaded schemas both fit refuses at construction too, as a
-`ConfigurationError` rather than an `Unplannable` (above) — it's a wiring
-mistake, not a query the router declines.
+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
+[`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).
 
 ### Is it worth wiring up? Measure.
 
@@ -435,7 +494,8 @@ $ rake graph_weaver:federation:coverage SUPERGRAPH=supergraph.graphql
 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:
+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
@@ -448,44 +508,22 @@ plannable, but nothing here serves what they reach (3) — name a schema for tho
 ```
 
 `QUERIES=` picks the directory (default `GraphWeaver.queries_paths`). Planning
-needs the supergraph and nothing else, so this still runs in CI with the SDL
-alone — no subgraph has to be loadable, and with none loaded the report drops
-the second number and says it counted planning only. The subgraph line says
-which subgraphs each query touches, so a graph whose queries all sit in one is
-visibly a different situation from one that stitches everywhere. Anything
-refused is listed after it, grouped by category, so one glance says whether the
-gap is one construct or many. The runs above are against the demo graph in
-`spec/support/federation`, not a real app's mix.
-
-### How the refusals are kept honest
-
-A double that quietly answered *differently* from the router would be worse
-than no double at all, so
-[`spec/integration/router_parity_spec.rb`](../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. Three outcomes, one of them
-a defect: match, refuse, or answer differently — and the spec fails on the
-third. It also checks that the gateway answers every refusal cleanly, so each
-refusal is a capability gap rather than a broken query. `make integration` runs
-it (node required).
-
-Alongside the corpus it runs boundary probes and a handful of queries where a
-subgraph deliberately **fails** — a resolver erroring under a stitched fetch, an
-entity nothing can resolve, a `@requires` fetch that comes back empty. Those are
-the ones that matter most: each is a case where a merge that doesn't
-re-propagate hands back a populated tree while the real router answers
-`data: null`, so it's checked against the real thing rather than against an
-expectation someone wrote down.
-
-## Pointing weaver at a subgraph
+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`, including under a namespace as
-`@federation__key`), so weaver supplies the missing definitions on load;
-anything the file declares itself wins. The federation directives themselves
-generate no code — codegen is query-driven.
+`@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.
 
 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
@@ -498,10 +536,10 @@ graph, feed the composed artifact.
 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 weaver supplies it on 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 it supplies the `@key`/`@external` definitions. A
-file that declares its own keeps it.
+`@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
@@ -536,15 +574,28 @@ Key field sets are selection sets, so they're parsed as such:
 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: which of two alternative keys you meant to supply, and
-whether a nested sub-hash carries the fields the key set declares. Only the
-declared key fields reach the wire — an extra key in a nested hash is dropped.
-
-Two bounds worth knowing. 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`](../spec/federation_spec.rb).
+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"
+```
+
+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).