graph_weaver 0.4.6 → 0.5.1

data/CHANGELOG.md

@@ -1,3 +1,1445 @@
+###  v0.5.1  (2026-09-07)
+- **A union's catch-all struct keeps the fields an interface fragment asked
+  for.** `... on Named { name }` under a union types `name` on every member the
+  query named, but the catch-all — the member it didn't name, including one the
+  schema grows later — carried only `__typename`, so a `name` the server
+  actually sent was dropped on the floor. Those fields are `T.nilable`: the
+  member that arrives needn't implement the interface. **Regenerate** to pick
+  it up.
+- **`schema_stale?` now recognises the drift a graphql-ruby server reports.**
+  It matched Apollo's one flat code plus a message pattern, but graphql-ruby —
+  which this library ships as its in-process client — names the rule that fired
+  in `extensions.code`. So a renamed type, a removed argument, an argument that
+  became required and four other drift shapes all raised without the one
+  sentence telling you to refresh the dump and regenerate, and `to_h` reported
+  `"schema_stale": false`.
+- **A cast failure keeps the server's own explanation.** A field that came back
+  null *with a reason* — a permission rule, a partial outage — raised only
+  Sorbet's nil complaint, because the generated envelope built `data` before it
+  read `errors`. The reason is now in the message. **Regenerate** to pick it up.
+- **Cassette anonymization missed `errors` and `extensions`.** It walked
+  `data` and nothing else, so a rejected request's error message — which
+  routinely quotes the input that caused it — and whatever the server hangs
+  off `extensions` went to disk verbatim, under a flag that says real data
+  never reaches it. **Re-run `rake graph_weaver:cassettes:anonymize` on any
+  cassette you've already committed**, or re-record it. Neither key has a
+  schema behind it, so both are now walked by shape: keys, nesting, nulls and
+  booleans survive and every string and number is replaced, with `path`,
+  `locations` and an error's `extensions.code` kept because they describe the
+  request rather than the data.
+- **Recording flags a credential that lands in the file.** A cassette gets
+  committed as written, and its query and variables can't be anonymized —
+  they're the key replay matches on. So the bytes headed for disk are checked
+  for the shapes that are unmistakable (a JWT, `AKIA…`, `ghp_…`, `xox…`,
+  `sk_live_…`, a PEM block, a `Bearer` header) and named on stderr once per
+  cassette. Nothing is rewritten; a password like `hunter2` has no shape, so a
+  quiet run still isn't a clean bill of health.
+- **An anonymized cassette no longer drops a key selected twice.** The
+  anonymizer kept the last occurrence's sub-selection where codegen merges
+  them, so `a { x } a { y }` came back holding only `y` — a recording that
+  then failed its own `cassettes:check`.
+- **Three generated types disagreed with the schema.** `srb tc` proves the
+  generated code is self-consistent, not that it is true, so each of these was a
+  lie the typechecker endorsed. **Regenerate** to pick them up:
+  - A field reached only through a `@skip`/`@include`-guarded occurrence, where
+    the same key is also selected unguarded, was typed as guaranteed. The server
+    legitimately omits it, so `from_h` raised `key not found` on a valid
+    response — and a union whose `__typename` arrived that way crashed its own
+    dispatch. Those children are nilable now, and the `__typename` case refuses
+    at generation as it already did for the plainer spelling.
+  - A narrowed abstract inside a non-null list made the *list* nilable
+    (`[Thing!]!` with `... on Widget` → `T.nilable(T::Array[…])`). Only the
+    elements can be nil; the array is always there.
+  - An input field the schema gives a default is optional, but a non-null one
+    emitted `const :x, String, default: nil` — so `x.upcase` typechecked and
+    was a `NoMethodError`.
+- **`rake graph_weaver:federation:coverage` no longer counts a subgraph as
+  served here when two loaded schemas fit it.** `Router.new` refuses that case
+  — picking either would be a coin flip — so the report was promising a run
+  the suite can't have. It now lands in the "nothing here serves what they
+  reach" list, whose advice (name a schema for those subgraphs) is the fix.
+- **A supergraph that renamed the join spec is now refused instead of read as
+  empty.** `@link(url: ".../join/v0.3", as: "j")` spells every marker `j__`,
+  which the routing table doesn't follow — so it reported a composed graph with
+  *no subgraphs* and nothing unsupported, and `Testing::Router` built happily on
+  top of that. It now lands in `unsupported`, so the router and
+  `federation:coverage` refuse at construction and say why.
+- **`rake graph_weaver:cassettes:anonymize` now finds an SDL schema dump.** It
+  opened `GraphWeaver.schema_path` directly instead of locating the dump the
+  way every sibling task does, so an app whose committed dump is
+  `schema.graphql` (what the generator writes for a supergraph) got a raw
+  `Errno::ENOENT`. A missing dump now says so.
+- **`rake graph_weaver:queries:check` now authenticates with the token your
+  app uses.** It re-introspects the url the dump records, but read
+  `GRAPHWEAVER_AUTH` rather than the ENV var the dump named — so an app
+  installed with `--auth MY_TOKEN` reached its private API while the check
+  401'd. Every re-introspection now goes through `SchemaLoader.source_transport`,
+  which is also now public.
+- **A `graphql: :router` example now starts from the same fabricated data
+  whether it runs alone or after two hundred others.** The router is built once
+  for the suite, and a faked subgraph kept fabricating from wherever the last
+  example left its sequence — so `rspec spec/foo_spec.rb:12` disagreed with the
+  same example in a full run, which is the opposite of what `--seed` promises.
+  `Router#reset!` is the example boundary (`reset_trace` still clears only the
+  trace); the rspec tag calls it for you.
+- **An override key given as a Symbol now pins.** `graphql_fake(overrides: { name: "Ada" })`
+  validated clean and silently fabricated a random value, because lookup is by
+  String — the exact silent-green failure the override validation exists to
+  prevent.
+- **A helper no longer contradicts `config.default_mode`.** With
+  `default_mode = :fake`, an untagged example calling `graphql_in_process`
+  raised *"this example is tagged graphql: :fake"* — naming a tag that wasn't
+  there, and blocking the untagged form the docs recommend. Only an explicit
+  tag can disagree with a helper now.
+- **A variable default that isn't a Boolean no longer reaches a subgraph.** An
+  enum or input-object default is a parser AST node; sending one put a
+  back-pointer to the lexer on the wire, and an input object raised
+  `NoMethodError` outside any rescue. Only `@skip`/`@include` read these, and
+  they read Booleans; a subgraph applies its own defaults from the variable
+  declaration it already receives.
+- The local router asks the schema for one type by name rather than rebuilding
+  the whole type map, at four sites — one of them per response row. On a
+  1200-type supergraph a stitched query over 200 rows was **5x** slower than it
+  needed to be; the cost is now flat in schema size.
+- **`graphql: :in_process` ran the committed schema dump instead of your live
+  schema class.** A dump loads as an anonymous `GraphQL::Schema` subclass, which
+  looks like a runnable class and has no resolvers — so every app that followed
+  `getting_started.md` (the generator always commits a dump) got a graphql-ruby
+  500 blaming its own resolver, and the error that was written to explain this
+  was unreachable. Nothing to do; if you worked around it with
+  `Testing.config.schema = MySchema`, that still works and still wins.
+- **`GraphWeaver.parse(query:)` accepts a `Pathname`.** `schema:` already did,
+  so `GraphWeaver.parse(schema: Rails.root.join("schema.graphql"), query:
+  Rails.root.join("app/graphql/queries/person.graphql"))` died on the query
+  argument with `undefined method 'end_with?'`. Same for `client.parse(path)`.
+- **`rake graph_weaver:cassettes:check` and `:anonymize` now find cassettes
+  from any working directory.** Both read `config.cassette_dir` raw, while
+  `Cassette.new` resolves it against `Rails.root` — so run from anywhere but
+  the app root, `check` aborted with "this checked nothing, so it proved
+  nothing" and `anonymize` silently did nothing, both while a spec run found
+  the same files fine. They now use the same resolution the recordings do.
+- **An `extend_type(alias:)` name a struct instance already answers to now
+  refuses** instead of silently overriding it. `alias: { hash: "…" }` emitted
+  `def hash`, which breaks every `Hash` and `Set` holding that struct;
+  `inspect`, `to_s`, `method` and `class` were the same story. A *wire field*
+  by any of those names was already refused, so this is the same rule reaching
+  the same case from the other side. **If generation now refuses an alias you
+  had**, rename it — the accessor it generated was overriding a Ruby method.
+
+###  v0.5.0  (2026-09-07)
+- **`graphql_in_process(SomeSchema)`** runs one example against that schema
+  class's real resolvers — the sibling of `graphql_fake`, and how a federated
+  app tests a single subgraph directly rather than through the stitched graph.
+  `graphql: :in_process` is that call with no argument, which runs
+  `config.schema` when it is a live class, so a non-federated app needs
+  nothing. A suite testing several subgraphs names one per example, which no
+  suite-wide setting could express.
+- **`Testing::Router` crosses a boundary on a nested `@key` or `@requires`.**
+  `@key(fields: "id organization { id }")` and
+  `@requires(fields: "origin { lat lon }")` used to refuse; they now plan, to
+  any depth, with the object carried in the representation the way the SDL
+  spells it (a null inner object included). **Nothing to do** — queries your
+  suite marked "run this one against a real router" may now simply run. Where
+  a type declares more than one `@key`, the plan takes the first one the
+  fetching subgraph can supply.
+- **`:nested_field_set` narrowed rather than disappeared.** It now names only
+  a nested field set no one *fetch* can build — `origin` resolving in one
+  subgraph and `origin.lat` in another, or a nested `@key` whose object a
+  `@requires` would half-fill from somewhere else. Either way the object
+  would arrive in pieces, and a representation comes from one fetch. If you
+  group refusals by category, that bucket shrinks; its message and
+  `docs/federation.md`'s table say what is left. `:chained_requires` is
+  unchanged and still a different refusal.
+- **`Testing.config.router` takes `subgraphs:` without `supergraph:`.** It
+  raised — "must be the arguments to build one, e.g. `{ supergraph: … }`" —
+  even where the committed dump already is the supergraph, which is the case
+  the docs call "no config at all" and the single most likely config a
+  federated app writes (marking a remote subgraph `:fake`). Either key alone
+  is enough now; a missing `supergraph:` derives exactly as it does with no
+  `config.router` at all.
+- **`graphql_fake(**options)`** builds the example's fake where the example
+  can say what it needs — `graphql_fake(overrides: { "Reader.orders" => [{}, {}] })`
+  — and returns it, so `#requests` is in reach. `graphql: :fake` is this call
+  with no options. Options had nowhere to go before: the tag builds its client
+  in a `config.before(:each)`, which rspec runs ahead of every group hook, so
+  `Testing.config.overrides` set in a `before` block was always too late and
+  failed silently, as wrong data.
+- **`GraphWeaver.client` is snapshotted and restored around *every* example**,
+  not only a tagged one. `graphql: false` used not to restore while
+  `graphql: :fake` did, which made "tag `:fake`, then throw the client away"
+  the idiom for cleanup. Building your own client is now a plain assignment in
+  a `before` block. An example that deliberately leaked a client into later
+  examples no longer can.
+- **`graphql: :none` is gone** — a second spelling of `graphql: false`, which
+  stays. Change any `:none` tag to `false`.
+- **`GraphWeaver.client!` names the tag** when `graph_weaver/rspec` is loaded:
+  `no client configured — tag the example graphql: :fake (or :in_process /
+  :router), or build one with graphql_fake`. "Set `GraphWeaver.client=`" was
+  advice for the wrong file.
+- **An override pins a subtree by naming only the fields the test is about.**
+  `overrides: { "Reader.orders" => [{ "status" => "PAID" }, {}] }` pins the
+  list's length and merges each element onto fabricated data — the rest of the
+  selection is still generated. It used to *replace*, so pinning one nested
+  field meant hand-writing the whole selection set in wire casing, and
+  under-supplying died as `key not found: "book"` at cast time. A pinned key
+  the query doesn't select is now refused (spellchecked, and naming the
+  response keys it could have been), for the same reason a typo'd coordinate
+  is. At a union or interface, a pinned object names its `"__typename"` and
+  gets that member rather than a random one.
+- **An override of `nil` pins the field null.** It used to read as "no
+  override" and fabricate a value.
+- **`Testing::FakeClient#requests`** records every `execute` in order
+  (`{ query:, variables:, operation_name: }`) — "did we send the right
+  variables", and "did we call it at all", without a hand-rolled spy.
+- **`FakeClient`'s selection-walking internals are private** (`each_field`,
+  `gather`, `load_operation`, …). Nothing documented called them; if you did,
+  `Object.new.extend(GraphWeaver::Selection)` is the supported host.
+- **The local router refuses a `@requires` whose field set names another
+  `@requires` field** (`chained_requires`). It used to answer: a prefetch sends
+  the entity's own `@key` and nothing else, so the inner requirement never
+  arrived and the field was computed from a representation missing its input —
+  the same field then holding two different values in one response. The
+  one-hop limit was documented but not enforced.
+- **An error path no longer names an injected `@key`/`@requires` alias.** A
+  stitched error came back as `["thing", "_gw_w"]`, a field no schema contains;
+  it is `["thing", "w"]` now, as a real router reports it.
+- **`@skip`/`@include` driven by a variable's declared default was ignored on a
+  boundary-crossing field**, so `query($show: Boolean = true) { … @include(if: $show) }`
+  called with no variables silently dropped the field. graphql-ruby applies an
+  operation's defaults; the local router read only what the caller passed.
+- **`Testing::FakeClient` raises a GraphQL validation error for an unknown
+  field**, as every other client in the slot does. It used to die with
+  `NoMethodError: undefined method 'type' for nil` from inside the fabricator —
+  undiagnosable, and the commonest mistake there is: a query drifting ahead of
+  the schema dump, or a typo in one written inside an example.
+- **The local test router plans a union or interface at a subgraph boundary.**
+  `search { ... on Track { playCount } ... on Artist { upcomingEvents { … } } }`
+  — a feed, a search page, any polymorphic list — used to be refused
+  (`abstract_boundary`), because a representation names one concrete
+  `__typename` and the planner runs before any data exists. It now plans one
+  branch per concrete type the supergraph says the subgraph can answer with,
+  asks the fetch for `__typename`, and buckets the returned objects by it at
+  execution time — one `_entities` fetch per concrete type, which is what a
+  real router does. Nothing to change; queries that were refused now run.
+  - The `crosses_subgraph` refusal category is **gone**, and
+    `abstract_boundary` now means only one thing: the supergraph doesn't record
+    which concrete types a subgraph answers an abstract type with (no
+    `@join__unionMember`/`@join__implements`, and the type in more than one
+    subgraph). Match on `Unplannable#category` for either of those and you must
+    change it.
+  - A fragment whose type condition can't hold at a position is now dropped
+    rather than refused — `... on Note` under a field whose subgraph has no
+    Note in that union never matches, and a real router answers `{}` there too.
+- **A query file whose name can't spell a constant now names the file.**
+  `01_home_featured.graphql` reported `module_name: must be a constant name,
+  got "01HomeFeaturedQuery"` and left you to find which of thirty files it
+  meant; it now names the path and says the fix is a rename. It's a
+  `GraphWeaver::Error` too, so `rake graph_weaver:generate` aborts on it
+  instead of burying it under a backtrace — rescue `ArgumentError` for this
+  and you must change it. An explicit `module_name:` argument still raises
+  `ArgumentError`.
+- **`rails g graph_weaver:install <supergraph>` recognises a composed
+  supergraph** and says what changes because of it: the `federation:*` tasks,
+  and that `graphql: :router` runs specs against your real subgraph resolvers.
+  The initializer it writes says so too.
+- **Every `rake graph_weaver:federation:*` task was a silent no-op in a stock
+  Rails app.** Rails defaults `config.rake_eager_load` to false, and subgraph
+  detection only sees *loaded* schema classes — so `federation:subgraphs`
+  reported `nil` for every subgraph and `federation:diff` printed "checked 0 of
+  4 subgraphs" and exited **0**, a CI gate permanently green while checking
+  nothing. The tasks now eager-load the app first, and detection resolves.
+- **`federation:diff` fails when it compared against nothing** (exit 1, naming
+  what to do). Comparing against *some* subgraphs is still a pass — a
+  partly-local supergraph is a supported setup — but a comparison against none
+  of them proved nothing. If your subgraphs all run elsewhere, drop the task
+  from CI; it has nothing there to gate.
+- **The absent-subgraph refusal names the cause.** It advised `subgraphs: { … }`
+  on a `Router.new` an rspec `graphql: :router` example never calls. It now
+  leads with the usual cause — the schema class isn't loaded yet, so
+  eager-load it — and names `GraphWeaver::Testing.config.router = { subgraphs:
+  … }` as the way to name one under the tag.
+- **Subgraph-mapping refusals are `GraphWeaver::ConfigurationError` (was
+  `ArgumentError`)** — `rescue GraphWeaver::Error` around `Testing::Router.new`
+  now catches them, as `docs/errors.md` said it would. Rescue `ArgumentError`
+  for these and you must change it. The rule the docs now state: what the
+  library *concludes*, having read your schema, is a `GraphWeaver::Error`; an
+  argument wrong on its face (`pool_size: must be >= 1`) stays an
+  `ArgumentError`. An ambiguous-detection refusal also names each candidate
+  schema once, instead of repeating a reloaded constant.
+- **The local test router refused every mutation that stitched below its root**,
+  with a message claiming its root fields "span subgraphs" when there was one
+  root field in one subgraph — and advice (split it per subgraph) that couldn't
+  be followed. It now plans any mutation whose root fields share a subgraph:
+  they go over as one document and that subgraph serializes them, and what
+  hangs below a root is an ordinary read afterwards. The refusal is left for
+  root fields that genuinely span subgraphs, where the message is true.
+- **The local router honoured `@skip`/`@include` on a field but ignored it on a
+  fragment spread or inline fragment that crossed a subgraph boundary** — it
+  answered a selection the operation had excluded, and ran an extra subgraph
+  fetch to do it. Folding a same-type fragment into its parent dropped the
+  fragment node, and its directives with it. They now move onto the selections
+  they guarded, and a fetch is skipped entirely when everything it was for is
+  excluded (so `trace` matches what a real router does). A field and the
+  fragment around it both carrying the same directive refuses, as
+  `conditional_fragment` — one selection can't hold two conditions of one name.
+- **`rake graph_weaver:federation:diff` reported false drift for every input
+  object**, so a correct supergraph failed the CI gate with advice to recompose
+  something that wasn't broken. An input object exposes its members as
+  `arguments`, not `fields`, and the check only asked for fields.
+- **A `Pathname` works anywhere a schema path does** — `GraphWeaver.new`,
+  `generate!(schema:)`, `SchemaLoader.load`. `Rails.root.join("schema.graphql")`
+  previously failed as `undefined method 'lstrip' for an instance of Pathname`.
+- **`Transport::HTTP`'s `pool_size:` defaults to `RAILS_MAX_THREADS`** (else 5,
+  as before) — the variable Rails already sizes its own connection pool from,
+  because it is the same question. A threaded app that raised its thread count
+  no longer silently queues behind five sockets.
+- **A saturated pool says so.** The first request that has to wait for a
+  connection logs a warning naming the wait and the ceiling; later ones log at
+  debug. Queueing was previously indistinguishable from a slow server, which
+  mattered most under a fiber scheduler — `async`/Falcon multiplexes fine, but
+  nothing sets `RAILS_MAX_THREADS` there, so the default capped it at 5 with no
+  signal. See `docs/transports.md`.
+
+#### One `execute`, one way to pass a client (**breaking**)
+
+Every client answers the same call — `execute(query, variables:,
+operation_name:)`, returning the raw response hash. Three objects a user holds
+used to disagree with that, and each disagreement was a bug waiting.
+
+- **`Client#execute` is that contract now**, so `GraphWeaver::Retry.new(client)`,
+  `Testing::Sequence.new(client, fake)` and a cassette recorder over a client
+  all work. Its one-shot parse-and-run sugar moved to **`Client#run` /
+  `#run!`** (and `GraphWeaver.run` / `.run!` for the throwaway-client form):
+  **rename `client.execute!(query, **vars)` to `client.run!(query, **vars)`.**
+- **A generated module takes the per-call client as a kwarg**: rename
+  `PersonQuery.execute(some_client, id: "1")` to
+  `PersonQuery.execute(client: some_client, id: "1")`. Variables are
+  unaffected — `$client` was already refused at generation. It is also what
+  makes a mistyped variable name itself: `PersonQuery.execute(id: "1")` on a
+  query that declares no variables now raises `unknown keyword: :id` instead of
+  blaming the client. **Regenerate** (`rake graph_weaver:generate`);
+  `rake graph_weaver:verify` fails until you do.
+- **`GraphWeaver.resolve_transport` is gone.** Nothing needs unwrapping any
+  more. A client that can't execute is still refused, by the module it was
+  passed to — whose name is now in the message.
+- A module parsed from a `Client` bakes that client rather than its transport.
+  For a client built from a schema *dump* (no transport), `execute` now says
+  `this client has no transport (built from a schema dump)` instead of quietly
+  running on `GraphWeaver.client`.
+- `$transport` is a usable GraphQL variable name again — the generated body has
+  no such local.
+
+#### One reset, one plurality rule (**breaking**)
+
+- **`GraphWeaver.reset_scalars!`, `clear_scalars!`, `reset_enums!` and
+  `reset_type_helpers!` are gone.** `GraphWeaver.reset_registrations!` is the
+  clean slate between tests; to reset one registry, call the same name on
+  `GraphWeaver::Codegen`.
+- **Every directory setting is a list — `queries_paths`, `generated_paths`,
+  `fragments_paths`** — and *every entry is read*, by `generate!`,
+  `verify_generated!`, `check_queries` and `load_queries!` alike. (0.4.x
+  dropped a plural `queries_paths` because only `load_queries!` walked it;
+  that divergence is what the singular was protecting against, and it is gone.)
+  **Rename any `queries_path` / `generated_path` / `fragments_path` you set or
+  read** — assigning a String still works (`GraphWeaver.queries_paths =
+  "app/graphql/queries"`), and `generated_paths.first` is the one directory
+  `generate!` writes into. `schema_path` stays singular: a run reads one
+  schema, so a second entry would name a dump nothing opens.
+
+- `rake graph_weaver:queries:check` prints an unparseable query's position once
+  rather than twice, and `GraphWeaver.check_queries` returns the documented
+  `"message"` / `"line"` / `"column"` shape for parse errors too — the position
+  is no longer folded into the message.
+- Docs: a spec-local `generated_paths` entry needs an explicit
+  `GraphWeaver.load_generated!` (in Rails the Railtie has already run by then),
+  and belongs outside `spec/support/`, whose files rspec-rails requires itself
+  in sorted order. A registration naming one of your own constants goes in a
+  `to_prepare` block — the same rule the in-process client already follows —
+  rather than the `require Rails.root.join(...)` dance.
+- **Removing an `extend_type` registration no longer bricks the app.**
+  Generated files carry `include GraphWeaver::TypeHelpers::Foo`, so dropping
+  the registration made boot fail — and because `rake graph_weaver:generate`
+  depends on `:environment`, the regeneration that would repair it failed the
+  same way. The graph_weaver tasks now skip loading generated modules (none of
+  them reads one), so `rake graph_weaver:generate` repairs the tree. Outside a
+  task, the dangling include now raises a `GraphWeaver::Error` naming the
+  registration that went missing and how to recover, instead of a bare
+  `NameError` pointing into generated code.
+- **A cancelled request no longer leaks its socket.** `Transport::HTTP`
+  closed a connection of unknown state with a bare `rescue`, which catches
+  only `StandardError`. A fiber scheduler cancels with `Async::Stop`, which
+  descends from `Exception`, so cancelling an in-flight request walked past
+  the cleanup and left the socket open until GC. Affects any app under
+  `async`/Falcon with per-request timeouts. Nothing to do — the fix is
+  internal.
+- `rake graph_weaver:queries:check` and `federation:diff` flush stdout before
+  aborting, so a piped CI log shows the details before the verdict rather
+  than after it.
+- `generate!`, `verify_generated!` and `check_queries` accept a **path or SDL
+  string** for `schema:`, like every other schema slot in the library. A String
+  used to reach `schema.validate` as itself and die with `undefined method
+  'validate' for an instance of String`.
+
+- **`#parse` on anything that holds a schema**, not just `Client`:
+  `GraphWeaver::InProcess`, `Testing::FakeClient` and `Testing::Router` gain it
+  (and `#load_queries!`) from the new `GraphWeaver::Parsing` mixin. Replace
+  `GraphWeaver.parse(schema: router.schema, client: router, query: q)` with
+  `router.parse(q)`. `Retry` holds no schema and has no `#parse` — parse from
+  what it wraps. Nothing changes for `Client`, and the client contract is
+  untouched: a bare `GraphQL::Schema` class still fills the client slot.
+- **`graphql: false` (or `graphql: :none`) opts an example out of
+  `config.default_mode`** — no client is installed, so the example can wire its
+  own. Previously a default swept up every untagged example with no way out,
+  and both spellings raised "is not a mode"; that message now names the opt-out
+  alongside the modes.
+- Docs: `graphql_context` is setup, so `docs/testing.md` now shows it in a
+  `before` block for a group sharing one identity, with the inline form kept
+  for one-offs. The per-example reset runs ahead of group hooks, so a
+  group-level `before` re-applies from the same baseline every time.
+
+- `examples/federation.rb` — a runnable federated-testing example, and the first
+  one that needs no network: three real subgraphs, a boundary-crossing query
+  through a generated module, `router.trace`, and a plan-time refusal. Guarded
+  by `spec/examples_spec.rb`, which runs it.
+- Docs: the local router moved from `docs/testing.md` to `docs/federation.md`.
+  `testing.md` now covers which client an example runs against; `federation.md`
+  covers what a federated graph does. No behaviour change — update any bookmark
+  to `docs/testing.md#the-in-process-router--graphql-router`, now
+  `docs/federation.md#the-local-router`.
+- **`graphql: :in_process` no longer hunts for the live schema class.** It runs
+  against `GraphWeaver::Testing.config.schema`, or the schema class your client
+  already runs in-process — one sentence, no heuristic. The third fallback
+  (`Testing::LiveSchema`, which searched every loaded `GraphQL::Schema` for one
+  defining everything the reference schema declares) is **deleted**. It only
+  ever applied to an app whose client points at a *different* API, and under
+  Zeitwerk it failed on the first `:in_process` example anyway, since an
+  autoloaded schema isn't loaded until something names it. Such an app now sets
+  `config.schema = MySchema`; when neither source is there, the error says so.
+- **One positive predicate on `Response`, not two.** `#ok?` is gone; `#success?`
+  is the survivor, so the pair is `errors?` / `success?`. `success?` is what
+  `Process::Status` and `Faraday::Response` call it, and `ok?` reads as HTTP
+  200 — which a GraphQL response carrying errors also is. Semantics unchanged:
+  partial data alongside top-level errors is **not** a success.
+- **`Testing::Config#auto_fake` is gone** — it was the pre-tag spelling of
+  `config.default_mode = :fake`. Use that.
+- **`rake graph_weaver:federation:diff` no longer loads the test harness.**
+  `Federation::Drift` needed one thing from it — the list of loaded schema
+  classes — and did `require "graph_weaver/testing"` from inside itself to get
+  it, pulling faker into a task that fabricates nothing. That question, and
+  "does this schema define this coordinate", now live in `GraphWeaver::Schemas`,
+  shared with `Testing::Subgraphs`. Measured over the fixture supergraph, the
+  task loads 15 files instead of 323 (253 of them faker's).
+  `Testing::Subgraphs.loaded` moved with it: call `GraphWeaver::Schemas.loaded`.
+- Internal: `codegen/enum_type.rb` held `extend_type`, the type-helper and alias
+  registries and `GraphWeaver::TypeHelpers` — none of them enums, so a search
+  for `extend_type` landed in a file named for something else. Those moved to
+  `codegen/type_helpers.rb`; `enum_type.rb` now holds `EnumType` and the enum
+  registry, mirroring `scalar_type.rb`. No API change.
+- **`register_enum` and `extend_type` say where to register** when handed a
+  constant's *name* instead of the constant. Passing a String is the natural
+  workaround for "`uninitialized constant PetKind` in my initializer", and the
+  answer is Rails' own: autoloading is set up after `config/initializers` run,
+  so register from a `Rails.application.config.to_prepare` block — which
+  `rake graph_weaver:generate` also runs before generating. Both registries
+  still take the constant itself; a name would be a second spelling that
+  couldn't reach `fallback:` or `map:` anyway, since those name enum *members*.
+
+#### Scalar coercion is one switch (**breaking**)
+
+`coerce:` takes `true`/`false` only — the Symbol form is gone. It was a third
+way to ask one question (*may a variable of this scalar accept loose input?*)
+and the only one that also made you answer *how*, which the scalar already
+knows: `Int`/`Float` convert, anything with a `cast:`/`serialize:` pair parses,
+and a pass-through scalar can't.
+
+**What to do:**
+
+- `coerce: :to_i` / `coerce: :to_f` — write `coerce: true`. Generated output is
+  unchanged.
+- `coerce: :to_s` on `String`/`ID` — drop it and call `.to_s` at the call site.
+  Those have nothing to convert from, so `coerce: true` on one raises now
+  instead of emitting a no-op.
+- any other Symbol on a custom scalar — give the scalar a `cast:`/`serialize:`
+  pair and `coerce: true`.
+
+`GraphWeaver.auto_coerce` is unaffected, and `coerce: true` is now exactly what
+it turns on for one scalar instead of all of them.
+
+#### One shared module, not three (**breaking** — regenerate)
+
+`GraphQLInputs`, `GraphQLUnions` and `GraphQLEnums` are now one `GraphQLTypes`.
+They were three constants, three config knobs and three file shapes for one
+idea — a type shared across query modules — and the rule now fits in a
+sentence: **a type shared across query modules lives in the shared module and is
+aliased in.**
+
+**What to do:** run `rake graph_weaver:generate` (`verify` fails until you do,
+naming the stale files). Every generated file changes: a query module opens with
+one `require_relative "types"` instead of up to three, and its aliases read
+`AdoptionInput = GraphQLTypes::AdoptionInput`. On disk, `enums.rb`, `inputs.rb`,
+`inputs/` and `unions.rb` become `types.rb` (the manifest) plus one file per
+type under `types/` — the old files are pruned for you, since pruning keys off
+the generated header. If you referenced `GraphQLInputs::PetFilter` (or the other
+two) by hand, spell it `GraphQLTypes::PetFilter`.
+
+`GraphWeaver.inputs_module=` / `unions_module=` / `enums_module=` are now
+`GraphWeaver.types_module=`, and `generate!`/`verify_generated!` take one
+`types_module:` in place of three.
+
+One namespace also removes the aliasing *between* the shared artifacts: an input
+struct's props and a union member's selections spell their enums bare now, being
+lexically inside the same module. The manifest requires the enum files first for
+that reason.
+
+New: a shared fragment whose name is already a schema type in that module is
+refused at generation, naming both — a fragment is named by you, a type by the
+schema, and one module is one namespace. Previously they lived apart and could
+never meet.
+
+#### Has anyone changed a subgraph without recomposing?
+
+    rake graph_weaver:federation:diff SUPERGRAPH=supergraph.graphql
+
+A committed supergraph is a snapshot of a composition, and nothing checked that
+it still described your subgraphs — so it could quietly promise a graph that no
+longer exists. This reads the routing table against the subgraph schemas loaded
+in this process, needs **no network**, and exits non-zero on drift, so it gates
+a PR alongside `graph_weaver:verify`.
+
+Both directions, because they mean opposite things: **stale** (the supergraph
+carries `Product.weight`, nothing here defines it — recompose) and **not
+composed in** (a schema here defines `Product.dimensions`, the supergraph
+doesn't carry it — publish the subgraph). Comparison is deliberately looser
+than field-set equality, which would be wrong both ways: a subgraph carries
+federation plumbing no supergraph has, and `@external`/`@shareable` put a field
+in more than one subgraph.
+
+A supergraph is routinely only partly local, so the report names three states —
+checked, not here, and answered with fabricated data — and the headline counts
+them. Only drift fails; absence is a supported setup.
+`GraphWeaver::Federation::Drift` is the same thing as data (`#to_h`, `#drift?`).
+
+#### Validation errors name the subgraph behind the type
+
+When the schema dump is a composed supergraph, `rake graph_weaver:queries:check`
+brands each error with who resolves the type it points at:
+
+    app/graphql/queries/product.graphql
+      4:5  Field 'dimensions' doesn't exist on type 'Product' (products, reviews)
+
+`Product.dimensions` says what broke; `(products, reviews)` says whose code to
+look at. A plain schema has no routing table and is unaffected.
+
+- New: `SchemaLoader::RoutingTable#declared_fields`, `#declares?`, `#responsible`.
+
+#### A partly-local supergraph now works
+
+The testing router serves a supergraph composed from several services when only
+some of them run in this process. A subgraph no loaded schema defines is
+**absent** rather than an error at construction, so the router builds and every
+query that doesn't reach those fields runs normally. A query that does reach
+them is refused at plan time, before anything executes, naming the subgraph and
+the field that reached for it.
+
+    subgraphs: { "reviews" => :fake }   # answer an absent subgraph with fabricated data
+
+Faking is opt-in and never silent: a faked fetch is marked `faked: true` in
+`router.trace`, logged at `:warn` per fetch, and listed by `router.faked` and
+`#inspect`. It is deliberately not surfaced as a response error — that would
+make `execute!` raise, defeating the point.
+
+- `Testing::Subgraphs.resolve` now returns only the subgraphs this process
+  serves instead of raising when one has no candidate. Two candidates still
+  refuse, naming both.
+
+#### One tag picks what a test runs against
+
+`auto_fake` and `config.router` each installed a client for **every** example
+and refused to coexist, so a suite had to choose fakes or real resolvers once,
+for everything — and running in-process against a live schema had no configured
+mode at all. Now an rspec tag says it per example, or per group:
+
+    it "renders the empty state", graphql: :fake do        … end
+    it "authorizes drafts",       graphql: :in_process do  … end
+    describe "checkout",          graphql: :router do      … end
+
+`rspec --tag graphql:router` runs one mode's examples. The tag is namespaced
+under one `graphql:` key on purpose: a bare `:fake` or `:router` would collide
+with an app's own metadata and silently change which client an unrelated
+example runs against.
+
+**Nothing needs configuring.** Each mode derives what it runs against and
+refuses — naming what it looked for — rather than guessing. The schema is
+`config.schema` if you set one, else the committed dump, else the schema
+`GraphWeaver.client` talks to. `:in_process` finds the live schema *class*: the
+one your client already runs in-process, else the loaded class defining
+everything that schema declares (the rule `subgraphs:` detection already uses).
+`:router` plans against the dump when the dump is a composed supergraph — a
+federated suite whose checked-in dump is the supergraph needs no config at all.
+
+- **New:** `graphql_context(current_user: user)` sets the context your
+  resolvers see. It merges onto `config.context` and is reset before the next
+  example, so an example running as somebody else can't leak into the one
+  after. Pass a block to scope it. Under `graphql: :fake` it refuses — there
+  are no resolvers to receive it.
+- **New:** `config.default_mode` is what an untagged example runs against
+  (`nil`, the default, leaves `GraphWeaver.client` alone). It replaces
+  `config.auto_fake`, which still works as the old spelling of
+  `default_mode = :fake`.
+- **New:** `config.context` — the baseline every `:in_process` and `:router`
+  example starts from. `config.router = { context: … }` now refuses and points
+  here; the per-example reset would have overwritten it.
+- `GraphWeaver.execute`, `.new` and `Client.new` now refuse a *client* where a
+  schema source belongs — an `InProcess`, `Retry`, transport or fake used to
+  crash with `undefined method 'lstrip'`. The message names both ways to say
+  what you meant.
+
+#### Ruby-keyword field names now generate
+
+A result key that underscores to a Ruby keyword — `pageInfo { next }`,
+`filter { in }` — no longer refuses to generate. A prop is only ever read off
+a receiver, so `const :next` is fine; the one bare read, an `alias:`
+delegator's first hop, now spells `self.next`. Output props keep only the ban
+the input side already had: names every `T::Struct` already answers to
+(`class`, `hash`, `serialize`). If you aliased a query around this, you can
+drop the alias and regenerate. `GraphWeaver::Codegen::RESERVED_PROPS` is gone
+— `STRUCT_METHODS` is the whole rule now.
+
+- `optional: true` on an `alias:` no longer hides a path segment the schema has
+  no field for. It still skips a field this query didn't select — that is what
+  it is for — but a typo, or the classic `findPets` where the path is the Ruby
+  prop chain, now raises and says which of the two it looks like. If an
+  optional alias resolved only through a query-level rename (`{ renamed: meta }`),
+  it will now raise on queries that don't select that key.
+- **New:** `GraphWeaver.reset_enums!`, `GraphWeaver.reset_type_helpers!` and
+  `GraphWeaver.reset_registrations!` — the registry resets scalars already had.
+  `reset_registrations!` is the clean slate to reach for between tests.
+- An alias error no longer names the same type twice when a query module and
+  its root type share a name.
+
+#### Testing::Router now plans a real query, not just a single-subgraph one
+
+`GraphWeaver::Testing::Router` used to hand one operation to one subgraph
+verbatim and refuse anything that crossed a boundary. It now splits at the
+crossing, refetches the entity from its `@key` through
+`_entities(representations:)`, and stitches — batching every node at a level
+into one call, running root query fields that span subgraphs as one fetch
+each, and fetching a `@requires` field set from the subgraph that holds it
+before the field that needs it. On the demo corpus that moves 10/17 queries
+plannable to 17/17. It still refuses, at plan time, every shape it can't
+answer the way a real router would.
+
+`subgraphs:` is now **optional**: each subgraph's Ruby schema is derived from
+what the loaded schemas define, and refuses rather than guesses when two
+match or none do. An explicit map (or a partial one) still wins, and is now
+checked the same way — a mis-wired entry fails at construction naming what it
+doesn't define, instead of surfacing three fetches later.
+
+- **New:** `config.router = { supergraph: "supergraph.graphql" }` in
+  `graph_weaver/rspec` runs every example against your real subgraph
+  resolvers.
+- **New:** `rake graph_weaver:federation:subgraphs` prints the subgraph map
+  detection sees, with the evidence for each match.
+- **New:** `Testing::Router#context` is settable, so one example can run as a
+  different user without rebuilding the router.
+- `Testing::Unplannable`'s `:requires` category is **gone** — the gap it named
+  is closed. `:root_fields_span` now applies only to mutations (query roots
+  are planned). New categories: `:no_key`, `:abstract_boundary`,
+  `:nested_field_set`, `:shadowed_key`.
+- The coverage report's second line now names every subgraph a query touches
+  (`accounts+reviews`), not just the one it ran in.
+- `rake graph_weaver:schema:diff`, `schema:refresh` and `cassettes:anonymize`
+  now load the Rails environment first, so an initializer's settings apply.
+
+**`GraphWeaver::Testing::Router` — a local federation router for tests.** Give
+it a supergraph and your subgraph schema classes and it satisfies the client
+slot, so `GraphWeaver.client = router` runs every generated module against real
+resolvers in-process: no gateway, no node, no sockets. It plans one shape — a
+query whose every field resolves in a single subgraph, passed to that subgraph
+verbatim — and raises `Unplannable` (a `GraphWeaver::Error`) for anything that
+crosses a boundary, at plan time, before any subgraph runs. See
+[docs/testing.md](docs/testing.md#a-local-federation-router).
+
+**`rake graph_weaver:federation:coverage SUPERGRAPH=…` says how much of your
+query set that router can plan**, and groups every refusal by what stopped it —
+the number that decides whether wiring it up is worth it. Planning needs the
+supergraph alone, so it runs in CI with no subgraph loadable.
+
+**A supergraph's routing table is now readable:
+`GraphWeaver::SchemaLoader.routing_table(supergraph)`.** `load` strips the
+`@join__*` machinery to get the API schema; this keeps it — `owners("Product",
+"shippingEstimate") # => ["reviews"]`, each type's `@key` field sets, and which
+copies are `@external`. A `@join__` directive it hasn't been taught lands in
+`unsupported` rather than being skipped.
+
+**`Representations.<entity>` for an entity the query didn't select now says
+what to do.** Builders are query-driven, so `Representations.warehouse(...)`
+raised a bare `NoMethodError` naming nothing. It now names the builders this
+query does have and the selection to add (`... on Warehouse { __typename }`).
+
+**Shared-fragment directories are scanned recursively, and `.gql` files count.**
+The scan was `fragments/*.graphql`, so `fragments/person/fields.graphql` — how
+anyone with sixty fragments organizes them — was skipped in silence, and a
+`.gql` file was ignored even though `parse("x.gql")` reads one. A duplicate
+fragment name now names both files that define it.
+
+**Query directories are scanned the same way — recursively, `.gql` included.**
+`queries/admin/pets.graphql` produced nothing at all: no file, no error.
+`generate!`, `check_queries` and `client.load_queries!` now walk the tree, and
+`.gql` no longer leaks its extension into the module name. Directories organize
+queries but do not namespace them — `queries/admin/pets.graphql` is still
+`PetsQuery` in `pets_query.rb` — so two files with the same base name are
+refused at generation, naming both, rather than one silently overwriting the
+other's generated file. The scaffolded `graphql.config.yml` matches
+(`**/*.{graphql,gql}`).
+
+**`execute` now takes one kwarg per declared variable, always — a single
+required input-object variable is no longer flattened into per-field kwargs.**
+`mutation($input: AdoptionInput!)` generated `execute!(name:, species:, …)`,
+but adding any second variable generated `execute!(input:, …)` instead — so an
+unrelated edit to a query silently reshaped every call site, and the rule
+couldn't be stated without its exception. It also made a schema's own field
+names load-bearing: a field named `client` or `in` can't be a kwarg and can't
+be renamed, so flattening quietly declined and the surface moved again.
+**Rewrite affected call sites to pass the input as one kwarg:**
+`AdoptMutation.execute!(input: { name: "Rex", species: "DOG" })`, or
+`input: AdoptMutation::AdoptionInput.new(name: "Rex", species: Species::Dog)`
+for the field-by-field static check.
+
+**An input field named after a Ruby keyword no longer makes a schema
+ungeneratable.** `StringQueryOperatorInput.in` — the standard Hasura/Gatsby
+filter shape — raised "would become prop 'in', which collides with a Ruby
+keyword", with no way out: an input field is the schema's name, not yours, and
+`extend_type alias:` is output-only. But `prop :in` is legal Ruby, and nothing
+reads an input prop bare (`serialize` goes through `public_send`), so the
+refusal was over-broad. Input fields named `in`, `end`, `def`, `nil` and the
+rest now generate. A field colliding with a method every struct defines
+(`serialize`, `to_h`, `class`, `hash`) is still refused — those break at
+require time. Output structs are unchanged: a result key *can* be renamed, in
+the query.
+
+**A variable named `$client` no longer generates a file that won't parse.**
+`query($client: ID!)` emitted `def self.execute(client = nil, client:)` — a
+`SyntaxError` raised at app boot from `load_generated!`, arbitrarily far from
+the query that caused it, while `verify_generated!` reported the tree as
+current. Generation now refuses `$client`, `$variables` and `$transport` — the
+three locals the generated `execute` body owns — naming the fix. **Rename such
+a variable in the query (`query($clientId: ID!)`) before regenerating.**
+
+**`auto_coerce` no longer erases the typing of String/ID variables.** It mapped
+both to `#to_s`, which widened their kwargs to `T.anything` — the majority of
+real variables, statically unchecked, in exchange for a cast that can't fail.
+`auto_coerce` now covers only the conversions that are conversions (`Int`→`to_i`,
+`Float`→`to_f`) plus scalars with a full cast/serialize pair. **If you relied on
+a String/ID kwarg accepting anything, opt in per scalar:**
+`GraphWeaver.register_scalar("ID", String, coerce: :to_s)`.
+
+**An anonymous operation is now named after its module — in the query text and
+in `OPERATION_NAME`.** Requests started carrying `operationName` so servers and
+APMs can attribute traffic, but the constant was only set when the `.graphql`
+document named its operation — and anonymous is what the docs show, so every
+trace arrived `anonymous` and the feature did nothing for the documented happy
+path. `person.graphql` holding `query($id: ID!) { ... }` now emits
+`query PersonQuery($id: ID!) { ... }` with `OPERATION_NAME = "PersonQuery"`.
+Both halves move together: a server rejects an `operationName` its document
+doesn't declare. A document that names its own operation is left untouched.
+
+**Cassette files no longer store the request twice — re-record them.** Every
+entry carried a `key:` (the normalized query + variables) *and* a `query:` and
+`variables:` again, and replay matched on `key:` alone: editing the half a
+reviewer reads changed nothing, editing the other half broke replay while the
+file still looked right. The key is now derived from `query`/`variables`/
+`operationName` at load, so the file holds the request once and diffs are real.
+**Existing cassettes must be re-recorded** (`GRAPHWEAVER_RECORD=1`, or delete
+the file) — this also covers cassettes of anonymous operations, which stopped
+matching when entries started keying on `operationName`.
+
+**`MissingRecording` now prints the variables — the part that usually differs.**
+It printed the whole query and omitted the variables entirely, so the common
+miss (same query, different variables) showed you 60 lines identical to the
+YAML and nothing about the mismatch. The message now leads with the request's
+variables, says what was recorded for that query (`1 entry recorded for this
+query, with variables {"id" => "1"}`), and prints the query as one truncated
+line.
+
+**A first run with no cassette and no `client:` no longer raises
+`MissingRecording`.** There is no request yet, so it raises `GraphWeaver::Error`
+naming the actual situation. **Rescue `GraphWeaver::Error` if you were catching
+`MissingRecording` for this case.**
+
+**`Cassette.use` is now `GraphWeaver::Testing.cassette` — rename your calls.**
+It never returned a `Cassette`; it returns a *client* (a recorder or a replayer)
+to hand to `execute`, and the name said otherwise. `Cassette` is now only the
+file — `.new`, `#size`, `#anonymize!`.
+
+**Record mode with no `client:` now raises instead of replaying.**
+`GRAPHWEAVER_RECORD=1` on a `Testing.cassette(name)` call with nothing to record
+against quietly served the stale recording, so "re-record everything" produced a
+half-refreshed cassette set with no signal. **Pass `client:` to every call you
+want re-recorded.**
+
+**`Recorder.new(..., anonymize:)` is gone.** It was unreachable through the
+factory and duplicated `Testing.config.anonymize`. **Set the config flag** —
+that's the one way to anonymize, with `rake graph_weaver:cassettes:anonymize`
+as the cleanup tool for cassettes recorded before you turned it on.
+
+**`FakeClient.new` no longer requires `schema:`.** Every other option fell back
+to `Testing.config`; this one didn't, even though `config.schema` already
+auto-locates the committed dump. `FakeClient.new` now works on its own, and
+says what to set when no schema resolves at all.
+
+**`GraphWeaver.queries_paths` (plural) is gone — use `queries_path`.**
+`generate!` and `check_queries` read the singular (the first entry) while
+`load_queries!` walked the whole list, so a second queries directory produced
+modules at runtime that `rake graph_weaver:generate` never generated and
+`verify` never checked — silently. Queries are single-schema by design. **If
+you appended a second queries directory, fold it into the first** (or run a
+second `generate!` with its own `queries:`). `generated_paths` and
+`fragments_paths` stay plural; they genuinely load from several places.
+
+**One GraphQL enum is now one Ruby type.** A schema enum a query touches — as
+a variable, in a result, or both — is emitted once per schema into
+`generated/enums.rb` as `GraphQLEnums::<Enum>`, and every query module aliases
+it. Before, an enum read out of a result got a class named for the response key
+and nested in the struct that selected it (`SearchQuery::Result::Search::Pet::Species`),
+while the same enum used as a variable got a module-level one — so whether a
+schema enum was one Ruby type or three depended on what else the query happened
+to reference, and handing a value from one query into another's variable raised
+a `TypeError` that wasn't even a `GraphWeaver::Error`.
+
+**Regenerate, and expect enum constants to move.** A nested enum path in app
+code becomes the query module's own alias — `SearchQuery::Species` — or
+`GraphQLEnums::Species`; `srb tc` finds them all. The enums a shared fragment's
+union members select are hoisted too, so `unions.rb` now aliases them rather
+than re-emitting them.
+
+**The shared module names no longer depend on your output directory.** They are
+`GraphQLInputs`, `GraphQLUnions` and `GraphQLEnums`, full stop. The old rule
+camelized the parent of `generated/` unless it was on a hardcoded blocklist, so
+`output: "gen2"` gave you `Gen2Inputs` and renaming `app/graphql/generated` to
+`app/gql/generated` renamed a public constant. **A multi-schema layout must now
+name its modules explicitly** — `GraphWeaver.inputs_module=` /
+`unions_module=` / `enums_module=`, or `generate!(inputs_module:, ...)` — in the
+same initializer that already gives each schema its paths. `GraphWeaver.inputs_module`
+and `unions_module` no longer take an output-path argument.
+
+**One registration registry, not two.** `Client#register_scalar`,
+`#register_enum`, `#register_enums` and `#extend_type` are **deleted** — a
+client-scoped registration was invisible to `GraphWeaver.generate!` (the rake
+tasks have no client), so the console typed a field richly and the checked-in
+code silently generated `T.untyped`. **Move any `client.register_*` /
+`client.extend_type` call to the `GraphWeaver.` form** (an initializer, next to
+the rest of your config). The one thing client scoping bought — two servers
+disagreeing about a scalar — is what the per-field coordinate form is for:
+`GraphWeaver.register_scalar("User.birthday", Date)`.
+
+Also gone with it: `GraphWeaver.register_enums` (bulk) — there was never a
+`register_scalars` to match it, so call `register_enum` per line — and
+`GraphWeaver.reject_positional_map!`, now folded into the one
+`Codegen.register_enum` that every door reaches (so all three doors give the
+same "the value map is a keyword" error instead of a bare arity complaint).
+`Codegen.parse` / `.generate` / `.generate_inputs` / `.generate_unions` no
+longer take `scalars:`/`enums:`/`types:`.
+
+**`generate!` now takes a Client where it takes a schema** — `GraphWeaver.generate!(schema: api)`,
+`verify_generated!`, `check_queries` and `parse` all accept one, so the object
+you built in the console is the object the build step wants and no schema dump
+is needed. `client:` still means what it meant (a constant name to bake as
+`DEFAULT_CLIENT`) and still refuses a live object.
+**Rails integration fixes, found by running the gem in a real Rails app.**
+
+- **Production boot no longer raises `uninitialized constant
+  Generated::PersonQuery`.** The default `generated_path` is
+  `app/graphql/generated`, which Zeitwerk claims as an autoload root, while
+  the files there define top-level constants. Development (lazy) was fine and
+  eager loading was not, so this only showed up in production or
+  `rails zeitwerk:check`. The Railtie now hides the generated directory from
+  the loader; nothing to configure.
+- **`rake graph_weaver:generate` runs your initializer again.** The tasks
+  asked whether Rails' `:environment` task existed at *load* time, but Rails
+  defines it after every Railtie's `rake_tasks` block, so the answer was
+  always no. Generation and `verify` therefore ran without booting the app —
+  silently dropping every `register_scalar` / `register_enum` / `extend_type`
+  in `config/initializers`, and generating code that disagreed with the
+  running app. **Regenerate**: if you register anything in an initializer,
+  your committed generated files are wrong, and `rake graph_weaver:verify`
+  will now say so.
+- `generate`, `verify` and `schema:diff` report a `GraphWeaver::Error` the
+  way `schema:refresh` already did — the message, and a non-zero exit,
+  instead of a rake backtrace through codegen.
+
+**`rails g graph_weaver:install` takes any source `GraphWeaver.new` takes.**
+The source is one positional argument — an endpoint, a schema class or an
+existing dump all work the same way:
+
+```sh
+rails g graph_weaver:install https://api.example.com/graphql
+rails g graph_weaver:install MyApp::Schema        # in-process, no socket
+rails g graph_weaver:install db/schema.graphql    # a dump you already have
+```
+
+The initializer reflects the form chosen: a schema class is resolved in a
+`to_prepare` block (it is autoloaded, so an initializer can not read it, and a
+dev reload replaces the class object), and a dump you already have becomes
+`GraphWeaver.schema_path` rather than being copied. `--auth` and the
+introspection step are url-only; a source that can not use them, a constant
+that does not resolve, and a class that is not a schema are all refused
+before any file is written.
+
+**Generated struct names now come from the query's own field names.** A struct
+is named for the response key that selects it — `stargazers` becomes
+`Stargazers`, `edges` becomes `Edges` — so its name is a function of its own
+position in the query and nothing else. Names came from GraphQL *type* names
+before, disambiguated by field name only on collision, which meant **a second
+selection of the same type renamed the first**: a silent break in checked-in
+code your app references. Deep queries could also collide outright and refuse
+to generate.
+
+**Regenerate, and expect renames.** Nearly every nested struct changes name
+(`PersonQuery::Result::Person::Pet` becomes `...::Person::Pets`), and app code
+naming one won't typecheck until it's updated — `srb tc` finds them all. The
+payoff: adding, removing, or reordering an unrelated selection can never move
+a name again.
+
+- The key is used verbatim, with no pluralization heuristic — a list field
+  `pets` generates `Pets`. To pick a different name, alias the field in the
+  query: `pet: pets { name }` generates `Pet` (and a `.pet` accessor).
+- Union and interface members keep their type-condition names (`... on Book`
+  gives `Book`), inside a container named for the field; a union hoisted from
+  a shared fragment is still named for the fragment.
+- Two ties that walk order used to settle now resolve on their own: fields
+  sharing one collapsed union type take the first of their keys
+  alphabetically, and a name that would shadow the struct it nests in
+  (`pet { pet { ... } }`) takes a numeric suffix (`Pet2`).
+
+**Requests now send `operationName`** — every graph_weaver request used to be
+anonymous in Apollo Studio, Hasura, and any APM that keys traces, rate limits
+and slow-query reports on it. Generated modules emit their operation name as
+`OPERATION_NAME` beside `QUERY` and send it on the wire; a raw query string
+handed to a transport falls back to the name in the document. In-process
+execution passes it to `Schema.execute(operation_name:)`, which also makes a
+multi-operation document selectable there.
+
+To get the benefit, **name your operations** — `query Person($id: ID!)`, not
+`query($id: ID!)` — and regenerate. An anonymous operation still works and
+sends no `operationName`.
+
+Three breaking changes come with it:
+- **The client-slot contract widened to
+  `execute(query, variables:, operation_name: nil)`.** If you wrote your own
+  transport, client, or test double, add the kwarg — a client that doesn't
+  accept it now raises `ArgumentError: unknown keyword: :operation_name`. A
+  graphql-ruby `Schema` class already takes it, so bare schemas in the client
+  slot are unaffected. Subclasses of `GraphWeaver::Transport` only implement
+  `post(body)` and need no change.
+- **Cassettes are keyed on `operationName` too**, so two operations in one
+  document can't collide. Cassettes recorded from a *named* operation before
+  this release no longer match — re-record them
+  (`GRAPHWEAVER_RECORD=1 bundle exec rspec`). Anonymous ones are unaffected.
+- **`GraphWeaver::Transport.log_tag` takes an operation name, not a query
+  string** (`log_tag(query)` → `log_tag(operation_name)`); the constant
+  `Transport::OPERATION_NAME` is now `Transport::OPERATION_NAME_PATTERN`, since
+  generated modules define an `OPERATION_NAME` of their own.
+
+Codegen bug fixes from the library review (all with regression coverage):
+- Narrowing (`... on X` and nothing else) now reads the match off `__typename`
+  when the selection carries it, instead of off "the object came back empty".
+  Selecting `__typename` guaranteed a non-empty object, so **every non-matching
+  member was cast into `X`'s struct** — loudly when it had a non-null field,
+  silently when all its fields were nullable. Regenerate: any query mixing
+  `__typename` with a single type condition (the `_entities { __typename
+  ... on Widget { … } }` federation shape) was mistyped and now filters
+  correctly.
+- A dispatched union/interface now requires its `__typename` to be unaliased and
+  free of `@skip`/`@include` — `from_h` reads it unguarded, so either would have
+  raised at runtime. Fix the selection if generation now refuses it.
+- **Unions and interfaces generate per named condition, plus one catch-all
+  `Other`** — not one struct per schema member. A two-condition query against
+  GitHub's `Node` (278 implementations) went from 5,386 lines / 279 structs to
+  162 lines / 4. **Regenerate, and expect member names to move**: a type your
+  query names no fields on is now `Other` rather than its own struct, so a
+  `case` over the members needs an `Other` branch (`T.absurd` will tell you).
+  In exchange, a `__typename` the query doesn't name — including a **member the
+  schema grows after you generate** — deserializes into `Other` instead of
+  raising `unexpected __typename`, so adding a union member upstream stays the
+  non-breaking change GraphQL says it is.
+- `@skip`/`@include` on an inline fragment or a named spread now makes the
+  fields under it nilable, as it always did for a directly-marked field —
+  previously they kept non-null typing and a `data.fetch`, so a skipped block
+  raised `key not found`. The narrowing guard sees the fragment's own directive
+  too. Conversely, a field selected both conditionally and unconditionally is no
+  longer over-nilable: one unguaranteed selection doesn't unmake the guarantee.
+- List variables coerce per element, so an enum inside a list accepts its wire
+  value the way a scalar enum already did (`sort: ["POPULARITY_DESC"]` used to
+  raise `NoMethodError: undefined method 'serialize' for String`). Input-object
+  and custom-scalar elements coerce in lists too.
+
+- Federation schemas that previously wouldn't load now do:
+  - a supergraph whose `schema` definition carries a non-`@link` directive
+    (`@tag`, `@composeDirective`, a composed custom one) no longer dies with a
+    `GraphQL::ParseError` pointing into a document you never wrote.
+  - **raw subgraph SDL loads** — what `rover subgraph fetch`, `_service { sdl }`,
+    or your service repo's `.graphql` gives you. The federation directives a
+    subgraph applies but doesn't declare (`@key`, `@external`, `@shareable`, …)
+    are supplied on load, for both fed-1 and `@link`-style subgraphs. Note the
+    `@inaccessible` subtraction stays supergraph-only: a subgraph keeps those
+    fields, because it is not the public contract.
+- A schema that won't build now raises `GraphWeaver::Error` naming the artifact
+  we took the source for (supergraph / subgraph / plain SDL / introspection),
+  instead of whatever graphql-ruby's internals happened to raise — a
+  `NoMethodError`, a `ParseError` pointing into a document you never wrote, a
+  bare `RuntimeError`. **Rescuing the raw graphql-ruby classes no longer
+  catches these.** The `@inaccessible` cascade also prunes a directive
+  definition's own arguments.
+- **Single-line SDL loads.** `SchemaLoader.load("type Query { hi: String }")` —
+  the shape you type in a console — was rejected as "unsupported schema format",
+  because a string had to contain a newline to count as content rather than a
+  path.
+- Rejecting a schema source is branded too, so the error class no longer depends
+  on which branch rejected it: an unsupported format and an unreadable file both
+  raise `GraphWeaver::Error` (were `ArgumentError` and `Errno::ENOENT`). A bare
+  host now says so — `"graphql.anilist.co" looks like a host; did you mean
+  "https://graphql.anilist.co"?` — instead of pointing at the file system.
+- Cassette recording accepts a `GraphWeaver::Client` — the call
+  `docs/cassettes.md` shows (`Testing.cassette("github", client: live)`),
+  which failed with `ArgumentError: missing keywords`. And a client that can't
+  `execute` is now rejected on the spot, with its class named, rather than
+  surfacing later as `NoMethodError … for an instance of Hash`.
+- Generated structs answer `respond_to?` the way `method_missing` behaves, so
+  `struct.method(:nmae)` gets the same "did you mean" hint the direct call does.
+- `@oneOf` input objects enforce exactly one field. The schema can't express it
+  — every `@oneOf` field is nullable — so the struct accepted zero or many and
+  the server rejected the round trip; supplying the wrong number now raises
+  `GraphWeaver::InputError` naming the type and the keys. **Regenerate** to pick
+  it up.
+- An enum whose values differ only in case (`enum E { active ACTIVE }`) is
+  refused at generation naming both wire values, instead of emitting two
+  `Active` constants and raising `RuntimeError: Enum values must be assigned to
+  constants` when the file loads. **Map such an enum onto one of yours**
+  (`register_enum`). `AB`/`A_B` and `IN_PROGRESS`/`INPROGRESS` still generate
+  fine — they name distinct constants.
+- A `.graphql` file that won't parse raises `GraphWeaver::ValidationError`
+  **naming the file**, instead of a bare `GraphQL::ParseError` whose `[6, 1]`
+  pointed into a document you never wrote — fragment inlining parses on the
+  `generate!` path before `Codegen#generate`'s rescue could brand it. Fragment
+  files get the same treatment.
+- Generated `from_response` shape-checks the envelope, so a malformed one stays
+  under `GraphWeaver::Error`. A non-object `data`, a `Hash` (or an array of
+  strings) for `errors`, and non-object `extensions` all escaped as a raw Sorbet
+  `TypeError` — the `data` one from `from_h`'s sig, before the struct's own
+  rescue could see it. A body that isn't an object at all deserialized to an
+  empty envelope (`String#[]` answers `"data"` with nil); it now raises.
+- The generated `from_h` rescues `StandardError`, not just
+  `TypeError`/`ArgumentError`/`KeyError` — a registered scalar whose cast raises
+  anything else (`JSON::ParserError`, `URI::InvalidURIError`, your
+  `Money::ParseError`) escaped the umbrella. **Regenerate** to pick both up.
+- A document holding more than one operation is refused at generation. Only the
+  first was ever typed, and the whole document went on the wire with no
+  `operationName`, so the request came back "Must provide operation name" —
+  **split multi-operation files into one operation each.**
+- Result keys are checked before they become props, so generation refuses what
+  used to be an unloadable file. Two keys that underscore to the same prop
+  (`{ name Name: name }` — a plain alias, no exotic schema needed) raised
+  `ArgumentError: Attempted to redefine prop :name` at require time; so did a
+  field named `class`, `hash`, `send` or `frozen?`, which `T::Props` won't let a
+  struct redefine. **Alias the field in the query** (`classValue: class`) — the
+  error names the key and the spelling. The same reserved set now covers input
+  fields, which only checked Ruby keywords and `serialize`/`to_h` before.
+- **Global registrations are validated against the schema**, like client-scoped
+  ones always were: `GraphWeaver.extend_type("Medai", …)` (or `register_scalar` /
+  `register_enum`) used to be a silent no-op, which is the failure mode
+  `docs/getting_started.md` step 3 walks you straight into — it now raises at
+  generation with the spellchecked hint. Registrations are global (see above),
+  so **drop any that names a type the schema you generate against doesn't
+  have**. The built-in scalars are exempt — a schema with no `Date` isn't a
+  mistake.
+- `extend_type(requires:)` and `register_enum(requires:)` check each path is
+  loadable at registration, as `register_scalar(requires:)` already did and
+  `docs/scalars.md` already promised — a typo fails now, not in the generated
+  file.
+- Docs: `docs/testing.md` passed the client to generated `execute` as a `client:`
+  kwarg — it's positional. `README.md` had module naming backwards for the
+  documented path (a file's module comes from the **file** name, not the
+  operation name). `docs/federation.md` covers subgraph SDL, federation v1
+  supergraphs, and that `@inaccessible` is subtracted only on the supergraph
+  path. `docs/cassettes.md` names `MissingRecording` correctly.
+- **Federation namespaces are derived from the schema's own `@link`/`@core`
+  declarations** instead of a hardcoded `join__`/`link__`/`core__` list — the
+  spec URL's name segment gives the namespace, `as:` renames it, and `import:`
+  binds names into the root namespace (`{name: "@key", as: "@myKey"}` included).
+  Four things this fixes:
+  - a graph using fed-2.5+ auth (`@requiresScopes`/`@policy`/`@context`) no
+    longer leaks `federation__Scope`, `federation__Policy` or
+    `context__ContextFieldValue` into `schema.types`;
+  - a supergraph that renamed a spec (`@link(url: ".../join/v0.3", as: "j")`)
+    strips its `j__*` machinery — it previously failed to load at all;
+  - **a renamed `@inaccessible`** (`import: [{name: "@inaccessible", as:
+    "@private"}]`, or `as:` on the inaccessible spec) hides what it marks. It
+    was missed entirely before, so the derived API schema kept fields the
+    router does not serve and codegen over-permitted them. **Regenerate** if
+    your supergraph renames it.
+  - a `@core`-only fed-1 schema, and any composed graph carrying no `@join__`
+    marker, is now recognized as composed rather than loaded as plain SDL
+    (`core__Purpose` used to survive, and `@inaccessible` went unsubtracted).
+
+- **Subgraph SDL loads with the entity resolver it serves.** No published
+  subgraph SDL contains `_entities`/`_service` — `rover subgraph fetch` and
+  `_service { sdl }` both print the schema, where the plumbing is implicit — so
+  the one query only a subgraph can describe couldn't be typed against the
+  artifact you have. Weaver now supplies `_Any`, `_Service` and an `_Entity`
+  union over the file's own `@key`'d types, alongside the `@key`/`@external`
+  definitions it already supplied. Supergraphs and plain SDL are untouched;
+  a file declaring its own `_entities` keeps it.
+- **Typed `_entities` representations.** A query selecting entities now
+  generates a `Representations` builder per entity it can resolve, typed from
+  the `@key(fields:)` directives the subgraph SDL carries:
+  `UserQuery::Representations.user(id: "1")` → `{"__typename" => "User", "id"
+  => "1"}`. `__typename` is injected, key fields are typed from the schema, and
+  a single `@key` makes them **required kwargs** — so an incomplete
+  representation is an `srb tc` error, not a round trip. Compound (`"upc sku"`)
+  and nested (`"organization { id }"`) key sets are parsed as the selection
+  sets they are; a type with two alternative keys takes them optionally and
+  raises `GraphWeaver::InputError` naming the type and what's missing when
+  neither is satisfied. Builders are emitted only for entities the query
+  actually reaches, and a key marked `resolvable: false` gets none.
+  **`Representations` joins `Result`/`QUERY` as a reserved module-level name**
+  — a shared fragment hoisting to it is now refused.
+
+Transport improvements from the same review:
+- **`Transport::HTTP` pools its connections** (`pool_size:`, default 5) instead
+  of serializing every request behind one socket and one mutex. The mutex was
+  held across the whole network round trip, so one transport — which is what
+  `GraphWeaver.client = api` gives a Rails app — allowed exactly one request in
+  flight process-wide. Against a 10 ms-latency server, 8 threads × 10 calls:
+  1059 ms before, 281 ms with the default pool of 5 (~3.8×). Sockets still open
+  lazily, stay keep-alive, and are dropped on any error so the next call
+  reconnects. **Lower `pool_size:` if your server counts connections per
+  client**; raise it to match a threaded web server's thread count.
+- Both transports now send `Accept: application/graphql-response+json,
+  application/json;q=0.9` — the media type GraphQL-over-HTTP requires a
+  conforming client to accept, so a spec-conformant server can finally use the
+  newer status-code semantics — and `User-Agent: graph_weaver/<version>`, so
+  server operators can attribute the traffic. Previously the only header sent
+  was `Content-Type`, and net/http supplied `Accept: */*`. `headers:` still
+  overrides both; a prebuilt `Faraday::Connection` keeps whatever it carries.
+- **`Transport::Faraday` takes `open_timeout:`/`read_timeout:` and defaults them
+  to 10s/30s**, the same as `Transport::HTTP`. It had no timeout knobs at all,
+  so it inherited net/http's 60s/60s — 6× and 2× the documented defaults. Both
+  timeouts now also thread through the client: `GraphWeaver.new(url,
+  read_timeout: 5)` works whichever transport is picked. Passing a timeout
+  alongside a prebuilt `Faraday::Connection` raises, as `headers:` already did.
+  The Faraday transport also logs its adapter at `:info` — the default
+  `net_http` one opens a connection per request, which was invisible.
+- **New `GraphWeaver::InProcess`**, wrapping a live graphql-ruby schema class —
+  `GraphWeaver.new(MySchema, context: { current_user: user })`. In-process
+  execution worked but was blind in three ways: nothing supplied a `context:`,
+  so a resolver reading `context[:current_user]` got nil (surfacing as "Cannot
+  return null for non-nullable field Query.me"); all logging lived in
+  `Transport#execute`, which an in-process schema bypasses, so not one line at
+  DEBUG; and a resolver raise came out as a bare `RuntimeError` where the same
+  failure over HTTP is a `ServerError`, so `rescue GraphWeaver::Error` caught
+  one and missed the other. A resolver raise is now a `ServerError` (status
+  500) with the original kept as `#cause` — in-process, the real backtrace is
+  the point. **A bare schema class still works in any client slot**; the
+  wrapper is an upgrade, not a requirement.
+- **`ServerError` carries the response `#headers`** (names downcased), plus
+  `#retry_after` (seconds or HTTP-date, per RFC 9110) and `#rate_limited?`. The
+  `Net::HTTPResponse` was always in hand and thrown away, so recovering
+  `x-ratelimit-remaining` or a request id meant monkey-patching the transport.
+  A `post` override may now return a third element, the headers; returning the
+  documented `[status, body]` pair stays correct.
+- **`Retry` honours `Retry-After`** — the server's delay wins over the
+  configured backoff, clamped to `max:` and not jittered. Related: **408 and
+  429 now retry by default.** They were treated as ordinary 4xx ("your bug,
+  retrying won't fix it"), which for the one status that exists to say "come
+  back later" was exactly backwards, and left `Retry` incorrect against GitHub
+  and Shopify. Pass `retry_if:` to restore the old behaviour.
+- **A throttling predicate, spelled the same everywhere**: `ServerError#throttled?`
+  (429, or a 503 that says when to come back) and `QueryError#throttled?` /
+  `Response#throttled?` (a throttle code in the errors array). An API says "slow
+  down" with an HTTP status or with a code in a 200 body, and callers shouldn't
+  have to know which. The codes are `GraphWeaver::GraphQLError::THROTTLE_CODES`
+  — Shopify's `THROTTLED`, GitHub's `RATE_LIMITED`, and the common Apollo/Hasura
+  spellings — so `retry_codes:` takes the constant instead of a hand-written
+  string. `QueryError#to_h` gains `"throttled"` alongside `"schema_stale"`.
+- `Transport::HTTP` takes `ca_file:`/`ca_path:`/`cert:`/`key:`/`verify_mode:`,
+  forwarded to `Net::HTTP.start` — a private CA or mTLS no longer means
+  switching to Faraday, which was the real but undiscoverable answer. Passing
+  one to an `http://` url raises instead of quietly doing nothing.
+- **An instrumentation seam**: `GraphWeaver.instrumenter = ->(event, payload,
+  &block) { ... }`, a no-op until set, wrapping every request — over the wire
+  and in-process, one seam for both. `ActiveSupport::Notifications` becomes a
+  two-line adapter. The one event is `GraphWeaver::EXECUTE_EVENT`; its payload
+  carries `:url`, `:schema`, `:operation` and `:status`, and deliberately not
+  the query or variables (those are PII, and belong at debug on the logger
+  where the level gates them). See `docs/logging.md`.
+Developer-experience fixes (all with regression coverage):
+- **FakeClient override keys are validated against the schema.** A typo'd key
+  (`"Person.nmae" => "Daniel"`) pinned nothing, and the example passed against
+  random fake data — a test that had quietly stopped checking what it claims to.
+  Keys now raise, spellchecked, at `FakeClient.new` and at `Testing.configure`
+  when a schema is already set. Bare field-name keys (`"name"`) still work;
+  **fix or drop any key that doesn't name a field in your schema.**
+- Codegen validation errors name the position they already captured: each
+  message is prefixed `4:5`, and `queries/typo.graphql:4:5` when the file is
+  known (`Codegen.new`/`Codegen.generate` take it as `path:`), instead of
+  leaving a project of thirty query files to search by hand.
+- A strict `alias:` whose path doesn't fit a query now names the query that
+  failed and ends with `— pass optional: true to skip selections that don't
+  fit`, the documented way out.
+- Generation lists the custom scalars it had no registration for at `info`
+  (`3 unregistered custom scalars → T.untyped: …`). Informational — a scalar
+  without a codec is a legitimate choice, just no longer a silent one.
+- `Response#ok?` (and `#success?`) — the positive form of `errors?`.
+- `FakeClient#schema` reads back the schema responses are fabricated against,
+  which is how to reach it under `auto_fake`, where `GraphWeaver.client` is the
+  fake; `Testing.config.schema` reads back too.
+New:
+- **`rake graph_weaver:queries:check` — which of your queries a schema change
+  broke.** Re-introspects the url the dump records (leaving the dump alone) and
+  validates every checked-in query against the server as it is now,
+  reporting file plus line:col plus message and exiting non-zero on any
+  failure, so it drops into CI. `GraphWeaver.check_queries` returns the same
+  thing as data (`{path => [{"message", "line", "column"}]}`, empty when
+  everything validates); pass `schema:` to check a schema you already have
+  without touching the network. Complements `graph_weaver:verify`, which asks
+  the different question of whether the committed Ruby is stale.
+- `verify_generated!` (and `rake graph_weaver:verify`) compares generated files
+  with line endings normalized, so a checkout under git's `autocrlf` no longer
+  reports every generated file as stale.
+- New [editor support](docs/editors.md) doc: the `graphql.config.yml` that gives
+  VS Code and RubyMine validation, autocomplete and hover docs in your
+  `.graphql` files — no JS project, no gem code, five lines of YAML.
+- **Byte-identical generation is now a stated guarantee**, not just a property:
+  the same schema and queries produce the same files on any machine, in any
+  order (`docs/generated_modules.md`). It was already true and spec-enforced;
+  it was documented nowhere.
+
+**Faraday is no longer auto-selected — `GraphWeaver.new(url)` always builds
+`Transport::HTTP`.** Selection used to be `defined?(::Faraday)`, and faraday
+rides into most bundles transitively (stripe, octokit, ...), so adding an
+unrelated gem silently swapped your transport, its timeouts, and its connection
+behaviour. The accidental default was also the slower one: `Transport::HTTP`
+pools persistent sockets (1 TCP connection for 10 requests) where Faraday's
+default `net_http` adapter reconnects per request (10 for 10) — a full TLS
+handshake each time over HTTPS.
+
+**What you must do:** if you were relying on the auto-pick, ask for Faraday
+explicitly — `GraphWeaver.new(url, transport: :faraday)`. A middleware block
+still implies it (`GraphWeaver.new(url) { |conn| ... }`), since the block is
+Faraday's. Faraday is otherwise unchanged and fully supported. Alongside a url,
+`transport:` now takes `:http` (the default) or `:faraday` rather than a
+built transport object — passing an object there used to raise "pass a url or
+transport:, not both" and now raises naming the two symbols. Alongside a schema
+source it still takes a built transport, and now rejects a Symbol. The client
+logs which transport it built at `info`.
+
+`docs/transports.md` gains the recipe for giving Faraday the connection reuse
+`Transport::HTTP` has by default: the `:net_http_persistent` adapter, the two
+gems it needs, and the version pairing (Faraday 2.x requires
+`faraday-net_http_persistent` **2.x**; 1.2.0 raises `NoMethodError: undefined
+method 'dependency'` at load). graph_weaver depends on neither and never
+selects it for you.
+
+**Generated files are pruned when their query disappears.** Renaming or
+deleting a `.graphql` used to leave its `.rb` behind forever: `load_generated!`
+kept requiring it, its module kept resolving against a query that no longer
+existed, and `verify_generated!` stayed silent — the pruning only covered
+`inputs/*.rb` and `unions.rb`. `generate!` now deletes any generated file the
+plan no longer produces, and `verify_generated!` reports it as stale.
+
+Only files carrying the `# Generated by GraphWeaver — do not edit.` header are
+ever deleted, so a hand-written file in the output directory survives. **What
+you must do:** nothing, unless you were relying on a lingering module — the
+next `generate!` removes it, and CI's `rake graph_weaver:verify` will name it
+first.
+
+**Mutations now generate `…Mutation` modules, not `…Query`.**
+`save_list_entry.graphql` holding a `mutation` produces
+`SaveListEntryMutation` in `save_list_entry_mutation.rb`;
+`SaveListEntryQuery.execute!` read wrong for a write. Queries are unchanged.
+The rule is one rule — the camelized file name plus the operation the file
+defines — and all three naming sites follow it: `generate!`,
+`GraphWeaver.parse(path)`, and `client.load_queries!`. The operation name
+written *inside* the file still names nothing; it goes on the wire as
+`operationName`.
+
+**What you must do:** regenerate (`rake graph_weaver:generate`) and rename the
+call sites of any mutation module — `AdoptQuery` → `AdoptMutation`, including
+nested constants like `AdoptQuery::AdoptionInput`. Regeneration prunes the old
+`*_query.rb` files, and `rake graph_weaver:verify` names anything missed.
+Changing a file's `query` to `mutation` from here on renames its constant the
+same way, which CI now catches rather than letting it drift.
+
+**Generated modules get their client plumbing from
+`GraphWeaver::QueryModule`.** `client`/`client=` carry no per-query type
+information, so every generated file repeated the same fifteen untyped lines;
+they now live in the gem, beside the input-struct runtime, and a module says
+`extend GraphWeaver::QueryModule` instead. `execute`, `execute!`,
+`from_response` and `from_response!` stay generated — their sigs are your
+query's types. A baked `client:` constant is emitted as `DEFAULT_CLIENT`,
+still resolved on first use so a module can load before the initializer that
+builds its client, and resolution is unchanged: per call → per module → baked
+constant → `GraphWeaver.client`.
+
+**What you must do:** regenerate (`rake graph_weaver:generate`). The files
+change; nothing about how you call them does.
+Error-message and console ergonomics from the same review:
+- **Validation errors name the query file and render one per line**, compiler
+  style — `invalid query in app/graphql/queries/person.graphql:` followed by an
+  indented `4:5  Field 'nmae' doesn't exist on type 'Person'` per error. They
+  arrived as one joined line with no file at all, because `generate!` had the
+  path in hand and never passed it to codegen, so thirty query files left you
+  hunting for a bare `4:5`. `ValidationError#errors` and `#to_h` keep the shape
+  `rake graph_weaver:queries:check` reads; only the message text changed, and
+  **it is multi-line now** — update anything matching on it.
+- **`register_enum("Species", PetKind, {"DOG" => :dog})` says the value map is a
+  keyword**, and shows the call with `map:` in it. Guessing the map as a third
+  positional argument used to get Ruby's `wrong number of arguments (given 3,
+  expected 2)`, which never mentions `map:`.
+- **`load_queries!` logs when it replaces an already-loaded module**, at
+  `:info`, before swapping the constant: `replacing PersonQuery — objects built
+  from the previous module stay instances of it`. Reloading is unchanged and
+  still what the method is for; it just isn't silent about the structs it
+  orphans, which is how a console session ends up with an `is_a?` that fails
+  for no visible reason.
+**Rails install generator.**
+`rails g graph_weaver:install https://api.example.com/graphql` writes
+`config/initializers/graph_weaver.rb`, the `app/graphql/queries` and
+`app/graphql/generated` directories, `graphql.config.yml` (schema autocomplete
+and validation for `.graphql` files in VS Code / RubyMine) and the schema dump
+— replacing the console step the getting-started guide used to open with.
+`--auth` names the ENV var holding the token (default `GRAPHWEAVER_AUTH`),
+`--no-schema` skips the introspection. Re-running prompts on conflict like any
+Rails generator.
+
+**`rake graph_weaver:schema:refresh` can now create the first dump.** It read
+its url from an existing dump's provenance stamp, so it couldn't bootstrap one
+— pass `URL=https://api.example.com/graphql` and it will, and both the
+no-dump and no-provenance messages now name that fix. The same logic is
+`GraphWeaver::SchemaLoader.refresh!(url:, auth:)`, which is what the generator
+calls.
+
+**Pointing a client at a url that isn't a GraphQL endpoint now says so.** A
+REST base url, a GraphiQL page or a proxy that ate the path answers 200 with
+well-formed JSON, and `.schema` raised a bare `KeyError`/`NoMethodError` out of
+graphql-ruby — unbranded, no url, and it escaped `rescue GraphWeaver::Error`
+(a 404 on the same path was already branded and clear). Introspection now
+checks for `data.__schema` and raises `GraphWeaver::Error` naming the endpoint
+and the first 200 characters of what came back.
+
+**A subgraph's own `FieldSet` / `Scope` / `Policy` type no longer collides with
+weaver's.** Loading subgraph SDL injects the federation directive definitions
+the file applies but doesn't declare, and the scalars they reference went in
+unnamespaced — so a subgraph that owns a type by one of those names either had
+it shadowed or failed to build, with advice pointing at the wrong file. Those
+three are now `federation__FieldSet` / `federation__Scope` /
+`federation__Policy`. `_Any` / `_Entity` / `_Service` keep their names — those
+are spec-mandated and queryable.
+
+**`rake graph_weaver:queries:check` no longer compares an in-process app's
+schema against itself.** For an app whose schema is its own graphql-ruby class
+there is no server to re-introspect, so the check degraded to re-reading the
+committed dump — reporting phantom errors about the app's own schema, a field
+you just added reading as "doesn't exist". When `GraphWeaver.client` executes
+in-process (a `Client` wrapping a schema class, or the class itself), the check
+now validates against the live class. Network clients are unchanged.
+
+**The two dead-end "records no source url" messages now say what to do.** A
+dump taken from a schema class is rebuilt from code, not re-fetched — both
+`schema:refresh` and `schema:diff` say that instead of naming a `URL=` that
+doesn't exist for you.
+
+**Two rake tasks are renamed so each one names its own subject.** There were
+three checks and two of them were called `verify`, while the one people run
+most — "did schema drift break my queries?" — lived under `schema:` and doesn't
+check the schema. **Update your CI:**
+
+| Was | Now | Asks |
+|---|---|---|
+| `graph_weaver:schema:check` | `graph_weaver:queries:check` | do my checked-in queries still validate? |
+| `graph_weaver:schema:verify` | `graph_weaver:schema:diff` | has the server drifted from the dump? |
+
+`graph_weaver:verify` (is the committed Ruby fresh?) and
+`graph_weaver:schema:refresh` are unchanged. No aliases — the old names are
+gone.
+
+**The instrumentation payload now carries `:status` in-process too.** `InProcess`
+brands a resolver raise as `ServerError(500)` precisely so callers needn't
+branch on which side of the seam a query ran — but the payload had no `:status`
+in-process and no `:schema` over the wire, so a subscriber had to branch
+anyway. A successful in-process execute now sets `:status` to 200; a failure
+still rides the exception the hook already sees.
+
+**`extend_type` and `alias:` moved from `docs/scalars.md` to
+`docs/generated_modules.md`** — they decorate a generated struct, and now sit
+next to what a generated struct looks like. **Update any bookmark to
+`scalars.md#type-helpers-your-logic-on-generated-structs`**; it is
+`generated_modules.md#type-helpers` now. `scalars.md` still owns
+`register_scalar` and `register_enum`.
+
+- **`Testing::Router#trace` accumulates across executes and is reset
+  explicitly** — `router.reset_trace`. It used to clear itself at the top of
+  every `execute`, which made it answer about the *last* query rather than the
+  code path: a service object running two queries reported only the second's
+  fetches, and an example that ran nothing read the previous example's, so an
+  assertion could pass on another example's work and fail under `--order rand`.
+  The rspec `graphql: :router` tag resets it per example. **An example that
+  asserts on the trace after more than one `execute` now sees both**, and
+  wants a `reset_trace` in between if it meant only the last one.
+- **The absent-subgraph refusal leads with the half that applies.** It opened
+  with "Rails autoloads, so the class is probably just not loaded yet" — right
+  often enough to lead with, except when eager loading is already on, and then
+  the library can *ask* rather than send you to a setting you already have. It
+  now checks `config.eager_load` / `config.rake_eager_load` and, when either is
+  on, says the subgraph runs elsewhere and puts `=> :fake` first instead of at
+  the end of a 60-word sentence.
+- **A refusal spells a nested `@key`/`@requires` field set the way your schema
+  does** — `"origin { lat lon }"`, not `"origin.lat", "origin.lon"`. The dotted
+  form is this library's parse of it and matches nothing you can grep for.
+- **One `@interfaceObject` no longer disables the whole router.** It refused at
+  construction, for the entire supergraph, so a single directive made
+  `Testing::Router` unusable even for queries that never touch the type — one
+  corpus had to be split into two graphs over it. It is now a per-query refusal
+  (`Unplannable#category` `:interface_object`) keyed on the types the query
+  actually reaches, and `federation:coverage` counts it as one refusal among
+  others rather than aborting. Routing an `@interfaceObject` is still not
+  implemented; this only makes the refusal proportionate.
+  `RoutingTable#unsupported` no longer lists them —
+  `RoutingTable#interface_objects` does, as `{"Media" => ["catalog"]}`.
+- `docs/federation.md`'s refusal table now lists **every** `Unplannable`
+  category, and a spec keeps it that way. Five were missing, `chained_requires`
+  and `conditional_fragment` among them.
+- **`federation:coverage` counts what your suite can *run*, not only what
+  plans.** `5/5 queries plannable locally (100%)` was optimistic in exactly the
+  partly-local shape the docs call the usual migration one: a query resolving
+  in a subgraph another service serves plans fine and a spec still can't run
+  it. The headline now reads `…, 2 servable here`, and the queries reaching
+  past what's loaded are listed with the subgraph each needs. Plan-only is
+  still the design — with no subgraph loaded (the SDL-alone CI run) the second
+  number is dropped and the report says it counted planning only.
+  `Coverage#servable` and `#elsewhere` are the programmatic side, and
+  `Coverage::Result` gained `absent` / `servable?`.
+- **`Testing::Failure.stale_schema` drops its `schema:` / `seed:` sampling.**
+  It picked a random real type/field so a fabricated error string would look
+  plausible — but no assertion can depend on which one it picks, so it was
+  decoration with three kwargs and an RNG behind it. `stale_schema(type:,
+  field:)` names the casualty when the message matters, and the bare call still
+  trips `schema_stale?`. Passing `schema:`/`seed:` now raises `ArgumentError`.
+- **`rake graph_weaver:cassettes:check`** — replays every recording through the
+  generated modules and fails when one no longer casts. A cassette is the only
+  artifact recorded from a foreign server, and nothing else here notices when
+  that server's answers drift out of the shape the structs were generated for:
+  `verify`, `queries:check` and `schema:diff` all ask about the local side. It
+  needs no network, so it belongs beside `verify` in a PR run. A recording no
+  generated module sends is skipped and counted, and checking *none* of them
+  fails, like `federation:diff`. `Testing::Cassette#check` is the programmatic
+  side.
+- **A cast failure no longer prints sorbet-runtime's `Caller:` frame.**
+  `GraphWeaver::TypeError`'s message ended with `Caller:
+  .../sorbet-runtime/.../call_validation.rb:331` — a path into the gem, never
+  into the code with the problem, and the only location the message offered.
+
 ###  v0.4.6  (2026-07-30)
 Bug fixes from a full-library review (all with regression coverage):
 - alias: a nested-object/enum leaf (`meta.sub`) now qualifies its constant