graph_weaver 0.7.0 → 0.7.2

data/CHANGELOG.md

@@ -1,3801 +0,0 @@
-###  v0.7.0  (2026-09-13)
-
-**What you must do.** Every change here is 0.6.1 → 0.7.0, and a typical app
-ticks two or three. [upgrading](docs/upgrading.md#upgrading-from-061) has the
-same list with the greps that find each one.
-
-- **Regenerate** — `rake graph_weaver:generate`. Every generated file moved:
-  reserved props take a trailing underscore, `as_json` is emitted beside
-  `from_h`, a `cast:` of your own gets the library's own guard, each module
-  carries the graph it came from, a `@key` that selects through a list types
-  its kwarg as a list, a block-built type helper is named for its graph and
-  its type, and `execute` makes its request through the
-  gem. 0.6.1's modules keep running, but `rake graph_weaver:verify` is red
-  until you regenerate, and one of them raises `GraphWeaver::Error` naming this
-  the moment anything asks it for `as_json`.
-- **Rename two error classes.** `GraphWeaver::TypeError` → **`CastError`**,
-  `GraphWeaver::ValidationError` → **`QueryValidationError`**, at every rescue
-  site and in any `to_h["error"]` string you match on. No aliases.
-- **Rename the rspec tag `graphql: false` to `graphql: :live`**, and
-  `config.default_mode = nil` to `:live`, which is now the default.
-- **Rename the notification if you hardcoded it**: `"graph_weaver.execute"` →
-  `"execute.graph_weaver"`. Subscribing through `GraphWeaver::EXECUTE_EVENT`
-  needs nothing.
-- **Read `payload[:http_status]`** wherever a subscriber branched on
-  `payload[:status] == 200` or on a 4xx/5xx — `:status` is a Symbol now.
-- **Read `InputError#path.first`** wherever you read `#field` for the
-  *variable* name; `#field` is the input field that held the value now.
-- **Refresh a schema dump introspected through a url carrying a credential**,
-  and rotate the token if that file was ever pushed — earlier versions recorded
-  the url verbatim in the dump's provenance.
-- **Refresh a dump you deliberately keep behind your own schema class**, which
-  `verify` now fails on — or ask about no dump at all with
-  `verify_generated!(schema:)`.
-- **Regenerate `@oneOf` inputs whose dump is `.json`**
-  (`rake graph_weaver:schema:refresh && rake graph_weaver:generate`): the newly
-  emitted `ONE_OF` starts refusing calls that set two fields, which your server
-  was refusing all along.
-- **Move a `config.schema`, `config.router` or `config.context` set in a plain
-  `before` hook** into `GraphWeaver::Testing.configure` or an `around` — all
-  three are refused there now, where they used to silently change nothing.
-- **Move `require "graph_weaver/rspec"` to `spec/rails_helper.rb`** if yours is
-  in `spec/support/` and you never uncommented rspec-rails' `spec/support`
-  glob: the require never ran, so every `graphql: :fake` example has been
-  hitting the real client.
-- **Set `retries: 0`** if you wrapped a gateway in `Retry` and relied on it not
-  actually retrying: a 5xx/429 that arrives with a GraphQL errors body — which
-  is how Apollo Router answers — retries now, where it used to make one
-  attempt.
-- **Update a spec that compares a `Testing::Router` error hash whole.** A
-  subgraph's error carries `extensions: {"service" => "<subgraph>"}` now, as
-  every real transport stamps it.
-- **Drop `SUPERGRAPH=` from any task but `federation:*`**, which refuse it now
-  where they used to ignore it — a `SUPERGRAPH=… rake graph_weaver:queries:check`
-  in CI goes red instead of passing every query against the wrong schema.
-- **Send the value the server expects** wherever a variable was a `File`, `IO`,
-  `Pathname` or plain object: refused at the wire now, where `JSON.generate`
-  used to ship its `#to_s`.
-
-- **BREAKING: two error classes renamed, with no alias.**
-  `GraphWeaver::TypeError` is now **`GraphWeaver::CastError`** — it means the
-  response wouldn't cast into the generated structs, and the old name shadowed
-  a core class it doesn't descend from, so `rescue TypeError` inside the gem
-  read as Ruby's and `rescue GraphWeaver::TypeError` outside it read as a type
-  error in the caller's own code. `GraphWeaver::ValidationError` is now
-  **`GraphWeaver::QueryValidationError`** — it means the *query* failed schema
-  validation at build time, which a Rails reader would not guess from
-  "validation": their input's validation is `InputError`. The old names are
-  **gone**, not deprecated — rescuing one is a `NameError`, which is the loud
-  failure, and a constant alias would carry the confusion forward forever.
-  `GraphWeaver::Error` still catches both, as it always did.
-- **Breaking: `graphql: false` is now `graphql: :live`.** The opt-out is the
-  app's own client, untouched — which is a mode like the other four, so it is
-  spelled like one. `false` is refused, and the refusal names `:live`.
-  `config.default_mode` is the suite-level spelling of the same thing, and it
-  now **defaults to `:live`** rather than to `nil`, which is no longer a value:
-  every example has exactly one mode, an untagged one takes
-  `config.default_mode`, and `graphql: :live` steps a single example back out
-  of a default the suite set. Behavior is unchanged — `:live` leaves
-  `GraphWeaver.client` exactly as it is, and it is still restored after the
-  example — but a helper now contradicts `graphql: :live` the way it
-  contradicts any other tag rather than quietly winning.
-- **Breaking: `GraphWeaver::EXECUTE_EVENT` is now `"execute.graph_weaver"`.**
-  `<event>.<namespace>` is how every notification in this ecosystem is spelled
-  (`sql.active_record`, `execute_multiplex.graphql`), and it is what
-  `LogSubscriber.attach_to` and an APM's namespace routing key on — backwards,
-  the gem could not attach its own log subscriber without a puzzle.
-  **Subscribe through the constant and nothing changes**; a hardcoded
-  `"graph_weaver.execute"` silently stops matching, so grep for it.
-- **Breaking: the payload's `:status` is a Symbol, and the HTTP status moved to
-  `:http_status`.** `:status` is now `:ok`, `:errors` (the response carried
-  GraphQL errors) or `:failed` (it raised) — a 200 carrying errors is not a
-  success, and only a symbol says that on both sides of the seam. In-process
-  `:http_status` is nil, where `:status` used to be a fabricated 200 so one
-  subscriber could read both sides of the seam.
-- **A form can highlight the input field that was wrong, without reading
-  English — and `InputError#field` changed meaning (breaking).** `InputError`
-  now carries `#kind` (one of eight — `KINDS`), `#path` rooted at the variable
-  (`["where", "_and", 0, "_not", "species"]`, list indices included, so
-  `execute(ids: [1, 2, "x"])` reports `["ids", 2]`), `#coordinate`
-  (`"PetFilter.species"`), `#value` and `#details` (`members:`, `type:`,
-  `suggestion:`, `min:`…), so an app translates a stable key instead of parsing
-  a sentence ([i18n](docs/i18n.md)). **`#field` is now `#path`'s last *named*
-  segment** — the input field that actually held the value, which is the one a
-  form highlights, never an index — where it used to be re-branded on the way
-  out with the *variable* name; read `#path.first` for that. Nothing raises, so
-  the change passes unnoticed until the first refusal inside an input object.
-
-  **The structured half is spelled the way the schema is**, whichever side
-  refused: `#path`, `#field` and `#coordinate` are wire names — `["input",
-  "issuedOn"]`, `"externalId"`. It could not honestly be otherwise, since a
-  server can produce no spelling but its own, and a client-side refusal that
-  used the prop made `errors[e.field]` silently miss every server-detected
-  error, which is what a real Rails form did. The **prop** is what you type in
-  Ruby, and `#message` — the developer's line — names it (`external_id:
-  expected an Int`), so a form is `errors.add(e.field.underscore, …)` and
-  nothing else. An **unknown key** names no field, so the path echoes it
-  exactly as you wrote it and `details[:suggestion]` is the prop to type
-  instead. `filter_parameters` still judges by the prop, that list being
-  written in Ruby spelling — `api_key` has to keep matching what `apiKey`
-  holds.
-
-  **`#details[:type]` is the GraphQL type, never a Ruby class.** A String where
-  an input object belongs says `AdoptionInput`, not
-  `GraphQLTypes::AdoptionInput`, and a `register_scalar("Money", BigDecimal)`
-  field says `Money`, not `BigDecimal` — both used to render straight into
-  `"%{field} must be a %{type}."` on somebody's form. The messages still name
-  the Ruby you may pass, which is the developer's half. One gap left: the
-  sorbet fallback for a field no coercer covers still reports its Ruby type
-  (`metadata: expected T::Hash[…]`), which needs the field's GraphQL type
-  threaded through codegen's node tree. The format key is **`:pattern`**, not
-  `:format`, which is one of `I18n::RESERVED_KEYS` and raised
-  `I18n::ReservedInterpolationKey` out of [i18n](docs/i18n.md)'s own recipe the
-  moment an `:invalid_format` error reached it; a spec holds
-  `InputError::DETAILS` disjoint from that list so the next detail key can't
-  reintroduce the collision, and a server stating `extensions.input` sends
-  `"pattern"`.
-
-  `#value` goes through `filter_parameters`, and an unknown key carries no
-  `#value` at all — the key is what was wrong, and a typo'd key is by
-  definition not the filtered one it was meant to be. Both `#value` and
-  `#details` are always JSON-representable, at any depth (a non-finite Float
-  travels as `"NaN"` / `"Infinity"`), so `render json: e.to_h` can't turn a 422
-  into a 500 over exactly the values `Coerce` exists to refuse.
-  `InputError::VALUE_LIMIT` bounds what one can carry: an error is built for
-  whatever a caller sent and whatever a server echoed back, either of which can
-  be megabytes, and every raised one writes a `warn` line as well as landing in
-  `#to_h` — so each String `#value` holds at every depth, the value `#message`
-  quotes, and a sentence a server wrote are cut to 1024 bytes with `…(N more
-  bytes)` in place of the rest. A `@oneOf` input given one explicitly null
-  field is `kind: :missing` on that field rather than being told to "supply
-  exactly one field", which is what it had done, and a list element that isn't
-  what the list holds is a branded refusal naming the element rather than a raw
-  `NoMethodError`.
-
-  **And the other half of the question is answered too**:
-  `Response#input_errors` / `QueryError#input_errors` /
-  `GraphQLError#input_errors` read a **server's** rejection back into the same
-  `InputError` — from the `extensions.input` convention, graphql-ruby's
-  variable-coercion `problems`, a recognized `extensions.code`, or the argument
-  Hasura names in `extensions.path` (`"$.selectionSet.<field>.args.<name>"`,
-  list indices and nested input keys included), so `limit: -5` against anything
-  on that engine — PokeAPI, Nhost — comes back as an `InputError` on `path:
-  ["limit"]`, the field a form highlights. With Hasura the **path is the test,
-  not the code**: `validation-failed` is also what it sends for a query that
-  doesn't parse, and attaching your own `.graphql` file to a form field would
-  be worse than saying nothing. **`#path` is the input path the server stated,
-  or empty** — a GraphQL error's own `path` names a *selection* rather than an
-  input slot, so it is never stood in for one: a server that sends
-  `extensions.input.path` as a dotted String, or with a segment that is neither
-  a field name nor an index, gets `#path` `[]` and `#field` `nil` instead of a
-  plausible-looking field name for a slot the input hasn't got, which a form
-  doing `errors.add(e.field.underscore, …)` would have highlighted. The same
-  goes for a recognized `extensions.code` that names no `argumentName`; the
-  `kind` and the `details` the server did state still stand. A message goes
-  through the same filter, since graphql-ruby quotes the rejected value as a
-  matter of course; `#details` is checked for type as well as key; no
-  `#coordinate` is invented for a problem that states no path of its own; and a
-  server's sentence earns a `kind` only where one is honest (`:not_a_member`
-  with the enum's members, `:unknown` with the input coordinate, `:missing` for
-  a null it won't take), everything else staying `:refused` with the server's
-  own words — one Hasura sentence covers both `limit: -5` and `limit: "lots"`,
-  so `:out_of_range` would be a guess. A rejection that says nothing
-  identifying it as input — a bare `validates:` failure — is left alone rather
-  than guessed at; the convention is one `Validator` away
-  ([errors](docs/errors.md#when-the-server-rejects-the-input)).
-- **A result now has real JSON, and it round-trips.** `result.to_json` was
-  Ruby's `Object#to_json` — the `#inspect` string, quoted
-  (`"\"#<PersonQuery::Result:0x000...>\""`) — with no exception and no
-  warning, so the first production log line or cache write that reached for it
-  silently stored nothing. Under Rails it was worse in a quieter way:
-  ActiveSupport's `Object#as_json` reflects over the ivars, so `render json:
-  result` shipped the *Ruby* prop names, trailing underscores included
-  (`{"when_":"2024-01-15"}` for a field the schema calls `when`). The rule now
-  is one sentence: **a result's JSON is the wire shape** — the response keys,
-  and each leaf back through its scalar registration's `serialize:` — so
-  `Result.from_h(JSON.parse(result.to_json)) == result`. `#as_json` is
-  generated beside `from_h` as its mirror, and `#to_json` goes through it, so
-  `render json:` and a plain `.to_json` agree. `#to_h` is unchanged and still
-  the Ruby view (Symbol prop names, `T::Enum` members, codec-built objects):
-  a Symbol-keyed hash can't be mistaken for a server's response, and a JSON
-  string can, so the JSON is the one that has to be true. The trip is as
-  faithful as each scalar's own `cast:`/`serialize:` pair — a `Time` goes back
-  out with the microseconds its registration writes, and a `cast:` with no
-  `serialize:` has no wire spelling at all, so its value reaches the encoder
-  as it is (the same reason an input can't send one). A `register_enum`
-  `fallback:` member is in no to-wire table — several wire values collapse into
-  it, and it is exactly the member a drifted response casts to — so serializing
-  one falls back to the member's own `#serialize`, which casts back to the
-  fallback; without a `fallback:` the table is total and a miss still raises.
-  The rule's reasoning is in [DECISIONS.md](DECISIONS.md).
-- **A field named after a method every struct answers now generates, with a
-  trailing underscore.** `class` becomes the prop `class_`, `hash` becomes
-  `hash_`, and so on for `display`, `to_json`, `each`, and `supplied` on an
-  input — in results and input types alike. Both sides used to refuse: the
-  result side told you to alias the key in the query, and the input side told
-  you nothing you could act on, because a schema's field name is not yours to
-  rename. `class`, `hash` and `display` are columns somebody has, and a Hasura
-  `bool_exp` has one input field per column, so that refusal turned whole
-  schemas away. One rule, both directions: a prop may not shadow a method its
-  struct answers, so the prop — and only the prop — moves out of the way. The
-  wire is untouched, so the query you wrote, the request that goes out and the
-  response that comes back all keep the schema's spelling; `result.class` is
-  still Ruby's `class`, and `result.class_` is the field. The prop is the
-  field's one Ruby name — `.new`, `.coerce`, a **result's** `#to_h` and pattern
-  matching all use `class_`, while an **input** struct's `#to_h` is the wire
-  hash it would send (`{"class" => …}`) and input structs don't pattern-match
-  at all. An `InputError`'s structured half is the wire's throughout, so a
-  refusal on that field reports `#path` `["class"]` and `#coordinate`
-  `"Tricky.class"`. Generated source notes the rename on the line above the
-  prop (`# wire: class — reserved as a prop name`), which is the one
-  prop-vs-wire difference a reader can't infer. A key you aliased in the query
-  to get past the old refusal still generates from the alias — drop it and
-  regenerate if you want the field's own name back.
-
-  **The reserved names are a list the gem owns**, rather than whatever
-  `T::Struct` answered to in the generating process. Deriving them made
-  generation depend on require order: with ActiveSupport loaded first a result
-  key named `asJson` was refused, loaded second it became a prop that shadowed
-  the real `#as_json`, so `render json: result` serialized the field. The list
-  is what a struct answers — the public instance methods of `T::Struct` and
-  `Object`, the hooks Ruby or Rails call on an object that doesn't define one
-  (`initialize`, `to_ary`, `to_a`, `to_hash`, `to_str`, `to_int`, `to_proc`,
-  `to_json`, `as_json`, `to_param`, `to_query`, `try`, `presence`, `each`,
-  `deconstruct`, `deconstruct_keys`), and the methods the gem's own mixins
-  define. Kernel's *private* methods are deliberately not on it: a struct
-  doesn't answer them, and `format`, `select`, `test`, `open`, `load` and `pp`
-  are ordinary database columns. The rule itself has one public home,
-  `GraphWeaver::Codegen.prop_name`, for the parts of the gem outside generation
-  that have to agree with it.
-- **A federation `@key` on a reserved field generates instead of refusing.**
-  `@key(fields: "class")` was refused with nowhere to send you — a subgraph's
-  `@key` field is not yours to rename — and `@key(fields: "hash")` emitted
-  `def self.slot(hash:)` beside `const :hash_`, so reading `slot.hash_` and
-  writing it back raised a bare `ArgumentError`. A key kwarg now takes the same
-  trailing underscore the prop does (`Representations.room(class_: …)`), and
-  still sends `"class"` on the wire. Regenerate if a `@key` of yours names such
-  a field. ([federation](docs/federation.md))
-- **A `@key` that selects through a list stays a list.** `@key(fields: "id
-  lineItems { sku }")` over a `[LineItem!]!` typed its kwarg as one
-  `T::Hash[…]`: the correct list was refused and a single hash was accepted and
-  sent, which described an entity that doesn't exist. The kwarg is
-  `T::Array[T::Hash[…]]` now, the list stays a list on the wire, and the
-  generated key set spells the hop `"lineItems[]"`. No other `@key` shape
-  changes — **regenerate** if one of yours selects through a list.
-- **A block-built type helper is named for its source, not for what is
-  loaded.** `GraphWeaver.extend_type("Widget") { … }` minted its module by
-  counting whatever `GraphWeaver::TypeHelpers` constants already existed, which
-  made the name a function of how many times *that process* had read the
-  registry: `rake graph_weaver:generate` baked `WidgetV3` while a plain boot
-  only ever creates `WidgetV1`, so `rails server` died on "includes
-  GraphWeaver::TypeHelpers::WidgetV3, but nothing registers it" while `verify`,
-  run moments earlier on the same tree, called it up to date. The module is
-  named for where the block is written and what it extends —
-  `TypeHelpers::Pet` at the top level, `TypeHelpers::Billing::Pet` in `graph
-  :billing` — so two graphs extending one type name each get their own
-  constant, and the same source counts the same way in every process and after
-  a `to_prepare` reload. **Regenerate.** The reasoning is in
-  [DECISIONS.md](DECISIONS.md).
-- **Generation refuses an input type whose fields collide on one Ruby prop.**
-  Two input fields that underscore onto the same name — `nameWithOwner` and
-  `name_with_owner`, or `class` and `class_`, since `class` is renamed out of a
-  method's way — emitted `const :name_with_owner` twice, and the generated file
-  raised `ArgumentError` when it was *required*, from a trace with no schema in
-  it. It now refuses at generation, naming both fields, the type and the prop —
-  and says which variable reaches what (`$outer reaches Inner through inner`),
-  since the colliding type is usually several hops below the declaration you
-  wrote. The escape is to pass the object as a literal with a variable per
-  field, a schema's field name not being yours to rename; where the type is
-  reached through a list there is no such form, and the refusal says plainly
-  that no form of the query generates. The output side has always refused this;
-  the three real schemas swept (GitHub, PokeAPI, countries — 12,684 input
-  fields) contain no such pair.
-- **An input type named `Result`, `QUERY` or `Representations` is refused**,
-  the way an enum by one of those names already was. Those are the constants
-  every generated query module defines, and nothing checked an input struct
-  against them: `input Result` emitted `class Result` twice, the second
-  reopening the first into one struct that answered for both the variable and
-  the response — generated code that looks authoritative and is wrong — while
-  `input QUERY` raised a bare `TypeError: QUERY is not a class` from Ruby,
-  about the document heredoc. The refusal names the type and the three
-  constants. No public schema in a 23-schema sweep declares one (SpaceX has an
-  *object* named `Result`, which is unaffected — a result class is named for
-  the response key, not the type).
-- **`respond_to?` on a generated result struct no longer answers true for a
-  name that doesn't exist.** It said true for any near miss, so the standard
-  duck-typing guard was the thing that broke — `obj.pet if obj.respond_to?(:pet)`
-  raised the very `NoMethodError` the hint exists to explain. `method_missing`
-  still hints; the cost is that `struct.method(:nmae)` now raises Ruby's own
-  bare `NameError` rather than the hinted one.
-- **Generated result structs behave like ordinary Ruby objects**: value `==`
-  (with `eql?` and `hash`, so a result works as a hash key),
-  `deconstruct_keys` for pattern matching, and `#to_h`. All three go the whole
-  way down a nested result. `#to_h` is the Ruby shape, not the wire's —
-  snake_case prop names as Symbol keys, nils kept, enums as their `T::Enum`
-  members — so it is a view, not something to send back to a server. A result
-  key that would collide with one of the new names (`deconstruct_keys`)
-  generates with a trailing underscore, as any other reserved name does.
-- **A response whose shape drifted names the field and what arrived.** A server
-  that sends an object where a list belongs used to raise *"failed to cast
-  response into Q::Result::Person: Parameter 'data': Expected type
-  T::Hash[String, T.untyped], got T::Array[String]"* — the field named nowhere,
-  the struct named being the parent, and the "got" describing pairs `Hash#map`
-  had made on the way in rather than anything the server sent. It reads `pets:
-  expected a list, but the server sent an object` now, and points into the list
-  (`pets.0: expected an object, but the server sent null`) when an element is
-  the problem. A nullable sibling that is legitimately `null` is never the one
-  blamed: the guard that skips it reads the prop's type with its nilable-ness
-  intact, where it used to strip it and so never fired.
-- **`Response#report` no longer calls a method a server's error path names.**
-  The walk that resolves `entity_ids` stepped through the typed data with
-  `respond_to?`, which is true of every `Object` method — so an error path with
-  a segment named `freeze` **froze the caller's result struct** and then
-  reported an id for a field that doesn't exist, `display` printed the struct to
-  stdout, and `tap`/`send`/`method` raised `LocalJumpError`/`ArgumentError` out
-  of error handling. It reads the struct's own props now, so a segment that
-  isn't a field of that struct resolves to nil — and a field whose prop took a
-  trailing underscore (`class` → `class_`) resolves for the first time.
-- **The emitted `QUERY` is the query you wrote**, in two ways it wasn't.
-  Naming an anonymous operation splices the module's name into the operation's
-  own declaration at a position graphql-ruby reports — which is a byte offset
-  measured against character line starts, and a whole-document offset for a
-  token with no newline after it. A comment above a single-line `{ … }`, or any
-  multibyte character before the operation, put the name in the wrong place;
-  the emitted module still generated and `verify` still reported it up to date,
-  and every call failed on the wire. The splice is now measured correctly
-  **and** the spliced document is re-parsed — if it doesn't declare the name,
-  generation refuses and names the file rather than shipping a module that
-  can't run. The heredoc also used to right-strip every line, which silently
-  edits the *value* of a block-string argument — trailing whitespace inside
-  `"""…"""` is significant — so a query carrying one now sends what the
-  `.graphql` file says.
-- **"Select `__typename`" now says why the ones you did select don't count.**
-  Putting `__typename` in every `... on Type` and nowhere else looks like
-  compliance — it is what Linear's published SDK documents do, and it refuses
-  36 of their 250 operations — and the tag really is on the wire; it is just
-  read *after* the dispatch it would decide, and a member the query never named
-  would carry none at all. The refusal says so when that is the shape in front
-  of it, and keeps the short message otherwise. The rule is unchanged, and
-  [generated modules](docs/generated_modules.md#abstract-types) states it too.
-- **Two codegen refusals name what you wrote.** Two result keys that generate
-  one class name now name both of them, the way the sibling prop-collision
-  message already did; and a module named `T` is refused rather than emitting
-  code that shadows Sorbet's `T` in its own body.
-- **A date and a timestamp are refused for each other, both ways.** A date
-  reads back as a `Date` and a timestamp as a `Time`; the same rule now holds
-  for variables on the way out. `DateTime` is a `Date` to Ruby, so it passed
-  straight through the cast and went on the wire as a full timestamp —
-  `"2024-01-15T10:20:30+00:00"` where the schema said `ISO8601Date`, which a
-  lenient server truncated and a strict one refused — while a `Time` for an
-  `ISO8601Date`, and a `Date` for an `ISO8601DateTime`, surfaced Ruby's raw
-  *"no implicit conversion of Time into String"*. Truncating to the date here
-  would be the same guess made silently, so each now raises an `InputError`
-  naming the variable and the class: `$d of On: expected a Date, got a DateTime
-  — pass .to_date if dropping the time of day is what you meant`, and `$t of
-  At: expected a Time, got a Date — a Date has no time of day — pass the Time
-  you mean`. What a timestamp variable *accepts* grew to match — a `DateTime`
-  and the `ActiveSupport::TimeWithZone` from `Time.zone.now` both convert
-  losslessly, and both used to raise.
-- **A scalar you cast yourself gets the library's guard and its verdict.** With
-  a registration like `register_scalar("Date", Date, cast: :iso8601, serialize:
-  :iso8601)`, the emitted guard was a bare `value.is_a?(Date)` pass-through —
-  so a `DateTime` (which *is* a `Date` to Ruby) went by untouched and your own
-  `serialize:` wrote `"2024-01-15T10:20:30+00:00"` into a field the schema says
-  holds a date, the same cross-type trap the built-in `Date` refuses. It is
-  refused here now, with the same words. Anything else wrong used to reach your
-  codec and come back as Ruby's own sentence about an argument you never
-  wrote — `$input of Probe: birthday: no implicit conversion of Integer into
-  String`, filed under `kind: :unparseable`. The verdict is the library's now,
-  whoever wrote the codec, and it splits the way Ruby itself does: a
-  `TypeError` means the *class* was wrong and reads `$input of Probe: birthday:
-  expected a Date, got 5` under `kind: :type_mismatch`, while an
-  `ArgumentError` means the *content* was and keeps the parser's own words
-  (`invalid date`, `kind: :unparseable`) — the difference between "send
-  something else" and "fix the text", which is the half a form needs. The same
-  split applies to any `TypeError` a `cast:` or `serialize:` raises. The guard
-  is emitted into your generated files, so a checked-in one keeps the old
-  `is_a?` until you regenerate.
-- **"has no cast" now says which mistake you made.** Two unrelated
-  misconfigurations reached the same refusal: a registered class none of the
-  three probes (`.parse`, `.load`, `Kernel#Type`) matched, and a `type:` given
-  by *name*, which is never probed at all because there is no class in hand.
-  The advice differs — name a `cast:`, versus pass the class — but the sentence
-  didn't. Each now names its own cause: the class form lists the three probes
-  that found nothing, and the string form says it was registered by name and
-  shows the class form to switch to. The string form's no-probing behavior is
-  unchanged and correct;
-  [scalars](docs/scalars.md#registering-a-class-of-your-own) now says so where
-  the string form is introduced.
-- **A type-string scalar's bad value is named like every other one.**
-  `register_scalar("Vector", "T::Array[Float]")` gives the field no coercer, so
-  only sorbet stands between the value and the struct — and the check that
-  turns sorbet's complaint back into the library's asked `#valid?`, which stops
-  at the outermost type. `[1, 2, 3]` for a `T::Array[Float]` passed it while
-  the struct's setter (which checks recursively) refused, so the refusal came
-  out blaming the list that *held* the struct, with empty `details` and
-  sorbet's wording: *"items: invalid input for LineItemInput: Parameter
-  'vector': Can't set LineItemInput.vector to [1, 2, 3] (instance of Array) -
-  need a T::Array[Float]"*. It now asks the same question the setter does, so
-  it says *"vector: expected T::Array[Float], got [1, 2, 3]"* with
-  `coordinate: "LineItemInput.vector"`, `path: ["input", "items", 0, "vector"]`
-  and `details: {type:}` — the same shape a class-registered scalar's refusal
-  has always had. Lists of lists and nilable fields alike.
-- **`register_scalar` warns when the Ruby type inherits `eql?`.** A result
-  compares its props with `eql?`, so a value object that inherits it compares
-  by identity: two results parsed from the same bytes are unequal, and neither
-  works as a hash key, while the leaf itself compares fine.
-  `alias_method :eql?, :==` plus a matching `hash` is the fix. The warning
-  fired only for a class that defined `==` and forgot `eql?`, though its own
-  comment described the whole hazard — a class overriding *neither* breaks
-  result equality identically and got nothing. One rule now: a registered class
-  that inherits `#eql?` warns. `String`, `Integer`, `Float`, `Date`, `Time`,
-  `DateTime` and `BigDecimal` all define it and stay silent; a `T::Enum` is
-  exempt, its values being singletons; and a class that gets `==` from
-  `Comparable` and stops there is a true positive, not a false one. See
-  [scalars](docs/scalars.md#registering-a-class-of-your-own).
-- **A timestamp keeps its sub-second part on the way out.** `Time#iso8601`
-  takes no precision, so `"2024-01-15T10:20:30.500Z"` read off the wire went
-  back out as `"2024-01-15T10:20:30Z"` — half a second gone from an
-  `updatedAt` concurrency token, or from the `since:` a window is read on.
-  graphql-ruby's own `ISO8601DateTime` writes whole seconds, so a stock Ruby
-  server never showed it; **any JS/Apollo server writes milliseconds on every
-  timestamp**. A `Time` (or `DateTime`) that carries a fraction is now written
-  with microseconds, and one that doesn't sends the bytes it always has.
-- **A `Float` variable must be a finite number.** `Kernel#Float("1e400")` is
-  `Infinity` rather than a raise (so is `(10**400).to_f`), and JSON has no
-  spelling for a non-finite number — the GraphQL spec excludes them from
-  `Float` outright. It used to travel as far as the transport, which blamed
-  the whole request (*"variables are not JSON-serializable"*); the refusal now
-  names the variable and the value. Every door is checked, so an actual
-  `Float::INFINITY` is refused as well as a string that parses to one — and
-  `register_scalar "Ratio", Float` now reads a whole number off the wire
-  exactly as the built-in `Float` does, which it didn't before.
-- **A variable with no JSON form is refused at the wire.** `JSON.generate`
-  renders a value it doesn't know as that value's `#to_s`, so an `Upload!`
-  given a real file went out as `{"file":"#<File:0x00007f…>"}` — 200 back, no
-  error, and a memory address in the server's database. A `File`, an `IO`, a
-  `Pathname` or a plain object is refused before the body is built, naming the
-  variable and what to do instead; a `Date`, `Time`, `BigDecimal` or `Symbol`
-  still travels as its string. File uploads still need your own transport —
-  graph_weaver doesn't implement the GraphQL multipart request spec.
-- **A variable's whole trip onto the wire is branded.** Serialization ran
-  *outside* the coercion's rescue, so anything it raised arrived as a bare
-  `NoMethodError` naming neither the variable nor the operation — now it reads
-  `$budget of Store: …`, the way a coercion failure already did.
-- **`filter_parameters` scrubs a message's value at every depth, as it already
-  did `#value`.** The message side only ever asked whether the *variable's own*
-  name was filtered, so `execute(credentials: { token: "…" })` refused with the
-  secret quoted in the sentence — and in the `warn` line `Error#initialize`
-  writes — while `InputError#value` sitting beside it read `[FILTERED]`. The
-  value a message quotes now goes through the same scrub as `#value`, so a
-  filtered key one level in reads `got {"token" => "[FILTERED]"}`. Messages
-  change only where a filter matches; nothing else moved.
-- **Every transport failure names the endpoint it failed against.**
-  `TransportError` and `ServerError` carry `#url`, say it in the message
-  (`HTTP 502: <html>… — POST https://api.example.com/graphql`) and in `#to_h` —
-  an app talking to two graphs used to get `HTTP 502` and nothing else, so every
-  investigation started with "which one". The url they name is the one the gem
-  is **willing to say**: a url's userinfo and any query parameter
-  `GraphWeaver.filter_parameters` already filters are folded to `[FILTERED]`, by
-  the same list that scrubs the variables line. That applies everywhere a
-  transport says its url — the boot line, the per-request `debug` lines,
-  `Transport#inspect`, and `payload[:url]` on `execute.graph_weaver`, i.e. your
-  APM — so `https://svc:hunter2@api.example.com/graphql?access_token=…` no
-  longer lands in a log file or a third-party trace store. `Transport#url` is
-  unchanged: it is where requests actually go, and `#safe_url` is the sayable
-  one.
-- **A schema dump no longer records the credential that introspected it.** The
-  provenance stamp (`schema:refresh` and `cache:`) wrote the transport's url
-  verbatim, so a url carrying userinfo or an `?access_token=` landed in a file
-  that gets committed. It now records the endpoint bare — userinfo and any
-  query parameter `filter_parameters` filters are dropped, the rest kept — and
-  re-introspection still authenticates from the dump's `auth_env`, which is
-  where the token belonged. The loader's log lines and errors say the url the
-  way every transport failure now does, secrets marked `[FILTERED]`. A dump
-  written by an earlier version from such a url still holds the token: refresh
-  it once, and rotate the token if the file was pushed.
-- **A `multipart/mixed` response is named rather than dumped.** Forcing an
-  incremental-delivery `Accept` used to raise `non-GraphQL response:` followed
-  by the whole multipart payload, which misdiagnoses a body that is perfectly
-  well-formed GraphQL — just more than one document. It says so now: "this
-  response is incremental delivery (@defer/@stream), which this client doesn't
-  read".
-- **A response behind a UTF-8 BOM now parses.** RFC 8259 §8.1 lets a parser
-  ignore a leading BOM and Ruby's doesn't, so a .NET/IIS-fronted endpoint's
-  answer came back as `non-GraphQL response: {"data":…}` — a body that looks
-  perfectly good, broken by three invisible bytes. And **an empty body says so**
-  (`HTTP 204: empty response body`) rather than trailing off after the colon,
-  which read as a truncated message rather than as the answer it was.
-- **Two more net/http failures arrive as `TransportError`.** A garbage status
-  line (`Net::HTTPBadResponse` — a misbehaving proxy, HTTP sent to a port
-  speaking something else, or a keep-alive socket that desynced) and a body
-  that isn't the gzip it claims to be (`Zlib::Error`) used to escape the
-  `GraphWeaver::Error` umbrella entirely, so `rescue GraphWeaver::Error` missed
-  them and `Retry` treated a retriable failure as fatal. Both are now
-  `TransportError` — which retries, on a fresh connection — as is
-  `Net::ProtocolError`. `Transport::Faraday` already classified all three this
-  way; the two shipped transports now agree.
-- **A retry policy that was inert behind a gateway now fires.** `Retry` read
-  only the failures that *raised*, and Apollo Router answers everything it
-  decides itself with a GraphQL errors body — rate limiting is `503` plus
-  `REQUEST_RATE_LIMITED`, its own faults are `500` plus a code — so the body
-  won over the status and `retries: 3` made one attempt. One rule now: a
-  response retries when its status is one a `ServerError` retries on (5xx, 408,
-  429), or when its error codes are named in `retry_codes:`. A `200` is never
-  retried on status, so a router's partial `GATEWAY_TIMEOUT` still needs
-  `retry_codes:` to opt in, and a mutation still gets one attempt unless
-  `retry_mutations: true`. `REQUEST_RATE_LIMITED` joins
-  `GraphQLError::THROTTLE_CODES`, so `#throttled?` answers it too. The
-  reasoning is in [DECISIONS.md](DECISIONS.md).
-- **A retry delay can no longer kill the retry loop.** `base_delay:` and
-  `max_delay:` are refused if negative, where the typo is; a custom `backoff:`
-  returning one is floored at no wait. Either used to reach `Kernel#sleep`,
-  which raises `ArgumentError` — so one mistyped option reported as a bug
-  somewhere else, and the failure being retried was lost behind it.
-- **`Transport::HTTP`'s connection pool is fork-safe.** A socket idle at `fork`
-  time was inherited by every child, and a round trip carries nothing saying
-  which process opened it — so forked workers interleaved requests on one fd and
-  a caller could receive a well-formed GraphQL response to *another process's*
-  query, with no exception anywhere. The trigger is the documented boot path:
-  Puma `preload_app!` (or Sidekiq) plus an initializer that introspects, which
-  leaves exactly one warm socket in the pool. The pool now belongs to the
-  process that built it — on the first request after a fork the inherited
-  sockets are abandoned (not closed: that would take down the fd the parent is
-  still using) and the pool's permits are rebuilt.
-- **`GraphWeaver.new(url, pool_size: N)`** sizes the bundled HTTP transport's
-  connection pool from the url client, where before only `Transport::HTTP.new`
-  took it and an app had to set `RAILS_MAX_THREADS` to reach it. With
-  `transport: :faraday` it is refused rather than dropped — Faraday's adapter
-  owns its connections.
-- **`Transport::Faraday#url` keeps a url's query string.** Faraday moves it
-  into the connection's default params and strips it from `url_prefix`, so
-  `Transport::Faraday.new("https://api.example.com/graphql?apiKey=…").url`
-  reported an endpoint no request goes to — the one the boot log line names,
-  and the one `graphql: :wire` serves a graph's resolvers at. `#url` is now
-  reconstructed from where requests actually go, through Faraday's own encoder
-  — so an Array param reads `a[]=1&a[]=2`, the way the wire carries it, and a
-  Hash param is not a URL-escaped `Hash#inspect`.
-- **A request header can be a callable.** On `Transport::HTTP` a `headers:`
-  value answering `#call` is resolved per request rather than captured when the
-  transport was built, so a rotating credential needs no new transport:
-
-  ```ruby
-  GraphWeaver::Transport::HTTP.new(url, headers: {
-    "Authorization" => -> { "Bearer #{Tokens.fetch}" },
-    "X-Tenant" => -> { Current.tenant&.id },   # nil ⇒ header omitted
-  })
-  ```
-
-  A value (or a call) of `nil` sends no such header. `Transport::Faraday`
-  resolves one per request too, so a rotating credential means the same thing
-  on both bundled transports. **And `auth:` takes a token that rotates** —
-  `auth: -> { Tokens.fetch }` is resolved per request like any other callable
-  header value, where it used to raise and send you to Faraday's middleware.
-- **A non-String header value is sent as its `to_s`** on both transports, rather
-  than escaping as `NoMethodError: undefined method 'strip'` from inside
-  net/http, naming neither graph_weaver nor the header. The documented
-  `"X-Tenant" => -> { Current.tenant&.id }` crashed in any app whose ids are
-  Integers. A callable is still resolved first and `nil` still drops the header.
-- **Both transports name themselves to the graph.** Every request carries
-  `apollographql-client-name` and `apollographql-client-version`, which is what
-  an Apollo Router or GraphOS keys client attribution on — a real router's span
-  showed `client.name: ""` for everything this gem sent. The name is your Rails
-  application's, or `graph_weaver` outside Rails; the version is the gem's.
-  Override either in `headers:`, which is how one app names its several clients
-  apart. `Transport.default_headers` is the whole set; `DEFAULT_HEADERS` stays
-  the fixed half of it.
-- **A prebuilt `Faraday::Connection` now sends graph_weaver's `User-Agent`.**
-  Faraday pre-fills its own on every connection, so the fill-in-the-blanks
-  `||=` never fired and the traffic attributed to `Faraday v…` — defeating the
-  header's whole purpose. A User-Agent you set yourself still wins.
-- **`ServerError#headers` answers any casing.** Transports store response
-  headers downcased, so `e.headers["Retry-After"]` — the spelling the server
-  sent, and the one a caller reaches for — used to return nil. Lookup by name
-  (`#[]`, `#fetch`, `#dig`, `#key?`) now folds the case; iteration, `#keys` and
-  `#to_h` still yield the downcased spelling, so logs are unchanged.
-- **A Rails app now sees its GraphQL calls without configuring anything.** The
-  railtie sets `GraphWeaver.instrumenter` to the `ActiveSupport::Notifications`
-  adapter (an instrumenter the app set is never replaced) and attaches
-  `GraphWeaver::LogSubscriber`, so every execution — over the wire and
-  in-process — is one notification an APM can subscribe to and one line in the
-  log: `GraphWeaver billing/InvoicesQuery (12.3ms) ok`, `… errors [THROTTLED]`,
-  `… failed GraphWeaver::TransportError` (unprefixed when the module names no
-  graph, so a single-schema app's log reads `GraphWeaver PersonQuery …`).
-  **One rule: the summary is info, the wire is debug** — this is the only
-  GraphWeaver line at info, so a production log gets one per operation and
-  nothing that can carry PII, and turning the logger up to debug adds the query
-  and variables *beneath* it rather than repeating it. Measured at ~4.5µs per
-  execution all told (0.13µs of that `ActiveSupport::Notifications` itself with
-  nothing subscribed), against a round trip measured in milliseconds.
-
-  **Both auto-wires are opt-out from an initializer.** `GraphWeaver.logger =
-  nil` and `GraphWeaver.instrumenter = nil` in `config/initializers` win,
-  because the railtie declares them first and `before:
-  :load_config_initializers` — Rails gives an initializer an implicit `after:`
-  of the previous one the railtie declared, which is how the fallback would
-  otherwise land *after* the app's own files and overwrite the nil it had just
-  set. An app that reached for `config.after_initialize { GraphWeaver.logger =
-  nil }` still works and can drop it. ([logging](docs/logging.md))
-- **The instrumentation payload is a documented contract** ([logging](docs/logging.md#the-payload)),
-  the same shape whichever client slot ran the request: `:operation`,
-  `:graph`, `:client`, `:status` and `:duration_ms` always;
-  `:url`/`:http_status` over the wire, `:schema` in-process; `:error` (the
-  exception's class name) and `:code` — the first GraphQL error's code, or a
-  `ServerError`'s status, the one key to group an alert by — when there is
-  one; and `:retries` under a `Retry`, where each attempt is its own event
-  reading 0, 1, 2, so a call that took three goes no longer reads as three
-  unrelated slow requests. The query text and the variables are still
-  deliberately absent, and now pinned by a spec: `filter_parameters` governs
-  the log, which GraphWeaver writes itself, but the payload fans out to
-  subscribers that know none of those rules.
-
-  `:graph` is the Symbol a module was generated under — `nil` for one that
-  names none and for a client called directly — so a multi-graph app groups a
-  dashboard by graph without parsing operation names. It covers **one
-  request**: a generated `execute` labels the request it makes, each one when a
-  federated operation fans out, and never what a *server* does while answering,
-  so an in-process resolver that calls another API produces an event carrying
-  its own graph or none, rather than its caller's. It is read from what codegen
-  baked in, never inferred from the client — a wrong graph on a request is
-  worse than no graph. Bracketing a request this way is why a generated
-  `execute` is now `from_response(dispatch(variables, client:))`:
-  `GraphWeaver::QueryModule` owns the call, reading the module's own
-  `QUERY`/`OPERATION_NAME`, so nothing about it lands in every generated file.
-  Behavior, sigs and the `Response` envelope are identical.
-- **A bare graphql-ruby schema class in a client slot is instrumented like
-  every other client.** `GraphWeaver.client = MyApp::Schema` and
-  `execute!(client: MyApp::Schema)` ran with no seam at all — no APM event, no
-  log line, not even at debug — while `GraphWeaver.new(MyApp::Schema)` around
-  the same class had both. So the in-process half of an app was invisible on
-  the dashboard, and turning the logger up showed it as a graph that never ran.
-  A schema class is now put through the same `InProcess` wrapper
-  `GraphWeaver.new(Schema)` builds, wherever a client is read — a graph's
-  `client "Billing::Schema"` included. ([logging](docs/logging.md))
-- **An in-process client names an anonymous schema `"anonymous"`.** The
-  instrumentation payload's `:schema` was the schema's `#to_s`, which for one
-  built from SDL is its object address — a new value every boot, so an APM
-  grouping by it got a series per process rather than one per schema. A schema
-  class is still named by its constant, in the payload, the debug log and
-  `#inspect`. ([logging](docs/logging.md#the-payload))
-- **Turning on debug logging no longer changes what happens.** The debug line
-  rendered the variables as JSON itself, *before* the guarded encode — so a
-  value with no JSON form (`NaN`, binary) raised a raw `JSON::GeneratorError`
-  past `rescue GraphWeaver::Error` whenever a logger was listening at debug,
-  and in-process it turned a query that ran into a `ServerError`. The line now
-  says `<unloggable: JSON::GeneratorError>` and the request carries on to the
-  same outcome it has with no logger set.
-- **A non-federated app no longer logs a phantom "no routing table here"
-  warning.** `GraphWeaver::Error` writes a warn line as it is *constructed*,
-  and "is this source a composed supergraph?" was asked by calling
-  `SchemaLoader.routing_table` and rescuing its refusal — so every app whose
-  schema is an ordinary one warned, once per process, about a routing table it
-  had never asked for. The question has a predicate now,
-  `SchemaLoader.routing_table?`, and nothing builds an error to answer "no".
-- **An app can have more than one schema.** `GraphWeaver.graph` declares one.
-  Everything a graph knows is said inside its block, in call style — six
-  settings and the three registrations you already write at the top level:
-
-  ```ruby
-  GraphWeaver.graph :billing do
-    schema    -> { Billing::Schema }
-    queries   "app/graphql/billing/queries"
-    output    "app/graphql/billing/generated"
-    client    "Billing::Schema"
-    namespace "Billing"
-    register_scalar "Money", BigDecimal
-  end
-  ```
-
-  `schema "x"` sets and a bare `schema` reads back; there is no `schema = "x"`
-  form, since the block is `instance_eval`'d and that would be a local variable
-  that silently does nothing — graphql-ruby's `field :name` convention. Anything
-  else the block calls is refused, naming the nine it takes, as is a graph name
-  that isn't a Symbol or a String. `client`, `namespace` and `types_module` each
-  take the constant or its name, since generated source spells it either way; a
-  setting a graph doesn't say falls back to the top-level one.
-
-  `generate!`, `verify_generated!`, `check_queries`, `load_generated!`,
-  `reload_generated!`, the rake tasks and watch mode all walk every graph, so
-  one `rake graph_weaver:generate` does the app and one `rake
-  graph_weaver:verify` gates it. `rake graph_weaver:graphs` lists what is
-  configured — settings, registrations, and the client each graph calls
-  (`rake -T` can't: a task description is baked before `:environment`). The
-  hand-rolled recipe this replaces — N `generate!` calls with
-  `reset_registrations!` between them — is gone from
-  [docs/federation.md](docs/federation.md).
-
-  **In Rails, declare graphs in the initializer and name an autoloaded schema
-  class with a lambda** — `schema -> { Billing::Schema }`. Zeitwerk is set up
-  after `config/initializers` run, so a bare constant there raises; the lambda
-  resolves when generation asks, and again after a dev reload has replaced the
-  class object. The block runs where you write it, registrations included, so a
-  registration naming one of your own constants is in the position a top-level
-  one is and has the same answer: declare that graph from a `to_prepare` block,
-  which is safe to re-run (the graph's name is its identity) and whose query
-  directories still reach the development file watcher, so an edit to its
-  `.graphql` regenerates before the next request.
-
-  **Nothing changes for a single-schema app**: the top-level settings *are* the
-  default graph, and top-level registrations still reach every graph, so a
-  `register_scalar` in an initializer can't be dropped by declaring a second
-  schema. `namespace` nests everything a graph generates, including its shared
-  types module (`Billing::GraphQLTypes`); without one, two files that generate
-  the same module refuse as they always have, and the message now names the
-  graphs and the fix.
-- **Generation refuses a directory no declared graph covers.** Declaring a
-  graph replaces the implicit one the top-level settings describe, so an app
-  that declares one beside its existing `app/graphql/queries` would otherwise be
-  left with a directory nothing reads — `generate` skipping its files, `verify`
-  calling the tree up to date, `queries:check` passing a query containing
-  `nmae`, and the modules generated from it before the graph existed still
-  loading in production. `generate!`, `verify_generated!` and `check_queries`
-  refuse instead, naming the stray files and what each declared graph does
-  cover — and spelling the missing graph out in those paths, since "under
-  directories no declared graph covers" describes the reader's own settings
-  back at them. It says why that graph takes no `schema` or `namespace`: it
-  keeps reading the schema `schema_path` names, and every constant keeps its
-  name. The fix is to name the directory in a graph (`queries`/`output`),
-  declare a graph for it, or delete it; an app that declared no graph is
-  unaffected, its settings *being* its graph.
-  [getting started](docs/getting_started.md#more-than-one-schema) says it too.
-- **Every test mode decides what to run against per graph, and the helpers say
-  which graph they mean.** With more than one schema the honest answer varies
-  per module: `graphql: :fake` for a billing module fabricates billing's shapes
-  with billing's own scalar registrations, where it used to refuse to pick a
-  schema for the suite. `graphql_fake`, `graphql_in_process` and
-  `graphql_router` are the stand-in for the modules of **one** graph, and
-  **`graph:` names it** — `graphql_fake(graph: :poke, "pokemon_v2_pokemon.name"
-  => "pikachu")`, `graphql_in_process(graph: :catalog)`, `graphql_router(graph:
-  :storefront, fake: …)`. The only way to say which used to be `schema:`,
-  matched by the identity of the object the graph's `schema` setting holds,
-  which only a graph running a live class in-process has: an app that is a pure
-  client of two remote APIs has none, since `SchemaLoader` builds a fresh
-  anonymous class per load, so the client, the declared dump path and the
-  graph's own name were all refused with `names none of this app's graphs`.
-  `graph:` takes the handle a graph has everywhere else, printed by `rake
-  graph_weaver:graphs` and baked into every module's `GRAPH`. `schema:` still
-  serves the single-graph override it always did, every refusal now leads with
-  `graph:`, and `graphql_router` — which had no way at all to say whose `fake:`
-  it was holding, and so could only refuse — gains one. They still refuse,
-  naming your graphs, when there is none they could reach.
-
-  **A helper sets the stand-in for the graph it names; the tag sets the mode
-  for every graph no helper named.** `graphql_router(graph: :store)` followed
-  by `graphql_fake(graph: :countries)` used to collapse to whichever was named
-  last — a helper reinstalled the example's one mode, which cleared the
-  per-graph stand-in table, so the first helper's graph was silently re-derived
-  under the second's mode: the plain graph raised `:router` plans across a
-  supergraph, or the federated one answered with fabricated data. So `graphql:
-  :router` plus `graphql_fake(graph: :countries)` reads as what it means, and
-  is no longer refused as contradicting the tag — a helper naming one graph of
-  several isn't speaking for the example. A helper that *does* speak for the
-  whole example (one graph, or no `graph:`/schema to narrow it) still can't
-  contradict its tag.
-
-  `:router` asks each graph where its own supergraph is: the one that graph
-  names, else `config.router[:supergraph]`, else the committed dump when it
-  carries `@join__*`. So an app that had already said where its supergraph is
-  doesn't repeat it in `config.router`, and a module is never planned against
-  **another graph's** — which used to fail blaming a stale dump ("schema may
-  have changed since generation"). A graph in no supergraph is refused by name
-  and pointed at `graphql: :in_process`; two graphs naming one supergraph share
-  one router, parsed once.
-
-  Generated modules carry a private `GRAPH` naming the graph they were generated
-  from, so **regenerate** — a multi-graph app whose modules predate this says so
-  and refuses rather than guessing. `FakeClient.new` takes `registry:` for a
-  caller that holds the graph, since a graph whose `schema` is a file can't be
-  matched back off the schema object. (The per-graph registry behind all of
-  this, `Codegen::Registry`, is internal, like the rest of codegen's IR.)
-- **`graphql: :wire` runs a spec against your own transport.** The other tags
-  sit *in* the client slot, so the transport an app ships — APM tracing, a
-  caller tag, mTLS — never ran in a spec. `:wire` leaves `GraphWeaver.client`
-  where it is and serves your resolvers at the endpoint it posts to: the request
-  is serialized, posted through your middleware, and deserialized by `from_h`
-  over the server's own bytes. What sits behind each endpoint is what that
-  graph *is* — decided **per graph**, in descending faithfulness: its router
-  when it is in a composed supergraph, its live schema class when it has one,
-  else **a fake of its schema**. So the commonest shape there is, and the one
-  the README's Countries and GitHub examples are — a pure client of someone
-  else's API, with a committed dump and no resolvers to run — needs no
-  hand-written `GraphQL::Schema` shaped like your own query. One endpoint is
-  served per graph: the client that graph bakes into its modules with
-  `client:`, or `GraphWeaver.client` for a graph that bakes none — so an app
-  whose graphs all bake one needs no app default at all. A graph whose baked
-  client posts nowhere is refused by name rather than its requests leaving the
-  suite, and a graph with no schema at all is refused in `:wire`'s own voice,
-  naming the three places one can come from. The one candidate the other tags
-  fall back to and this one can't is `GraphWeaver.client`'s own schema —
-  reading it introspects the very endpoint `:wire` has stubbed.
-
-  **The pick is said out loud**, because it was invisible from inside the
-  example: an app whose client is a url transport and whose `Shop::Schema` no
-  one named got a fake, so its suite went green against fabricated data with
-  nothing said. One line per endpoint goes to `GraphWeaver.logger` (a Rails app
-  already has one) — `:wire serving Shop::Schema (in-process) at https://…` at
-  `info`, and at `warn`, naming the class and `config.schema`, when a fake stood
-  in while this process has a `GraphQL::Schema` class nothing pointed at. A
-  warning rather than a refusal, because a loaded class isn't proof you meant it
-  at *this* endpoint (a federated suite loads every subgraph's) and a fake
-  behind the wire is a thing to want: name the class for the suite, and call
-  `graphql_fake` in the examples that want fabricated data. Nothing else is
-  logged from a `:wire` example any more — the predicates deciding what to serve
-  raised-and-rescued to answer "no", and every `GraphWeaver::Error` writes a
-  `warn` line as it is built, so each example used to log two refusals that
-  never happened.
-
-  **A `graphql_*` helper says what goes behind the wire.** Under the other tags
-  a helper takes the client slot; under `:wire` it is served instead — the slot
-  has to keep your own client for the transport to run at all — so
-  `graphql_fake("Reader.orders" => [{ "status" => "PAID" }, {}])` pins one
-  `:wire` example's data exactly as it pins a `:fake` one's, and
-  `graphql_router(fake: …)` says per example what `config.router = { fake: … }`
-  says for the suite. A `:wire` example over a fake proves your transport — the
-  request your middleware wrote, the headers it sent, `from_h` reading real
-  JSON off a socket — but not that your `cast:` agrees with the real server,
-  since the fabricated bytes are written to match your own scalar
-  registrations.
-
-  It needs [webmock](https://github.com/bblimke/webmock) **enabled** — `require
-  "webmock/rspec"` in the spec helper — which hooks Net::HTTP, Faraday and
-  HTTPX, so every bundled transport runs unchanged. Having it in the Gemfile is
-  not enough: `Bundler.require` makes it *loaded* without installing the
-  adapters, so `:wire` checks before serving and names the line to add rather
-  than letting the first request leave the suite for the real endpoint. It
-  needs **rack** too — webmock's `to_rack` builds the Rack env with it and
-  doesn't depend on it — and the refusal names both in one sentence rather than
-  letting you find them one `bundle install` at a time.
-  `GraphWeaver::Testing::Endpoint` is the ordinary Rack app behind it, mountable
-  anywhere for anyone who'd rather have a real socket. See
-  [testing](docs/testing.md#over-the-wire--graphql-wire), which also covers
-  [making the served endpoint fail](docs/testing.md#making-the-served-endpoint-fail):
-  `:wire` adds one stub per endpoint and webmock answers with the last one
-  declared, so a `stub_request(…).to_return(status: 503)` in the example is a
-  **served** failure — your transport reads the status and `Retry-After` off a
-  real response and spends its real retry budget, which a `Failure` client
-  (which raises above the wire) can't reach.
-- **A `context:` can be a proc**, called per request with the headers as sent —
-  the identity seam nothing above the wire could reach:
-
-  ```ruby
-  config.context = ->(headers) { { current_user: User.find_by(token: headers["Authorization"]) } }
-  ```
-
-  A hash still works, and is still the baseline `graphql_context` merges onto.
-- **`config.context`, `config.schema` and `config.router` are refused once
-  they're too late**, under one rule: **configure at load, or in an `around` —
-  never in a plain `before`.** The tag builds (and under `:wire` serves) an
-  example's clients in a `before` hook of its own, which rspec runs ahead of any
-  group `before`, so a set there changed nothing and the example passed against
-  whatever the tag had already picked — a `config.context` that silently never
-  reached a resolver, a `config.schema` the fake never saw. The refusal fires
-  exactly when the clients are already built and names the `around` and the
-  per-example helper (`graphql_context`, `graphql_fake(schema:)`,
-  `graphql_router(fake:)`). Move any such `before` to an `around`, or to
-  `Testing.configure` in the spec helper.
-- **The testing fakes refuse rather than silently do nothing.**
-  `fail_at: "pets.0.name"` matched nothing at all — indices were stripped
-  before comparing — so a spec named a list element, injected no failure, and
-  passed. An index is a path segment like any other now: state the ones you
-  mean and the rest match any position, so the plain `"pets.name"` still fails
-  the first element the walk reaches; a path that starts with an index, or
-  isn't a String, is refused. `Failure.graphql("boom", extensions: {…})` put
-  the extensions on the **response**, so the error carried none, and `code:`
-  was a bare "unknown keyword" — the keywords beside a message now shape that
-  error (`code:`, `extensions:`, `path:`, `locations:`), the hash form still
-  holds several, and anything else is refused by name. The response's own
-  `extensions:` went with them; `FakeClient` is where a whole response is
-  shaped. And **`Failure.timeout`** joins `.transport`/`.server`: a
-  `TransportError` whose `#cause` is net/http's `Net::ReadTimeout`, so a spec
-  says "it timed out" without naming net/http's classes.
-- **A pin is told from an option by a lookup, not by casing.** The rule was "a
-  dot or a leading capital is a pin", so a lowercase type could not be pinned at
-  all: `graphql_fake("pokemon_v2_pokemon" => …)` against a Hasura API came back
-  as `a fake doesn't take pokemon_v2_pokemon:` and the pin was silently gone.
-  Now a key the fake takes is an option, a key **your schema** knows — a type,
-  enum, scalar, `Type.field` coordinate, or a field name — is a pin, and a key
-  that is neither is refused naming both and guessing across both. A key written
-  in the leading positional hash is only ever a pin, which is the spelling for a
-  schema whose own vocabulary collides with an option name. A keyword that is a
-  near-miss for a pin (`Persn: "Ada"`) now raises `ArgumentError` from the fake
-  rather than `GraphWeaver::Error` from the override check; the same key in the
-  leading hash is unchanged. And a **scalar** pin written as the Ruby object —
-  `overrides: { "Money" => Money.parse("12.00") }` — is serialized the way the
-  registration says, rather than reaching `from_h` as a `Money` and failing
-  there; an object pin's fields already followed that rule. Where the
-  registration can't serialize a value (a `serialize:` Proc builds source), the
-  fake refuses naming the scalar instead of letting the cast fail two layers
-  down.
-- **`list_size:` also takes a Hash, saying how long ONE list is.** Every list
-  the fake reaches read the same setting, so nested unbounded lists multiply:
-  `rows { owner { … } tags }` at `list_size: 1600` fabricates 1600 rows and
-  1600 tags in each of them, and per-row allocations double with every doubling
-  of the number (1,064 → 12,981 objects per row from 100 → 1600). Key the Hash
-  the way pins are keyed — a `"Type.field"` coordinate or a bare field name,
-  with `default:` for the rest — and the named list stays flat (205 objects per
-  row across the same sweep): `{ "Row.tags" => 3, default: 1000 }`. Integer and
-  Range mean exactly what they did; a key the schema doesn't know is refused
-  with a spellcheck, at the fake's door and at `Testing.configure`. Works the
-  same on `config.list_size`, `graphql_fake(list_size:)` and a router's `fake:`.
-- **A test-time schema memo notices the file underneath it changing.**
-  `GraphWeaver::Testing.config.schema` keys its located dump on the resolved
-  path, so `GraphWeaver.schema_path=` and `root=` are no longer invisible to
-  `:fake` — only `Testing.reset!` used to clear it, which made the fabricated
-  shapes order-dependent across spec files. It still loads once while the file
-  stands still.
-- **A `graphql:` tag now reaches a module generated with `client:`.** The baked
-  `DEFAULT_CLIENT` sits above `GraphWeaver.client`, which is the slot a tag
-  swapped, so `it "…", graphql: :fake` ran a bound module against its real
-  endpoint. The mode now stands in for that constant too — a per-call `client:`
-  and `MyQuery.client =` still win, and `:wire` still leaves every client where
-  it is. **If a spec relied on a bound module ignoring the tag, it now runs
-  against the fake.**
-- **`@oneOf` was never enforced on any schema read from an introspection dump.**
-  Codegen emits `ONE_OF` from `one_of?` and `InputStruct#one_of!` is the only
-  thing that refuses two fields being set — but graphql-ruby's introspection
-  query omits `isOneOf` unless asked, and its loader drops the field even when
-  it is present, so every dump this gem has ever written said "not @oneOf" for
-  every input object and the enforcing struct was never generated. Both halves
-  are fixed, and a schema introspected now and one loaded back off the file that
-  writes are the same schema. Schemas built from SDL (`.graphql`/`.gql` dumps,
-  inline SDL, a live class) were always correct. A server too old to define
-  `isOneOf` *refuses* the query rather than answering null — PokeAPI's Hasura
-  does — so introspection asks for it and asks the baseline query again rather
-  than fail: one extra round trip, only where the first answer was going to be
-  an error either way.
-- **`schema:refresh` and `schema:diff` work for a schema you serve yourself.**
-  Both refused unconditionally for a dump built from a graphql-ruby class
-  ("records no source url"), so the documented CI chain — `schema:diff &&
-  queries:check && verify && cassettes:check` — was permanently red for an
-  in-process app, and a runtime `QueryError` on a renamed field advised
-  `schema:refresh`, the one task guaranteed to refuse. One rule now, asked per
-  graph: **the dump is the contract generation reads; `refresh` rewrites it
-  from the graph's source, `diff` says how far that source has drifted from
-  it** — whichever the source is. A url is re-introspected as before; a live
-  schema class fills the same duck-typed slot, so it answers introspection
-  itself and nothing touches a network. Only a graph whose dump IS its source
-  still refuses, because there is nothing behind it to re-read. If you wired up
-  graphql-ruby's `GraphQL::RakeTask` to rebuild the dump for graph_weaver, you
-  can drop it: `schema:refresh` writes the same artifact, in whatever format
-  the dump already is, to the path graph_weaver reads. `schema:diff`'s verdict
-  now names the source it compared against (`… matches Catalog::Schema`,
-  `… matches https://api.example.com/graphql`) rather than "the server".
-  `SchemaLoader.refresh!` takes `schema:` and `path:` for the same reason;
-  `SchemaLoader.endpoint` and `Graph#dump_source` are the two new public names.
-
-  **`schema:refresh` also writes a graph's first dump.** Nothing wrote the
-  second one: the installer is single-graph, `URL=` names one endpoint for an
-  app that has one dump per graph, and `real_world.md`'s `GraphWeaver.new(url,
-  cache: true).schema` recipe writes the conventional `schema_path`. A graph
-  naming a dump that isn't there yet is introspected from the url its own
-  client posts to, and the dump records that url as its source like any other —
-  so two plain remote APIs are: declare both graphs with `schema
-  "app/graphql/poke/schema.json"` and `client "POKE"`, run `schema:refresh`,
-  run `generate`. `schema:diff` stops reading a missing dump as "generates from
-  that url directly", which is what a graph naming a live schema class does,
-  and names the file and the task instead. `Graph#named_dump_path` and
-  `SchemaLoader.dump_path?` are the new public names; `Graph#dump_path` still
-  means "the dump that is there".
-- **`schema:refresh` no longer overwrites a composed supergraph with the API
-  schema behind it.** Introspection returns the merged shape a router serves,
-  with the `@join__*` routing table gone — so `rake graph_weaver:schema:refresh
-  URL=<router>` replaced a 5.8 KB supergraph with 1.6 KB of API schema and
-  exited 0, after which `federation:diff` failed and `schema:diff`/`verify`
-  went green against the wrong artifact. Any write that would trade a
-  supergraph dump for a non-supergraph one is refused, naming `rover supergraph
-  compose`; `schema:refresh` with no `URL=` says the same thing to a federated
-  app instead of suggesting one.
-- **A task that can't honour `SUPERGRAPH=` says so.** The flag reaches the
-  `federation:*` tasks, and `queries:check`, `verify`, `generate` and the rest
-  ignored it in silence — so `SUPERGRAPH=public.graphql rake
-  graph_weaver:queries:check` reported every query valid against a supergraph
-  missing a field they select. They refuse it instead; honouring it would
-  collapse a multi-graph app into one unnamed graph, which for `generate` means
-  pruning the other graphs' generated files. Declare the supergraph on a graph
-  to check against it. The reasoning is in [DECISIONS.md](DECISIONS.md).
-- **`verify` fails when the dump has fallen behind the schema class it was
-  built from.** Its question is "is what's checked in current", and the dump is
-  checked in too — for an app that serves its own schema it is an artifact
-  derived from code in the same repo, and everything downstream reads it, so
-  `generate` and `verify` both called a tree up to date while the live
-  resolvers had already moved. A CI gate that only reads exit codes saw
-  nothing. A dump you deliberately keep behind your own schema is a `verify`
-  failure now — refresh it, or name the schema explicitly
-  (`verify_generated!(schema:)`), which asks about no dump at all. The check
-  costs one in-process introspection per graph and never a network call: a
-  dump that records a url stays `schema:diff`'s subject.
-- **A cassette holds one entry per request key, and the docs now say so.** The
-  key is the query, its variables and the operation name together; re-recording
-  a request replaces its entry and a request the file hasn't seen appends one,
-  so `GRAPHWEAVER_RECORD=1` never leaves two entries for one request however
-  often it runs. Unchanged behavior, newly stated and specced: editing a query
-  changes the key, so the old entry stays behind as a recording nothing sends —
-  what `cassettes:check` counts as "not sent by any query module", and what
-  deleting the cassette and recording afresh clears. **`cassettes:check`'s
-  stale advice names both causes** too: the generated structs move when a
-  *registration* moves, not only when the schema dump does, and re-recording
-  doesn't fix that half — so regenerating is offered for it by name.
-  ([cassettes](docs/cassettes.md))
-- **An `@interfaceObject` no longer breaks the subgraph its interface's *other*
-  implementers live in.** Apollo writes a bare `@join__field` — no `graph:` at
-  all — on a concrete implementer's copy of a field really contributed through
-  `@interfaceObject` elsewhere, and the routing table read that the way it reads
-  no directive at all: "wherever the type lives". So `products` was said to
-  resolve `Bundle.reviews`, which `Products::Schema` never defines — pinning
-  `subgraphs: { "products" => Products::Schema }` raised `ConfigurationError` at
-  `Router.new`, and under auto-detection `products` was reported absent and an
-  unrelated `{ products { name price } }` refused `absent_subgraph`, advice
-  about eager loading and all. The rule is now one sentence: **a field routes to
-  exactly the subgraphs its `@join__field` names**, and only a field with *no*
-  `@join__field` lives wherever its type does. Selecting the implementer's copy
-  directly is refused `no_owner` ("the supergraph places `Bundle.reviews` in no
-  subgraph") instead of being fetched from a subgraph that would not answer it.
-- **A `@requires` field and a plain one crossing into the same subgraph now ride
-  one `_entities` call**, as Apollo's do, instead of two — they are split only
-  when a prefetch didn't answer for some node, which is the one case their node
-  sets differ. A dashboard query drops from 6 fetches to 5.
-- **A subgraph SDL that renames what it imports now loads.**
-  `@link(import: [{name: "@key", as: "@primaryKey"}])` — the `@link` spec's own
-  aliasing — raised an error blaming the file for a directive the file had
-  declared. The `@link` header is read for every spelling it binds and then
-  dropped from the schema, so `link__Import`/`link__Purpose` no longer appear in
-  a schema loaded from subgraph SDL.
-- **Two more queries the local router refuses instead of answering them
-  wrong.** A **`@fromContext` argument** was refused only from the
-  crossing-aware half of the planner, so a query one subgraph answered whole
-  skipped the check — and only a gateway injects a `@fromContext` value, so the
-  resolver ran with the argument unset and the router returned a plausible
-  wrong number. And a **progressive `@override(label:)`** wasn't refused at
-  all: Federation 2.7 leaves both subgraphs resolving the field and lets the
-  gateway split traffic by the label, where the router picked one and answered
-  from it every time, silently and forever (new category
-  `:progressive_override`; drop the label and composition drops the losing
-  copy, which plans normally). Every refusal that must hold for a query however
-  it is planned now runs above the single-subgraph shortcut, which is the one
-  walk every plan passes through — see [DECISIONS.md](DECISIONS.md).
-- **`@defer`/`@stream` are refused by name** (`:incremental_delivery`) rather
-  than by happening to fail validation — the answer would arrive in more than
-  one payload, and the Apollo Router supports `@defer` for real. The scan runs
-  above validation in both places that refuse, so the reason you get is this
-  one and not graphql-ruby's "Directive @defer is not defined":
-  `Testing::Router#execute` used to validate before it planned, and `rake
-  graph_weaver:generate` had no check at all — it refused only while no schema
-  declared the directive, and would have generated a module that dropped the
-  deferred selections against a supergraph that did.
-- **A subgraph error out of `Testing::Router` carries `extensions: {"service"
-  => "<subgraph>"}`.** Every real transport stamps which subgraph failed and a
-  client branches on it, so a test asserting on an unstamped error passed here
-  and broke in front of a gateway. The Apollo Router's spelling; a resolver's
-  own `extensions` are left alone. **Update any spec that compares a router
-  error hash whole** — and note that a production router with
-  `include_subgraph_errors` omitted redacts the stamp along with the message
-  ([testing](docs/testing.md)).
-- **`rake graph_weaver:federation:diff` sees three things it used to miss.**
-  It no longer **calls an absent subgraph stale**: a schema was recognized by
-  the types its subgraph declares, and two subgraphs extending one entity
-  declare the same one — so a `prefs` running in another process was matched to
-  its neighbour `accounts`, every field only `prefs` resolves was reported
-  stale, and the gate failed red advising a recompose that would change
-  nothing. A schema now also has to define something the supergraph attributes
-  to that subgraph **alone**; one that shares everything it declares is "not
-  here", which [docs/federation.md](docs/federation.md) already promised doesn't
-  fail the task. `#skipped` (and the `not checked` section) now names those
-  coordinates rather than the types.
-
-  It **compares a field's type, not just its name**. The check was coordinate
-  presence — `Warehouse.code` going from `String!` to `ID!` under an untouched
-  supergraph reported "matches the schemas here", and CI passed on a
-  composition describing a graph nobody serves. Both types are compared and a
-  disagreement is its own drift kind, **shape**, beside stale and not composed
-  in, with both signatures in the message: `Warehouse.code (inventory): String!
-  in the supergraph, ID! here`. `Drift#to_h` grows a `"shape"` key and `#drift?`
-  counts it, so a suite asserting on either sees the new kind.
-
-  And it **names a subgraph you retired from the composition but left loaded**.
-  Every check there walks the supergraph's subgraph list, so a Ruby schema the
-  composition no longer places sat on the only side nothing looked at —
-  recompose without `reviews`, leave `Reviews::Schema` defining everything it
-  always did, and the report said "matches the schemas here (checked 3 of 3
-  subgraphs)", exit 0. It is named on stderr ("not placed — no subgraph of any
-  supergraph read here is:"), as a **warning rather than drift**: a process that
-  loads a subgraph of a supergraph this run never reads is the same picture, and
-  nothing tells the two apart. `Drift#unplaced` is the list for one supergraph
-  and `Drift#subgraphs` is the names it does have; the task asks every graph in
-  the run, so a multi-graph app's second supergraph places its own.
-
-  The `federation:*` tasks also ask the declared graphs where the supergraph is.
-  `federation:diff`, `:subgraphs` and `:coverage` looked only at the
-  conventional dump, so an app that had written
-  `GraphWeaver.graph(:accounts) { schema "…/supergraph.graphql" }` had to repeat
-  it in `SUPERGRAPH=` — and without the flag got a refusal describing a file it
-  never named. Each task now runs once per declared graph whose schema is a
-  composed supergraph, heading each report with the graph's name, and
-  `:coverage` measures that graph's own `queries` rather than
-  `GraphWeaver.queries_paths`. `SUPERGRAPH=` still overrides for one run, and a
-  single-schema app with a composed dump prints exactly what it did.
-- **Three fixes in `rails g graph_weaver:install`.** It **wires the rspec
-  require where rspec reads it**: the setup told you to put `require
-  "graph_weaver/rspec"` in `spec/support/graph_weaver.rb`, and rspec-rails ships
-  the `spec/support` glob **commented out**, so for anyone who hadn't
-  uncommented it the require never ran and a `graphql: :fake` example silently
-  went to the real client. The line now goes in `spec/rails_helper.rb` (under
-  rspec-rails' own `require "rspec/rails"`), or `spec/spec_helper.rb` if that's
-  all there is, or is printed when the app has neither — idempotent, so a re-run
-  and a line you added by hand both leave it alone. It **no longer wires auth
-  you didn't ask for**: the initializer carried `auth: ENV["GRAPHWEAVER_AUTH"]`
-  on every url install, so a public API's setup read an ENV var nobody had set,
-  while the `--auth` docs said the flag was "omitted entirely for a public API
-  that needs no token" — without `--auth` that line is now written commented,
-  which is both the honest default and how you add a token later. And it
-  **keeps a schema dump you already have**: the dump was the one file it didn't
-  write through `create_file`, so Thor never prompted on it and declining every
-  conflict on a re-run still replaced it — a re-run naming a *different*
-  endpoint silently overwrote the old graph's dump along with the source url it
-  records. An existing dump is left alone and named (with where it was
-  introspected from, when that isn't the source just given); delete it and
-  re-run to re-introspect, or `rake graph_weaver:schema:refresh` to re-fetch in
-  place. All three describe what the *next* install writes — existing
-  initializers are untouched.
-- **`rails g graph_weaver:install` adds each graph's output directory to
-  `AllCops: Exclude:`** when the app already has a `.rubocop.yml`, so plain
-  `rubocop` stops reporting `Style/Documentation`, `Style/ClassAndModuleChildren`
-  and `Metrics/*` on generated files. The block it appends carries
-  `inherit_mode: merge: [Exclude]`, because RuboCop *replaces* an `Exclude`
-  array on merge rather than unioning it — without that line the append would
-  wipe the app's effective excludes, RuboCop's own `vendor`, `node_modules` and
-  `tmp` defaults included, along with anything reaching the file through
-  `inherit_from:`. It never creates the file, and it leaves an `AllCops:` you
-  already have alone — a second one would replace it rather than merge —
-  printing the lines to add instead, as it does for a multi-document
-  `.rubocop.yml`, where rubocop reads only the first document and an appended
-  block would land where nothing reads it.
-- **New: `rake graph_weaver:unused`, the over-fetch the other checks can't see.**
-  `verify` says the Ruby matches the query; this asks whether the query still
-  asks for what the app *uses*. It reads the props each query's generated
-  structs carry, sweeps your `.rb`/`.erb`/`.slim`/`.haml`/`.jbuilder` once for
-  every form a prop could be read by (`.sku`, `sku:`, `:sku`, `"sku"`), and
-  names what nothing reads — by query file, selection, and the coordinate the
-  query spells (`Person.bornOn`, not the prop `born_on`). `.rake` and
-  `.builder` are swept too. Nothing is edited and it exits 0; `STRICT=1` exits
-  1 when anything is unread — `0`, `false`, `no`, `off` and empty are off, so
-  the spelling a CI config uses to turn it off turns it off — and
-  `PATHS=app,lib` narrows the sweep, refusing a path that isn't there rather
-  than sweeping nothing and reporting every selection unread. A repo with no
-  queries is told `no queries in <dir>`, the sentence its sibling `generate`
-  already says, instead of being advised to generate nothing. A line handing a
-  query module straight to `render json:` / `to_h` / `to_json` / `as_json` /
-  `serialize` / `deconstruct_keys` reads every prop at once, so that module is
-  excused and the line is quoted — matching a serializer by name is the softest
-  thing here and a wrong excuse should be visible; the sweep follows the local
-  a module was assigned to, so the ordinary two-line controller (`result =
-  Q.execute!` then `render json: result.person`) is excused as well, and it
-  says which local it followed. A graphql-ruby *type* file is skipped, in the
-  `< Types::BaseObject` spelling graphql-ruby's own generator emits as well as
-  the fully qualified one; a `Resolver` or `Mutation` is not, since a BFF reads
-  the upstream graph exactly there. It matches names as text, which makes it a
-  lint and not a proof — the task's own footer names what it is blind to, and
-  carries the measured rate: on a real app half to two thirds of genuinely
-  unread selections go unreported
-  ([getting started](docs/getting_started.md#the-selections-nothing-reads)).
-- **Three things are refused where they used to go wrong later.** A `client`
-  that isn't a constant is refused at generation: the value is spelled into
-  every generated module, so a `client` given the endpoint url emitted
-  `-> { https://api.example.com/graphql }` — a file that doesn't parse — from a
-  run that reported success, and the message now names the constant to declare
-  instead. A `cast:` or `serialize:` **proc that returns a value** is refused at
-  registration: a proc there builds *source* for the generated file, so
-  `cast: ->(v) { v.to_sym }` interpolated to nothing and every response failed
-  far from the registration, blaming the codec; it is probed once when
-  registered, and a non-String return names the spelling to use. And a router's
-  `fake:` refuses `seed:`, as `graphql_fake` and `graphql_router` already did —
-  rspec's `--seed` drives the fake, and a router is built once for the suite, so
-  a seed there would pin every example to one run.
-  (`GraphWeaver::Testing.config.seed` remains the override for a harness that
-  isn't rspec.)
-- **A generated output nested deeper than a `generated_paths` glob reaches is
-  hidden from Zeitwerk again, and loaded.** `app/graphql/a/b/generated` was read
-  as already covered by the default `app/graphql/*/generated` — `File.fnmatch?`
-  lets `*` cross a `/`, and `Dir.glob`, which expands the same pattern
-  everywhere else, does not. It was then neither ignored nor required:
-  production boot died on a `Zeitwerk::NameError` naming a constant you never
-  wrote, and development simply had the modules missing. Nothing to do — a
-  layout like `app/graphql/subgraphs/billing/generated` now works.
-- **A symlinked generated output is hidden from Zeitwerk, and refused when it
-  is declared too late to hide.** The railtie resolved a path with
-  `File.expand_path`, which doesn't follow symlinks, while Zeitwerk walks real
-  directories — so an `output` that was a symlink, or an absolute one through a
-  symlinked ancestor (the Capistrano `current/` shape), was ignored under a name
-  Zeitwerk never visits and its modules died on `uninitialized constant`. The
-  refusal that exists for a too-late output compared the same unresolved path
-  against real autoload roots, so it stayed silent for exactly that spelling; it
-  now fires, and names the output the way your graph spells it.
-- **A graph declared from `config.to_prepare` whose `output` no loader can be
-  told to skip is refused at boot**, naming the graph and the fixes. Rails sets
-  Zeitwerk up before `to_prepare` runs and Zeitwerk reads its ignore list only
-  then, so such a directory cannot be hidden from autoloading — it used to fail
-  in every environment with a Zeitwerk error that blamed a dropped
-  `extend_type`. The refusal asks Zeitwerk which directories a loader would
-  really walk, so an app that hid the output itself with
-  `Rails.autoloaders.main.ignore(...)` is left alone. An output under
-  `config.autoload_once_paths` is refused at the point that knows, and names the
-  two routes that work — `Rails.autoloaders.once.ignore(...)` from
-  `config/application.rb`, or generating somewhere that is not an autoload-once
-  path — since Rails sets the `once` autoloader up in bootstrap, where nothing
-  an initializer does can reach it.
-- **`config.graph_weaver` refuses a key the railtie doesn't read.** It takes
-  `watch`; `config.graph_weaver.queries_paths = ...` was taken silently and did
-  nothing. The refusal names `GraphWeaver.queries_paths =` as the setting that
-  works, and covers every spelling of that write —
-  `config.graph_weaver[:queries_paths] = ...` and `store` went straight to
-  `Hash#[]=`, which is the silent no-op the refusal exists to prevent.
-- **`load_generated!` tells a `Zeitwerk::NameError` apart from a dropped
-  `extend_type`/`register_enum`.** The old message sent you hunting for a
-  registration that was still there; the new one says Zeitwerk owns the
-  directory and names the fix (`GraphWeaver.generated_paths`, or the
-  conventional `app/graphql/*/generated`).
-- **`GraphWeaver.configure do |config| ... end`** — `GraphWeaver::Testing.configure`
-  existed and the top level didn't. `config` is `GraphWeaver` itself, so the
-  flat `GraphWeaver.client = ...` spelling is the same call and stays valid.
-- **Four smaller fixes.** `GraphWeaver::Transport::Faraday` resolves without a
-  require — the constant is autoloaded, so the `Transport::Faraday.new(url) { |conn| … }`
-  that [docs/transports.md](docs/transports.md) shows works where you'd write
-  it, an initializer, instead of raising `NameError` at boot (still opt-in:
-  naming it is what loads faraday). `rails g graph_weaver:install` writes the
-  current scalar spelling, `register_scalar("Money", BigDecimal)`, rather than a
-  three-keyword registration for a scalar 0.6.1 registers for you. The
-  unregistered-scalar report prints where the task that found it prints: one of
-  `generate`'s and `verify`'s two registry advisories went only to the logger,
-  which in Rails is `log/development.log`, so nobody running the task saw it —
-  `GraphWeaver.untyped_scalars` is the list, beside
-  `GraphWeaver.unmatched_registrations`, and it is grouped by graph when a run
-  covers more than one — merged flat it read as "forgotten everywhere" for a
-  scalar registered for one graph and forgotten for the next, so
-  `GraphWeaver.untyped_scalars_by_graph` is the same fact kept apart. And `rake graph_weaver:cassettes:check`
-  sees a namespaced graph's modules: it looked for top-level constants, so an
-  app whose graphs set `namespace` found "0 generated modules", refused for
-  having checked nothing, and blamed the cassette directory.
-- Internal: `bin/round-trip --hostile` now spoils an **input** leaf as well as
-  a response one — a wrong type, an unparseable string, a value the enum
-  doesn't have, a nil where null is illegal, at any depth including inside
-  lists — and requires an `InputError` whose `#path` names the corrupted slot
-  and whose `#kind` says what was wrong. The 40,000 clean round trips before it
-  were evidence about response decoding and close to none about input errors;
-  run against the GitHub schema it found the missing list index in `#path` on
-  its own. It also reads a renamed prop now: a field whose Ruby name took a
-  trailing underscore used to make the harness compare `class` against
-  `class_` and call every such round trip lossy, which hid whatever else that
-  query would have caught — and it calls `execute` with the kwarg a variable
-  really becomes, since it used `prop_name` and an argument named `hash`
-  (Linear's `Query.comment(hash:)`) went out as `hash_:` for `execute` to
-  refuse. The rename exists so a *prop* can't shadow a method its struct
-  answers; an execute kwarg shadows nothing and keeps the schema's spelling.
-
-  The harness also **reads a scalar off the registry rather than off its name**.
-  Sweeping 23 public schemas turned up two declaring `scalar Time` (GitLab's,
-  universe's) and one declaring `DateTimeOrDuration` (Linear's), and both
-  oracles mis-read them: `Time` is a row in the harness's own legal/illegal
-  tables, keyed there by the *Ruby* type a registration casts to, so an
-  unregistered custom scalar of that name was spoiled as if it had a codec, and
-  generated code was failed for accepting what `T.untyped` pass-through must
-  accept. The lookup asks the Ruby type now, with a built-in's own name allowed
-  to refine it. Separately, `bin/round-trip`'s stand-in registrations spelled
-  out `serialize: :iso8601` for a timestamp, which is `Time#iso8601` and drops
-  the sub-second the harness's wire expectation keeps; they name the class and
-  stop, as docs/scalars.md has always said to. No library behavior changed —
-  both were the harness lying about real schemas — and the registrations moved
-  to `RoundTrip.register_scalars!` so the suite can hold them to it. And
-  `railties` joins the development dependencies, so a spec can boot a real
-  `Rails::Application` and assert the railtie's initializer order rather than
-  reasoning about it — the ordering bug in the logger and instrumenter
-  auto-wires was invisible to a suite that never booted Rails.
-- Docs: [logging](docs/logging.md) gains the payload table, the log line, and
-  two-line adapters for OpenTelemetry (`in_span`) and Datadog
-  (`Datadog::Tracing.trace`) — both run against the real gems. Datadog's
-  Net::HTTP and Faraday contribs already trace the transport; the instrumenter
-  adds the span *above* it, named for the operation, which is the one that
-  means anything when every call is a POST to the same url. It also says what
-  `filter_parameters` does and doesn't reach: what GraphWeaver composes, never
-  a server- or resolver-authored `GraphQLError#message`.
-  [errors](docs/errors.md) now says what a *server's* input rejection carries,
-  and leads with what isn't portable rather than burying it: the section opens
-  with the servers read by name (graphql-ruby, Apollo, Hasura), what marks an
-  error as input on each, and a worked fallback for a server that marks
-  nothing — including the nil-`#field` branch a `:refused` error takes, the
-  deep-underscore a Rails JSON controller owes its params before `execute`, and
-  the Hasura `where:` value that is legal to the comparison type and fails at
-  Postgres as `data-exception`, which is neither code the arm reads. It also
-  says what shape the convention's `path` must be, and that a
-  `GraphQL::Schema::Validator` on a *field* is never told which list element it
-  is validating — graphql-ruby coerces a list with a plain `map` — so a `qty`
-  inside `lines: [LineInput!]!` reports `["input", "qty"]` for every element
-  alike; install the validator on the **list argument** instead and index the
-  coerced Array yourself (the recipe is there, and a spec runs it). And it says
-  plainly that neither side collects every problem: `coerce` raises on the first
-  field that won't convert (unknown keys and absent required fields being the
-  two it does list in full), and graphql-ruby 2.6 aborts variable validation at
-  the first `validates:` failure across the whole tree — so build the form
-  expecting to iterate.
-  New [i18n](docs/i18n.md) page proposes stable keys for input problems;
-  nothing in it ships yet. It spells out which spelling a path is in and how it
-  maps to a form field, the nil branch, and how to render `#path` when the
-  index is the half that says which list row failed.
-  [scalars](docs/scalars.md#registering-a-class-of-your-own) **leads with the
-  money shapes that work internationally**. The worked `Money` example
-  hardcoded `"USD"` in its cast — correct for the wire shape it assumed (a bare
-  decimal), and silently wrong for any other currency, which comes back
-  mislabelled with no error anywhere. That's the schema's shape, not the
-  library's, so the section now orders the shapes by what they carry: an object
-  scalar (`{"amount","currency"}`), one string carrying both, and an object type
-  `Money { amount currency }` — which needs no `register_scalar` at all, just an
-  `extend_type` — with the bare decimal last and marked single-currency-only.
-  Also new there: register what your cast *returns*, not where the factory
-  lives (`register_scalar("URL", URI)` runs fine and fails `srb tc` at every
-  call site, because Sorbet's `URI` module payload has no `include Kernel` —
-  register `URI::Generic`); pass-through means no invented codec, not an
-  optional cast, since a class JSON can't parse into is still refused when a
-  query reads the field; a `JSON`-narrowed coordinate opts that field out of
-  `:fake` fabrication as well as hardening its shape; and which cross-type
-  values are refused — Ruby **objects**, where a timestamp *string* for a `Date`
-  parses and truncates, as graphql-ruby's own `ISO8601Date` does. And what a
-  timestamp cast costs, measured: `Time.parse`, the reader every `DateTime`
-  field already uses, is ~7× `Date.iso8601`, and `cast: :iso8601` is ~3×
-  cheaper than it and stricter.
-  [getting_started](docs/getting_started.md) cuts the first hour down to the
-  single-schema path, with multi-schema as its own section further down, names
-  the measured false-negative rate of `rake graph_weaver:unused` where the task
-  is introduced — a lint you can act on is worth more than one you are invited
-  to trust — gains the runnable CI script it never had, one per topology plus
-  the GitHub Actions job, says that a validator installed by symbol is
-  invisible to Zeitwerk (reference it from the same `to_prepare` block, above
-  the schema), and answers the Sorbet question where the adoption decision is
-  made rather than at the end. Its §5 also names the two `rover` commands that
-  close the federated-CI gap below, and the Actions job grew a `federation:diff`
-  step.
-  [testing](docs/testing.md) gains `fail_at`'s path syntax, an
-  `extensions.input` example, `Testing::Sequence` for ending a paging loop, what
-  `to_timeout` does and doesn't prove (webmock stands in for the socket, so
-  neither it nor a `sleep` in `to_return` can exercise a `read_timeout:` of
-  yours), that a fake-mode pin is keyed by the schema's scalar name rather than
-  the Ruby class, that `:fake` never runs your server's `validates:` or custom
-  validators, and loses the "partial failure" label on a call that fails the
-  whole response. New there: **a production Apollo Router redacts what
-  `Testing::Router` hands you** — with `include_subgraph_errors` omitted, the
-  default, a subgraph error becomes `{"message" => "Subgraph errors redacted",
-  "path" => […]}` with the extensions emptied, so a spec asserting on a
-  subgraph's message or on the `extensions.service` stamp passes here and fails
-  in staging; it says what to assert on instead and gives the `Failure.graphql`
-  that reproduces the redacted shape. Also the nested-list multiplication
-  behind `list_size:`, measured.
-  [federation](docs/federation.md#producing-a-supergraph) gains the step it
-  never had — how to *produce* a supergraph: `federation_sdl` from the
-  `apollo-federation` gem (named in prose for the first time), where other
-  teams' subgraph SDL comes from, and `rover supergraph compose` with its
-  config and its `--elv2-license` flag. It also writes down that
-  [`router.trace`'s fetch count is the local router's plan, not a
-  gateway's](docs/federation.md#the-local-router): the data is faithful, the
-  cost isn't quite — the same dashboard query is 4 fetches through a real
-  `@apollo/gateway`, because a `@requires` prefetch here is its own call even
-  when it goes to the same subgraph as the plain read beside it, so an N+1
-  regression assertion belongs on a bound or on the subgraph set rather than on
-  an exact count. Also newly written down there: a `@join__` directive the
-  routing table doesn't read refuses `Router.new` for the whole graph (an
-  upgrade-timing event for every team sharing the supergraph), a document that
-  fails ordinary GraphQL validation gets an `errors` response rather than an
-  `Unplannable`, and apollo-federation's `orphan_types`-before-`query` ordering
-  trap. It now opens with a signpost saying which of its sections belong to a
-  client team, a subgraph team and the supergraph owner, and gains four more:
-  **in CI**, because no task in the toolbox looks at the schema production is
-  serving — they all compare the app to its own checked-in artifacts, and
-  `schema:diff` can't be pointed at a supergraph — so it names the two `rover`
-  commands that close it; **`@tag` and contract variants**, what codegen says
-  against each (it refuses at the boundary, which is the guarantee), why
-  `federation:diff` can't tell two variants apart, that nothing cross-checks the
-  variant you generated against with the endpoint you call, and that a variant
-  is mechanically just another `GraphWeaver.graph`; **two changes every gate
-  calls clean**, a scalar swapped for one that still serializes as the same JSON
-  kind (`String!` → `Currency!`, `"19.99"` → `"$19.99"`) and an enum value
-  removed where no query names it literally, with `schema:diff`'s `breaking:
-  true` the only signal for either; and that an `@override` migration is
-  finished from the **old** side, since deleting the new owner's copy first
-  hands the field back to the subgraph you were migrating away from and nothing
-  reports it. Also there: `Federation::Drift`'s `subgraphs:` takes a
-  resolver-less schema from `SchemaLoader.load(sdl)`, so a subgraph published as
-  SDL by a team that doesn't write Ruby is fully compared — and detection unions
-  every candidate that fits a subgraph, so diffing a *proposal* has to name it.
-  [generated modules](docs/generated_modules.md#an-input-object-generates-its-whole-closure)
-  states the rule the docs implied and never said — results are generated per
-  selection set, input types by transitive closure, which is why one Hasura
-  `$where` emits a thousand files — and documents the escape hatch that only
-  ever appeared in an error message: write the filter as a query literal with a
-  variable per leaf. It also says how far a result's immutability goes: its
-  props, so the `String` or `Hash` a leaf holds is the one the response carried,
-  as with `Struct` or `Data` — and that caching one wants `Marshal`, not YAML,
-  since a `T::Enum` member is a singleton compared by identity and Psych
-  rehydrates a duplicate, so `pet.species == Species::Dog` comes back false. It
-  also names the one enum misuse nothing catches — `result.tier == "GOLD"` is
-  silently `false`, on a generated `T::Enum` as on any other — and the
-  sorbet-runtime switch that reports it
-  (`T::Configuration.enable_legacy_t_enum_migration_mode` plus a
-  `soft_assert_handler`), which belongs in your boot rather than in generated
-  code because it covers your own enums too. And two costs: `verify_generated!`
-  runs a full `generate!` however little changed, while
-  `T::Configuration.default_checked_level` buys nothing for `from_h`. Its
-  type-helpers section now shows that an `extend_type` mixin *can* carry sigs
-  `srb tc` checks — declare the fields it reads as abstract sigs, which the
-  struct's `const`s satisfy.
-  [upgrading](docs/upgrading.md) opens each version section with a table of
-  which changes apply to you, separates the grep hits that self-heal on
-  regenerate from the ones to rename by hand, and ends on `graph_weaver:verify`.
-  New [alternatives](docs/alternatives.md) compares the field — graphql-client,
-  graphlient, artemis, hand-rolled — including where this gem loses. Also:
-  browsing a live schema from a console
-  ([real world](docs/real_world.md#browsing-the-schema)), the four settings
-  rake-free generation needs to agree on, what `retries:` does and doesn't
-  cover plus `pool_size:` and the pool's fork-safety, and that the request body
-  carries no persisted-query id — so a gateway safelist with `require_id`
-  refuses it, with the `Transport::HTTP` subclass that bolts APQ on today
-  ([transports](docs/transports.md#retries)), that Rails' own default
-  `filter_parameters` includes `:email` so a stock app redacts an ordinary field
-  named `email` the day the gem is added ([logging](docs/logging.md#filtered-variables)),
-  and keying a translation on the exception class where there is no `kind`
-  ([i18n](docs/i18n.md#transport-and-server-failures)). And
-  `spec/doc_samples_spec.rb` parses every fenced Ruby sample in README +
-  `docs/` and resolves every link between them, so a sample that doesn't run
-  can't ship — two that didn't now do (`Codegen.generate(client:)` takes the
-  constant's *name*, and `Federation::Drift` needs `require
-  "graph_weaver/federation"`).
-###  v0.6.1  (2026-09-10)
-- **A stdlib scalar registers with nothing but its class.**
-  `GraphWeaver.register_scalar("Decimal", BigDecimal)` now emits the whole
-  codec: `BigDecimal(...)` reads the wire value, `to_s("F")` writes it back,
-  and the generated file requires `bigdecimal`. The careful spelling people
-  reached for was wrong — `serialize: :to_s` puts `"0.125e2"` on the wire —
-  so the library owns it. Cast inference gained Kernel's conversion functions
-  (`BigDecimal()`, and any `Kernel#Type` your app defines for a type the wire
-  can't already be), and `serialize:` accepts `[:method, *args]` for a
-  serializer that takes arguments. `cast:`/`serialize:`/`requires:` are
-  unchanged, for a class of your own.
-- **Scalar names that are conventions are registered already**: graphql-ruby's
-  `ISO8601Date`, `ISO8601DateTime`, `BigInt` and `JSON`, plus `DateTime` —
-  what GitHub, Shopify and most hand-written schemas call an ISO 8601
-  timestamp. A date deserializes into `Date` and a timestamp into `Time`, so
-  nothing invents a midnight; `BigInt` reads the decimal string graphql-ruby
-  writes as well as a JSON number; `JSON` is registered as `T.untyped` on
-  purpose, which also drops it from the "unregistered custom scalars" report.
-  A schema that means something else by one of these names fails loudly — the
-  cast raises, naming the field — and one `register_scalar` overrides it, as
-  it always could. **Regenerate** if a query of yours reads a scalar with one
-  of those names: its prop was `T.untyped` and now has a type.
-
-###  v0.6.0  (2026-09-09)
-- **One rule for relative path settings: they resolve against
-  `GraphWeaver.root`** — `Rails.root` in a Rails app, the working directory
-  otherwise. There were two: cassettes resolved against `Rails.root` while
-  the schema dump, queries and generated directories resolved against the
-  process's working directory, and the railtie patched three of the four
-  places that mattered. A Rails app started anywhere but its own root — a
-  `bin/rails server` or an `rspec` run from a subdirectory — loaded no
-  generated modules at all. An absolute setting is untouched, and the settings
-  keep returning what you configured, so `graphql.config.yml` stays portable.
-  Set `GraphWeaver.root` to override. The rule runs both ways: a path is
-  resolved against the root on access and reported relative to it on output,
-  so `generate!`'s return value, `changed_files`, `check_queries`' keys, the
-  rake tasks' `wrote`/`pruned` lines and the file an error names all come back
-  in the short form you configured. `cache:` also accepts a `Pathname` now,
-  as `schema:` and `query:` always have.
-- **One spelling for the generated module's name: `name:`.** `GraphWeaver.parse`
-  took `name:` while `Codegen.generate` took `module_name:`. **Breaking:**
-  `module_name:` now raises naming `name:`. A parsed module also names itself
-  in errors — `GraphWeaver.parse::PersonQuery::Result::Person` instead of a
-  hex address — and assigning it to a constant upgrades every nested struct
-  to the real path.
-- **`generate!` leaves a file alone when its content hasn't changed**, so the
-  rake task prints `wrote` only for files it wrote and `N already up to date`
-  for the rest, and a watching dev server reloads only what moved.
-  `GraphWeaver.changed_files` says which. A generated file now says which
-  release wrote it (`# Generated by GraphWeaver 0.6.0 — do not edit.`), so the
-  first `verify` after an upgrade reports the tree as stale. **Regenerate.**
-- **A fake refuses an option it doesn't take**, naming the accepted ones and a
-  did-you-mean, at every door (`FakeClient.new`, `graphql_fake`,
-  `Router.new(fake:)`, `graphql_router(fake:)`) — it was a raw
-  `unknown keyword` from inside the fabricator. A scalar the fake can't
-  fabricate is now reported at its path (`at reader.orders.0.total`) with the
-  coordinate to override (`"Order.total"`).
-- **A supergraph using federation 2.8's `@context`/`@fromContext` is refused
-  per query rather than routed with the argument unset.** `@join__field` was
-  on the routing table's known list, so its `contextArguments:` was read and
-  dropped: `Testing::Router` planned a fetch for the contextual field with the
-  argument empty. Apollo composes such a graph even when the context-setting
-  type and the contextual field sit in different subgraphs, so nothing
-  upstream caught it. The refusal fires only where the router would plan that
-  fetch itself; a subtree one subgraph answers whole still runs. New
-  `Unplannable` category `:context_argument`.
-- **The local router makes one entity fetch where it made two** when an entity
-  has two `@requires` fields crossing into the same subgraph on the same
-  `@key`. Both sent the identical representation; Apollo makes one. Specs
-  asserting on `#trace` for such a query see one fewer entry. A missing `@key`
-  on a representation now names the entity type in `InputError#struct`, as a
-  coercion failure already did.
-- **Three rake and generator polish items.** `rake -T` no longer prints a
-  queries path it can't know — a task description is baked before
-  `:environment`, so it presented the default as your setting; it now names
-  the defaults as defaults. `cassettes:anonymize` prints `no recordings in
-  <dir>` instead of nothing. `rails g graph_weaver:install` scaffolds
-  `app/graphql/fragments/.keep`, the directory its editor config already
-  globbed; the getting-started note names `rails g graphql:install
-  --skip-query-logs` for an app without Active Record.
-- **`filter_parameters` scrubs error messages, not just the debug log.** A
-  rejected value reached the log twice: on the `variables=` line at debug, and
-  in the message every error writes at `warn` — above the gate, as free text.
-  One rule now covers both: a message the library composes about a value you
-  supplied names it only when the key it arrived under isn't filtered. So
-  `$password of Login: [FILTERED]`, while `$count of Compute: expected an Int,
-  got "lots"` is unchanged — the value is usually the whole diagnosis. Applies
-  to execute kwargs, input fields at any depth, federation `@key` fields, and
-  the missing-cassette report. A wrong-typed input field with no coercer now
-  says which field (`cents: expected BigDecimal, got 5`) instead of sorbet's
-  sentence, and the local federation router no longer logs variables
-  unscrubbed.
-- **The public surface is what the docs name, what generated code calls, and
-  the `execute` slot — 421 names, down from about 700.** Everything else moved
-  under `GraphWeaver::Internal`, whose one rule is that nothing in it is API,
-  or went `private`. `spec/public_surface_spec.rb` diffs what's reachable from
-  `GraphWeaver` against a checked-in list, so the next accidental promotion
-  fails CI instead of shipping. **Breaking** only for code reaching past the
-  documented door: the federation query planner and its IR are
-  `Internal::Planner`; the fake-value engine is `Internal::Values`; the
-  selection walk is `Internal::Selection` (so `FakeClient` no longer answers
-  to `each_field` or `gather`); the cassette matching rules are
-  `Internal::RequestKey`; `GraphWeaver.log`/`.instrument`/`.filter_variables`
-  are `Internal::Log` (`logger=`, `instrumenter=`, `filter_parameters=` are
-  unchanged); `Transport.operation_name`/`.mutation?`/`.log_tag` left the
-  class you subclass for `Internal::Wire`. `SchemaDiff::Change`,
-  `Cassette::Check`, `Coverage::Result` and `InputStruct::Field` are `Data`,
-  not `Struct`, so they no longer hand out writers. `Codegen::ScalarType` is
-  private from load rather than from the first `reset_scalars!` — the
-  `private_constant` had landed inside the method body. Generated modules also
-  stop exposing their plumbing: `DEFAULT_CLIENT`, `FIELDS` and `ONE_OF` are
-  emitted as `private_constant`. **Regenerate**; nothing you call changes.
-- **The retry options are flat.** `retries:` is how many attempts follow the
-  first; every other `Retry` option now sits beside it on the client —
-  `GraphWeaver.new(url, retries: 5, backoff: :linear, retry_codes:
-  ["THROTTLED"])`. **Breaking:** `retries:` no longer takes a Hash (`retries:
-  { retries: 5 }` read as a key nested in itself), and three options are
-  spelled out now that they sit next to a count: `on:` is `retry_on:`,
-  `base:`/`max:` are `base_delay:`/`max_delay:` — `retries: 5, max: 30`
-  invited reading `max:` as a second attempt count. The Hash form names its
-  flat replacement, and a retry option passed without `retries:` says so.
-- **A representation's key fields are coerced, like an `execute` kwarg.**
-  `Representations.user(id: params[:id])` typechecked statically and then
-  raised sorbet-runtime's unbranded `TypeError` at runtime. The generated
-  builders now carry `.checked(:never)` and run each key field through the
-  registered scalar's own conversion; a value that converts to nothing raises
-  `GraphWeaver::InputError` naming the representation and the field.
-  **Regenerate.**
-- **The library's internals are private.** Everything not documented and not
-  named by generated code is now `private` / `private_class_method` /
-  `private_constant`: codegen's IR and walk, the schema loader's detection
-  tables, the transport's log patterns, `Retry`'s default predicate, the
-  file-naming helpers. **Breaking:** `GraphWeaver::Selection`'s methods are
-  private in every class that mixes it in, so `Testing::FakeClient` no longer
-  answers to `each_field`, `gather` or `load_operation` — never a supported
-  door. The runtime that emitted source calls into (`cast_data`,
-  `check_envelope!`, `Coerce`, `Hints`, `InputStruct`, `QueryModule`,
-  `Representation`) stays public and says in its comments that it is
-  generated code's, not yours.
-- **A registration another schema owns warns instead of failing generation.**
-  One registry serves a whole graph — federation composes scalars and types
-  by name — but validation ran against the single schema in hand, so the
-  natural multi-subgraph pattern (register once, generate each query against
-  its own subgraph) hard-failed. Generation now fails only on what the schema
-  can *disprove*: a name it declares as something else, or a coordinate whose
-  field it declares as a composite. Everything else warns, naming the schema
-  and suggesting a corrected name. `rake graph_weaver:generate` and `verify`
-  print that list once per run after the files;
-  `GraphWeaver.unmatched_registrations` is the same list for a Rakefile.
-  **Breaking**: a typo'd registration that used to stop generation is now a
-  printed warning. `docs/federation.md` gains "Generating for a federated
-  graph": through the gateway, generate against the supergraph; calling
-  subgraphs directly, one client each with `reset_registrations!` between.
-- **Variables coerce inside `execute` now, and the sig stays as narrow as the
-  schema.** `execute(first: params[:first])` works — the String becomes an
-  Integer, an ISO-8601 string a `Date`, a model's Integer primary key an `ID` —
-  while `execute(first: "20")` written literally in a typed file is still an
-  `srb tc` error. The only way to accept loose input used to be `coerce: true`
-  / `GraphWeaver.auto_coerce`, which bought it by *widening* the emitted kwarg
-  and so switched off the static check at every call site. The generated sigs
-  are now `.checked(:never)` so an untyped value reaches the body; coercion is
-  the check that replaces sorbet-runtime's, and it refuses more than sorbet
-  did. Bad input raises `GraphWeaver::InputError` naming the variable, the
-  operation and the value — the same 422 rescue point as an input-object
-  field. **Breaking:** `GraphWeaver.auto_coerce` and `register_scalar(coerce:)`
-  are gone; a scalar that had `coerce: true` keeps its behaviour but its kwarg
-  narrows, so a call site passing a literal String is now an `srb tc` error.
-  `cast:` is what a loose value converts through. **Regenerate.**
-- **Numeric strings are read as a wire format, not as Ruby source.** `"010"`
-  is ten, not eight, and `"0x1f"` and `"1_0"` are refused, in variables and
-  responses alike — `Kernel#Integer` accepted all three, which made a
-  zero-padded form field silently mean something else. An `Int` refuses a
-  `Float` it can't hold losslessly (`2.5`), and a `Boolean` refuses a String:
-  Ruby has no `Kernel#Boolean`, so every rule for `"0"`/`"off"` is a
-  convention the library declines to pick — convert at the call site.
-- **A faked subgraph takes the options every other fake takes, and
-  `graphql_router` says them per example.** `subgraphs: { "reviews" => :fake }`
-  built its fake with nothing, so `overrides:`, `list_size:` and `null_chance:`
-  had nowhere to go. `fake:` carries them, on `Router.new`, on
-  `Testing.config.router`, and per example through `graphql_router(fake:)`,
-  which mirrors `graphql_fake`. One `fake:` covers every faked subgraph —
-  coordinate-keyed overrides already say which type they mean. A `fail_at:`
-  inside an `_entities` fetch used to null the field and report no error; it
-  now comes back as an error on the caller's path.
-- **A subgraph two loaded schema classes fit is refused by the query that
-  reaches it, not by `Router.new`.** In an app where several loaded schemas
-  each satisfy a foundational subgraph, building a router raised for
-  subgraphs the query under test never touched — and only when eager loading
-  happened to be on. The router now builds, every query that avoids the
-  subgraph runs, and one that reaches it raises naming the candidates, saying
-  they came from loaded schema classes, and showing the `subgraphs:` form that
-  pins one. A class named explicitly still fails at construction.
-  `router.ambiguous` lists them. `Testing::Subgraphs.resolve` now returns a
-  `Resolution` (`#served`, `#ambiguous`).
-- **A `.graphql` edit reaches the next request in development.** The query
-  directories and the schema dump join Rails' own reloaders, and the
-  `to_prepare` that loads the generated modules now regenerates first — after
-  your registrations, so an `extend_type` in a `to_prepare` is in place before
-  codegen reads it. A query that doesn't compile is logged at `error` with its
-  file and position while the modules already loaded keep serving. Development
-  only, while the server is running; `config.graph_weaver.watch = false` turns
-  it off, and `rake graph_weaver:verify` still gates CI on the committed files.
-  `GraphWeaver.reload_generated!` does the same by hand after regenerating in
-  another terminal, and generated files are now written to a temp file and
-  renamed, so a `rake graph_weaver:generate` beside a watching dev server can't
-  hand the running app a prefix that no longer parses.
-- **A variable passed `nil` now sends `null`; one left out is still left
-  out.** GraphQL tells an absent variable from an explicit null — `bio: null`
-  clears a bio, omitting it does nothing — and a Ruby kwarg with a nil default
-  cannot, so both spellings omitted the key and no generated mutation could
-  clear a field. An optional nullable variable now records whether the keyword
-  was supplied. Input objects get the same distinction where a Hash can express
-  it: `coerce({nickname: nil})` sends null, `coerce({})` omits; a struct built
-  with `.new` can't tell, so nil there still means omit. A non-null variable
-  can't carry null, so nil there also still omits and its schema default
-  applies. **Breaking**: `bio: params[:bio]` with a missing param now sends
-  `null` where it used to omit — pass the keyword only when you mean to.
-  **Regenerate.**
-- **A response that won't cast says which field, and whose bug it is.** A
-  leaf's cast raises about the value alone — "invalid date" on a struct holding
-  four dates located nothing — so each casting leaf now carries its response
-  key. An `ID` the server sent unquoted is out of spec but read like a
-  graph_weaver bug in sorbet's words; the message now says which it is and how
-  to take it anyway. An enum value the generated enum doesn't hold now names
-  the legal values and says the likely cause is drift, matching the input
-  side. **Regenerate.**
-- **`register_scalar` with a type the wire can't build is refused at
-  generation.** `register_scalar("Money", BigDecimal)` produced a `BigDecimal`
-  prop and no cast, so every response failed its prop check at runtime, far
-  from the initializer that caused it. Generation now refuses it where a query
-  reads that scalar back, naming the field and how to give it a `cast:`.
-  `docs/scalars.md` now tabulates what the wire carries in both directions.
-- **A fake takes pins, keyed by a scalar type, an object type, or a field.**
-  A pin says what the fake uses instead of inventing a value: a wire value,
-  an object it reads the selected fields off — a FactoryBot build, a model, a
-  `Struct`; a field the object doesn't answer is still fabricated, and a Ruby
-  value goes on the wire the way its scalar registration serializes it — or a
-  proc handed the seeded `Random`. Pins lead and options follow, in one call;
-  suite-wide, the same hash is `Testing.config.overrides`, and a router's
-  `fake:` takes it for the subgraphs it fakes.
-
-      graphql_fake("Money" => "12.00", "Person" => build(:person), "Order.total" => "999.00")
-
-  A scalar registered as your own class — `register_scalar("Money", Money,
-  cast: :parse)` — told codegen how to read the wire value but left the
-  testing harness guessing what to write, so every fake response touching it
-  died inside `from_h` blaming `Money.parse` for a `"Money-1"` placeholder.
-  The type pin is the answer, from every door including cassette
-  anonymization; without one, fabrication refuses, naming the scalar, the
-  field, and the pin to add. Scalars registered as `Time`, `Date`, `Integer`,
-  `Float`, `String` or `T::Boolean` need nothing. Fakes also now honor a
-  per-field `register_scalar("User.birthday", Date)`, matching codegen's
-  resolution. `graphql_fake` and `graphql_router(fake:)` refuse a per-example
-  `seed:` — `rspec --seed` is the mechanism, and `config.seed` the suite-wide
-  one for a harness that isn't rspec.
-- **`Testing.config.null_chance` and `Testing.config.mode` are gone; both
-  are per-fake now.** A suite-wide answer to a per-example question nils an
-  unrelated field one run in ten. **Move them:** `graphql_fake(null_chance:
-  0.3)` and `graphql_fake(values: :literal)` (the per-fake `mode:` is renamed
-  `values:` so it can't be confused with `graphql: :fake` /
-  `config.default_mode`, which stay). The auto-detect — faker when the gem is
-  loaded, else literal — is the only suite-wide value style.
-  `Testing::MODES` is now `VALUE_STYLES`.
-- **`retries:` takes the count you'd write, and means the same thing
-  everywhere.** `GraphWeaver.new(url, retries: 3)` raised and pointed at
-  `retries: { tries: 3 }` — a second word for the same number that disagreed
-  about whether it counted the first attempt. One word now: `retries:` is how
-  many attempts follow the first, on the client and on `Retry` alike, so
-  `retries: 0` is one attempt. **Rename** `Retry.new(tries: n)` to
-  `Retry.new(retries: n - 1)`; the default is unchanged in effect.
-- **`Response#to_h`.** Every error class answered `#to_h`; the envelope didn't.
-  It returns `{"data" =>, "errors" =>, "extensions" =>}` with each error as its
-  JSON-ready hash. `data` stays the typed struct rather than re-serialized:
-  `T::Struct#serialize` gives snake_case keys, drops nulls, and leaves a
-  registered scalar as its Ruby object — output that would pass for the
-  server's response without being one.
-- **Sensitive variables are scrubbed from the debug log.** A `login(password:)`
-  mutation's variables were one log-level switch away from the log. Matching
-  values are replaced with `[FILTERED]` at any depth, on the wire and
-  in-process paths. Rails apps configure nothing: the railtie adopts the app's
-  own `config.filter_parameters`. Elsewhere,
-  `GraphWeaver.filter_parameters = [:password, /token/]`; the default list is
-  `[:password, :token, :secret, :authorization]`, matched as case-insensitive
-  substrings, and `[]` turns filtering off.
-- **`schema:diff` names what changed, not just that something did.** It
-  reported `schema.json is stale` and stopped, so learning what moved meant
-  refreshing and reading a `git diff` of a 3 MB dump. It now prints one line
-  per change at its schema coordinate, breaking ones first — types, fields,
-  arguments, nullability, enum values, union members, interfaces and
-  deprecations — and still exits non-zero on any drift. Breaking is judged from
-  the client's side, so nullability is directional: an output losing `!` breaks
-  a generated struct, an input gaining one breaks a query that omits it.
-  `SchemaLoader.stale?` is now `SchemaLoader.diff`, returning the summary;
-  `diff(path).empty?` is what `stale?` answered.
-- **A Rails app whose generated code includes an autoloaded helper now
-  boots.** `extend_type("Pet", PetHelpers)` and `register_enum("Species",
-  PetKind)` name constants your app autoloads, so the library tells you to
-  register them from a `to_prepare` block — but the railtie required the
-  generated files before Zeitwerk was set up and before `to_prepare` ran, so
-  the `include PetHelpers` those registrations emit raised `NameError` at every
-  boot, in every environment. They now load from a `to_prepare` block of their
-  own: after the autoloader, after your registrations, before eager loading.
-- **A fragment on the abstract type no longer narrows the field away.**
-  `named { __typename ... on Named { name } ... on Pet { species } }` read the
-  `Named` fragment as a type condition and narrowed to Pet, so a Person came
-  back as `nil` and the `name` the server sent went on the floor — while the
-  same selection spelled bare dispatched correctly. Two ways of writing one
-  query disagreed, and the fragment is how anyone shares interface fields.
-  **Regenerate** to pick it up.
-- **A `Float` field reads the whole number a JSON encoder writes.** JSON has
-  one number type, so `1.0` reaches Ruby as an `Integer` from graphql-js and
-  Go's `encoding/json` alike, and `const :amount, Float` refused a response the
-  spec calls legal. Widened with `Kernel#Float`, which still refuses what
-  `.to_f` would quietly turn into `0.0`. **Regenerate** to pick it up.
-- **A guarded `__typename` no longer makes a narrowing miss look like a
-  match.** Narrowing without a readable tag decides on emptiness, but a
-  `__typename` behind `@skip`/`@include` still arrives for the member narrowing
-  means to filter, so the wrong member was cast. That query now refuses at
-  generation, with the message that already names the fix.
-- **Generation refuses what Ruby would misread.** A result key that would
-  shadow a constant the file uses (`date` beside a `Date` scalar nested a
-  `class Date < T::Struct` and typed the scalar prop as that struct) is refused
-  naming both keys; so is an enum value that camelizes to nothing (`_`), which
-  emitted a file that died at load with a syntax error.
-- **A bad enum value in a variable says what the enum accepts**, as an
-  `InputError` — it raised a bare `KeyError` naming an anonymous module as a
-  top-level variable while the same mistake inside an input object was already
-  branded. A missing required input field now lists every missing key instead
-  of sorbet's symptom for the first prop it reached. **Regenerate** to pick up
-  the new emitted coercion.
-- **A named fragment now crosses a subgraph boundary.** A stitched fetch is
-  built from selections alone, so a spread that survived into one named a
-  fragment the subgraph had never seen and the whole subtree came back
-  `Fragment X was used, but not defined`. Every spread a fetch carries is now
-  spelled as the inline fragment it is.
-- **A fake's value for a custom scalar comes from what you registered it
-  as.** It was picked off the schema's *name* for the scalar, so a `Timestamp`
-  registered as `Time` got `"Timestamp-1"` and every fake response touching it
-  died inside the codec codegen had emitted for it. A scalar registered as
-  `Time` now gets iso8601, one registered as `Integer` an Integer; an
-  unregistered one keeps its placeholder. Cassette anonymization runs through
-  the same engine and had the same hole, which made `cassettes:check` fail on
-  a cassette the anonymizer had just written. **Re-run
-  `rake graph_weaver:cassettes:anonymize`** on a cassette holding a registered
-  custom scalar.
-- **A mutation is no longer retried.** A read timeout, a 502 or a reset socket
-  does not say whether the server applied the request, and a second `charge`
-  is worse than a failed one — so `Retry` gives a mutation one attempt and says
-  so on the logger. Pass `retry_mutations: true` for an API whose mutations are
-  idempotent. Each retry now logs the wait and the attempt number.
-- **A connection that dies mid-body is a dropped connection.** net/http's
-  `ignore_eof` default handed back the bytes that arrived when a socket closed
-  short of its `Content-Length`, so a half-sent response reached you as a 200
-  with a truncated body — a permanent `ServerError` that `Retry` would not
-  retry. It now raises the retriable `TransportError` it is.
-- **An in-process query gets its own context.** graphql-ruby writes a
-  resolver's `context[...] =` into the hash it is handed, and one `InProcess`
-  is normally the whole app's client — so a flag set by one request was still
-  there for the next, and racing between them under Puma.
-- **A response that carries neither `data` nor `errors` is refused.** A client
-  returning `nil`, one keying the envelope by symbol, one that typo'd `"dat"`:
-  each produced a `Response` reporting `success?` with `data` nil.
-  `from_response` is documented public API and symbolized keys are the
-  likeliest mistake at that seam, so it now brands, naming the keys it found;
-  a client answering with a String brands too, instead of dying on `#to_h`.
-  **Regenerate** to pick that up.
-- **`@skip`/`@include` are evaluated by the fake against the variables you
-  passed**, declared defaults included — the way a server and
-  `Testing::Router` already did, so one query no longer carries a key under
-  `graphql: :fake` and not under `graphql: :router`. A faked subgraph does the
-  same for directives inside its `_entities` selection. A `first:`/`last:`
-  arriving as a variable caps the fabricated list like a literal, a cap below
-  zero reads as a page of none, and `null_chance` reaches list positions.
-- **An alias spelling a response key the router carries a `@key` under is
-  refused.** The router injects the `@key` it crosses on under a reserved key
-  and strips it from the answer, so `_gw_weight: weight` came back without
-  `_gw_weight` at all. It joins the `shadowed_key` refusal, which already
-  covered Apollo's half of the same collision.
-- **A `@requires` field set excluded by `@skip`/`@include` no longer
-  prefetches.** The router ran a subgraph fetch a real router never makes —
-  which matters for a test double, where a resolver that runs is one your
-  example can observe.
-- **`verify_generated!` fails over zero query documents**, and `generate!`
-  warns. A mistyped `queries_paths` left `verify` returning true having
-  compared nothing, so a CI gate stayed green forever.
-- **`rake graph_weaver:generate` says what it pruned, and where it looked when
-  there was nothing to generate.** Deleting a `.graphql` deletes the checked-in
-  file it produced, and the task printed nothing and exited 0; so did a run
-  with no queries, the state every install starts in.
-- **`Failure.server` takes the headers a backoff branches on.**
-  `ServerError#retry_after` and `#throttled?` read `Retry-After`, and there was
-  no way to set one: `Failure.server(status: 429, headers: { "retry-after" =>
-  "2" })`. `Failure.transport`'s message now names the class it caught, the
-  way the bundled transports do.
-- **Cassette recording is safe across threads.** `record` was
-  read-modify-write; two threads recording through one cassette each saved a
-  snapshot missing the other's entry.
-- **A `.json` schema dump that isn't JSON says which file and what it holds.**
-  A truncated download or a login page saved over the dump raised a bare
-  `JSON::ParserError`, outside `GraphWeaver::Error` and naming neither.
-  `rake graph_weaver:schema:refresh` — the fix — no longer trips over it.
-- **Setup mistakes say what to do.** A schema source that looks like a url
-  (`localhost:4000/graphql` included) gets the url advice first; a non-token
-  `auth:`, a `retries:` that is neither true nor a Hash, a url
-  `Transport::HTTP` cannot POST to, a `parse` path without a `.graphql`
-  extension, a cache directory that can't be written, `schema:refresh URL=`
-  with a file path, and `schema:diff` with no dump all name the fix. A
-  `ServerError` carries the advice its status implies: a 3xx names where the
-  server pointed (redirects are not followed) and a 401/403 names `auth:`. A
-  spec with a `graphql:` tag but no `graph_weaver/rspec` is told to require
-  it, a misspelled tag reports one failure instead of two, `InputError` no
-  longer prints sorbet's `Caller:` frame, a generated file whose registered
-  constant is gone names the registration, and `rails g graph_weaver:install`
-  names a retry that works when introspection fails.
-- **The GitHub example's checked-in modules were regenerated**, and a spec now
-  keeps them in step with the emitter.
-- **A cold process no longer introspects once per in-flight thread.** A
-  url-built client fetches its schema lazily, and Puma serves its first
-  requests concurrently — so eight threads arriving together meant eight full
-  introspection round trips, each of them also writing the schema cache. One
-  now, whoever asks first.
-- **The schema cache and cassettes are written atomically.** `File.write`
-  truncates before it writes, so an interrupted run — or a second writer, a
-  rake task beside a running app — could leave a half-written file where a
-  committed artifact used to be. Both now write beside the target and rename,
-  which is atomic: a reader sees the old file or the new one.
-- **The connection pool keeps its ceiling under an interrupt.** An async raise
-  landing between taking a permit and the `ensure` that returns it would have
-  leaked one for the life of the process, and `Rack::Timeout` raises exactly
-  that way; the gap is closed. Its saturation warning is also once now rather
-  than once per racing thread.
-
-###  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-federated-graph--graphql-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
-  (`Meta::Sub`) instead of emitting a bare `Sub` that raised NameError; alias
-  names/segments are validated as identifiers (were interpolated verbatim,
-  allowing injection); `optional:` no longer swallows a reserved-name/collision
-  mistake; a real field named `first`/`last` resolves as a field.
-- Shared unions: a hoisted member selecting a mapped enum now emits its
-  `<NAME>_FROM_WIRE` table into `unions.rb` (was a NameError at `from_h`); a
-  fragment whose name collides with `Result`/`QUERY` is refused.
-- A named interface fragment holding inline `... on X` conditions now dispatches
-  instead of silently dropping those fields; fragment cycles raise a clear error
-  in the FakeClient/Anonymizer walkers instead of `SystemStackError`.
-- Malformed responses/inputs stay under `GraphWeaver::Error`: a non-2xx
-  `errors: null` body keeps its status; a 2xx non-object body is a `ServerError`;
-  `data!` on null-data/no-errors raises `QueryError`; `coerce(non-Hash)` raises
-  `InputError`.
-- Testing harness: FakeClient/Anonymizer merge duplicate result keys (were
-  fabricating shapes the generated struct couldn't cast); `fail_at` fires every
-  execute; symbol-keyed cassette variables no longer crash on reload; the
-  Anonymizer keeps concrete-fragment fields when data lacks `__typename`.
-- Federation: a user type named `link` is no longer dropped; an all-`@inaccessible`
-  schema raises a pointed error. Client accepts `retries: nil` on a schema
-  source; `register_scalar` rejects an anonymous class.
-- FakeClient: an Integer `list_size` now means exactly that length (a Range
-  randomizes within it). Codegen rejects two variables that underscore to the
-  same kwarg (`$userId` + `$user_id`). The Faraday transport raises rather than
-  silently dropping `headers:`/block when handed a prebuilt connection.
-
-###  v0.4.5  (2026-07-30)
-- `alias:` paths gain list-element selectors: a `first`/`last` segment picks one
-  element out of a list hop, always nilable — `alias: { entity: "_entities.first" }`
-  yields `def entity = _entities&.first`, and navigation continues into the
-  element (`_entities.first.name`). Typed from the selection: a single inline
-  fragment lands on the concrete member (`T.nilable(Widget)`), a multi-fragment
-  selection on the union. Selectors are checked against the node shape — `.first`
-  on a non-list raises. Cleanly retires the `result._entities&.first&.field`
-  boilerplate of single-entity federation `_entities` queries.
-- `extend_type(..., optional: true)` makes its aliases lenient: a query whose
-  selection doesn't fit the path omits the accessor instead of failing
-  generation. For an alias on a universal type (a `Query` accessor a strict alias
-  would force every query to satisfy), or one that only fits some selections.
-
-###  v0.4.4  (2026-07-30)
-- Supergraph loading now derives the **API schema**: `@inaccessible` elements
-  (present in the federated graph but hidden from what the router serves) are
-  removed on load, cascading — a field/argument/union-member/interface
-  referencing a removed type goes too, and a type left empty is removed in turn.
-  So codegen validates against exactly what clients can query, with no
-  over-permitting and no Apollo JS tooling to subtract the API schema first.
-  Plain (non-federation) SDL is untouched.
-
-###  v0.4.3  (2026-07-30)
-- Federation-aware supergraph loading: `SchemaLoader` (and `Client.new`) now
-  load a composed Apollo Federation v2 supergraph SDL directly. When the `@join__*`
-  markers are present it strips the composition machinery — the synthetic
-  `join__*`/`link__*` types and directive definitions, and every `@join__*`/`@link`
-  application — via an AST rewrite before `from_definition`, so the merged type
-  shapes load cleanly with nothing federation-internal leaking into
-  `schema.types`. Plain SDL is untouched. A query can now be typed against the
-  composed supergraph, not just per-subgraph schema objects.
-- Removed `directive_defaults_patch.rb` (the graphql-ruby monkeypatch); the
-  preprocessor supersedes it and `graphql-ruby` fixed the underlying issue. The
-  gem now requires `graphql >= 2.6.7`.
-
-###  v0.4.2  (2026-07-30)
-- `extend_type` accepts `alias:` — project a selected field (possibly nested)
-  onto a flat, typed accessor emitted into the struct body:
-  `extend_type("Widget", alias: { tag: "meta.tag" })` generates a sig'd
-  `def tag = meta&.tag`. Retires hand-written value objects that only flattened
-  a passthrough field. Takes a `{ name => path }` hash, a bare path string
-  (accessor named after the last segment), or an array of paths. Typed from the
-  selection — a nullable hop makes the accessor nilable and nil-safe; the leaf
-  may be a scalar, enum, or nested struct. Validated per query at generation: an
-  unselected/misspelled segment (with `did you mean`), a list hop, or a name
-  collision raises. Stacks and is client-scopable like the mixin forms.
-
-###  v0.4.1  (2026-07-29)
-- Generated `execute!` forwards its kwargs to `execute` via hash shorthand
-  (`execute(client, name:, species:)` rather than `name: name, species: species`)
-  — cosmetic only. Regenerate to refresh (`verify` flags the drift otherwise).
-
-###  v0.4.0  (2026-07-28)
-- Shared unions: when a named shared fragment is the whole selection on a union
-  field (`feed { ...FeedItemFields }`), its type is hoisted once into a
-  `GraphQLUnions` module and every query that spreads it aliases the same type —
-  so a union selected across many queries is one Ruby type family (one
-  exhaustive `case … T.absurd`), not a fresh dispatch module per query. No flag:
-  the shared fragment is the opt-in. Triggers only for an exact lone spread;
-  mixing other fields, or shadowing with a query-local fragment, keeps the union
-  inlined. Module name derives from the output path (override with
-  `GraphWeaver.unions_module=`); dynamic `parse` still inlines.
-- Removed the `shared_inputs:` option from `generate!` / `verify_generated!`.
-  Directory-based generation always emits each input type once into a shared
-  module — the self-contained-module opt-out added complexity for little value.
-  Single-query `parse` / `Codegen.generate` still inline their types (there's
-  no set to share against). Only affects callers who passed
-  `shared_inputs: false`.
-
-###  v0.3.4  (2026-07-29)
-- Shared fragments: define reusable named fragments once (default
-  `app/graphql/fragments`, configurable via `GraphWeaver.fragments_paths`) and
-  spread them from any query. Each query inlines only the fragments it
-  transitively spreads, so the sent query stays self-contained. Fragment files
-  hold only fragments; names are unique across them. Works in `generate!` and
-  dynamic `parse`.
-
-###  v0.3.3  (2026-07-29)
-- Union member-type dedup: a union selected more than once on a struct now
-  collapses to one Ruby type family instead of a distinct per-field family with
-  identical members — so a consumer gets a single exhaustive
-  `case … T.absurd` across every field of that union. Structurally different
-  selections stay distinct types. (First cut: same-struct siblings; regenerate
-  checked-in modules to pick it up.)
-
-###  v0.3.2  (2026-07-29)
-- `register_scalar` accepts a `Type.field` coordinate to override how one
-  field's scalar deserializes — so the same scalar can be different Ruby types
-  across fields (`register_scalar("User.birthday", Date)` while
-  `ISO8601DateTime` stays a `Time` elsewhere). Field overrides win over the
-  scalar-name registration; both stack global-then-client. The coordinate is
-  validated against the schema (a typo'd or non-scalar field raises). Same
-  method, same signature — a `.` in the name selects the field form.
-
-###  v0.3.1  (2026-07-28)
-- `GraphWeaver.extend_t_sig` controls whether generated modules/structs emit
-  `extend T::Sig`. Default (`nil`) auto-detects a global T::Sig injection
-  (`class Module; include T::Sig`) and skips the now-redundant `extend` — so
-  generated code stays clean under rubocop's `Sorbet/RedundantExtendTSig`.
-  Force with `true`/`false`; `false` requires the global include.
-
-###  v0.3.0  (2026-07-28)
-- Renamed `register_type` to `extend_type` to disambiguate intent: it
-  *decorates* a generated struct with mixin modules/helpers — it doesn't
-  define or replace a type's deserialization (that's `register_scalar` /
-  `register_enum`, for leaf types, whose Ruby shape is fixed; a composite's
-  shape is per-query, so there's nothing fixed to replace). No deprecation —
-  the old name is dropped.
-- Invalid query input now raises `GraphWeaver::InputError` (under the
-  `GraphWeaver::Error` umbrella) instead of a raw `ArgumentError` /
-  `KeyError` / sorbet `TypeError`: an unknown or typo'd input key, a
-  missing required field, an out-of-range enum, or a wrong-typed field
-  when an input object is built from a hash through `coerce`. Carries
-  `#field` / `#struct` and a JSON-ready `#to_h` — one rescue point for
-  returning a 422 at an API boundary. Top-level *scalar* kwargs still
-  fail like any Ruby method call (sorbet `TypeError` / `ArgumentError`).
-
-###  v0.2.2  (2026-07-22)
-- Generated modules expose from_response / from_response! alongside
-  execute / execute!: deserialize a raw GraphQL response (fetched by any
-  client) into the typed envelope without going through the transport.
-  execute now delegates to from_response
-
-###  v0.2.1  (2026-07-13)
-- Conventional paths are appendable lists: queries_paths /
-  generated_paths (singular accessors read the first entry, so existing
-  config keeps working); load_generated!, Client#load_queries!, and the
-  Railtie walk every entry — append spec/support/graphql/* from a spec
-  helper to load test-only queries. Entries may be globs, and the
-  generated default includes app/graphql/*/generated so per-schema
-  layouts auto-load
-- inputs_module derives from the output path: multi-schema layouts name
-  each schema's module after its directory
-  (app/graphql/github/generated -> GithubInputs), the conventional
-  layout keeps GraphQLInputs; GraphWeaver.inputs_module= and
-  generate!(inputs_module:) still override
-- Shared types split one-file-per-type: generated/inputs/ holds each
-  input struct/enum in its own small file (PokeAPI: 573 files, median
-  24 lines vs one 11.5k-line blob) with inputs.rb as the manifest
-  (forward declarations make load order irrelevant); regeneration
-  prunes files for types the schema dropped, verify flags strays;
-  generate!/verify take inputs_module: per invocation (multi-schema
-  apps generate into different modules)
-- Shared input types: generate! emits every variable type (input
-  structs + their enums + mapped-enum tables) ONCE per schema into
-  generated/inputs.rb (module GraphQLInputs; GraphWeaver.inputs_module=
-  renames, shared_inputs: false opts out), with query modules aliasing
-  only what their own surface references — AdoptQuery::AdoptionInput
-  keeps working and shared types gain one identity across modules.
-  Three filtered Hasura queries: 34,684 lines inline -> 11,754 shared
-  (~90 lines per query module)
-- BREAKING (vs 0.2.0): auto_fake is opt-in again — require
-  "graph_weaver/rspec" no longer swaps every example onto a fake;
-  set config.auto_fake = true explicitly (the schema still auto-locates
-  once you do). Less magic, no unexpected behavior
-- Generated input structs are table-driven: typed consts + a per-field
-  FIELDS table (conversions as lambdas) interpreted by the
-  GraphWeaver::InputStruct runtime, replacing unrolled
-  serialize/coerce/value_at per struct — a bool_exp-heavy PokeAPI module
-  shrinks 29k -> 11.5k lines (-60%) with identical behavior (nil
-  omission, wire-value enums, nested/recursive coercion, spellchecked
-  unknown keys all covered by the existing suite)
-- Internal: Node base class for the codegen IR protocol; module
-  assembly moved from Codegen#generate into Emit#emit_module
-  (byte-identical output)
-
-###  v0.2.0  (2026-07-12)
-- Cleanup pass (staff-engineer review): scalar registrations get the
-  same typo validation as enums/types; cassette replay stops recomputing
-  its key per entry; dependency-order DFS uses hash bookkeeping (big
-  bool_exp graphs); require/vocabulary residue swept; the vestigial
-  graph_weaver/testing/rspec shim removed
-- BREAKING: "client" replaces "executor" across the whole surface.
-  Generated modules: the per-call override is an optional POSITIONAL
-  first argument — PersonQuery.execute(github, id: "1") — so variables
-  own the entire kwarg namespace and NOTHING is reserved (a $client or
-  $executor variable is fine; only Ruby keywords refuse); per-module is
-  MyQuery.client=, the baked param is client:. GraphWeaver.executor= is
-  gone — GraphWeaver.client= is the one ambient slot (auto_fake swaps
-  it per example; explicit clients are self-contained and never see it).
-  Client#executor is now Client#transport (transport: to bring your
-  own); SchemaLoader.introspect/stale? speak transport. Renames:
-  FakeExecutor => Testing::FakeClient, SequenceExecutor =>
-  Testing::Sequence, RetryExecutor => GraphWeaver::Retry,
-  Recording/ReplayExecutor => Recorder/Replayer, Cassette.use(client:)
-- Live federation integration: two Ruby subgraphs (apollo-federation
-  gem) composed and routed by a real Apollo gateway (node harness under
-  spec/support/federation), with GraphWeaver introspecting through the
-  router and executing a query stitched across BOTH subgraphs — part of
-  make integration. Complements the existing supergraph-SDL codegen spec
-- graphql-over-http: a non-2xx response carrying a GraphQL errors body
-  (Apollo Server/Router send request errors as 4xx JSON) flows into the
-  Response envelope so QueryError sees the structured errors; only
-  non-GraphQL bodies (proxy pages) raise ServerError
-- Fix: input-struct serialize used bare locals (result/value) that a
-  same-named prop silently shadowed — a field named "result" dropped
-  its value onto the wrong target; generated locals now wear the
-  reserved __gw prefix (GraphQL reserves __-names, so no collision is
-  possible)
-- Input fields and variables whose Ruby name would be a keyword
-  (nil/def/end/...), a generated method (serialize/to_h), or the
-  reserved executor kwarg now refuse at generation with a pointed
-  error instead of emitting broken code
-- Non-JSON 200 bodies (proxy error pages) classify as ServerError, and
-  unserializable variables (NaN/Infinity) raise GraphWeaver::Error —
-  raw JSON::* errors no longer escape the umbrella
-- Transports redact on inspect/to_s (class + url only) — Authorization
-  headers can't leak through logs or exception dumps
-- Narrowed `... on X` selections require at least one unconditional
-  field: with every field behind @skip/@include, a matching response is
-  {} — byte-identical to a non-match — so generation refuses rather
-  than silently dropping real matches to nil
-- Integration spec against Hasura's PokeAPI: snake_case codegen,
-  recursive bool_exp variable filtering, untyped jsonb pass-through
-  (make integration)
-- BREAKING: ValidationError now descends from GraphWeaver::Error (was
-  ArgumentError) — one `rescue GraphWeaver::Error` catches everything
-- Input-struct .coerce raises on unknown hash keys with a spellchecked
-  hint — a typo'd filter key no longer silently drops off the wire
-- Client registrations (register_type/register_enum) validate at the
-  call site when the schema is already loaded; lazy clients still
-  validate at generation
-- Unregistered custom scalars emit bare T.untyped (not
-  T.nilable(T.untyped), an srb tc error under typed: strict)
-- Wire log lines carry [req N OperationName] tags; long queries
-  (introspection) truncate at debug
-- Logging: GraphWeaver.logger (any stdlib-compatible Logger; Rails.logger
-  auto-wired by the railtie) — wire traffic + timings at debug,
-  introspection/cache/codegen at info, every raised error at warn
-- Recursive input types generate — self- and mutually-referential inputs
-  (Hasura's bool_exp filter surface) emit dependency-ordered structs with
-  runtime forward declarations for cycles, so variable-driven Hasura
-  filtering works; previously raised "recursive input type"
-- Fix: snake_case GraphQL type names (Hasura, PostGraphile) camelize
-  into valid Ruby constants — pokemon_v2_pokemon => PokemonV2Pokemon
-  (previously generated a SyntaxError); wire names (__typename dispatch,
-  registry keys) are untouched
-- Everything raised is rescuable: unparseable queries wrap as
-  ValidationError (GraphQL::ParseError no longer leaks), and internal
-  NotImplementedError raises (recursive inputs, unsupported kinds,
-  subscriptions) became GraphWeaver::Error
-- Transport::HTTP takes open_timeout:/read_timeout: (defaults 10s/30s);
-  timeouts surface as retriable TransportError
-- Transport::HTTP reuses its connection (keep-alive, mutex-serialized,
-  keep_alive_timeout: for the idle window); any failure drops the socket
-  so the next call starts fresh
-- GraphQLError#code also reads a top-level "type" (GitHub's dialect:
-  NOT_FOUND, FORBIDDEN) when extensions.code is absent
-- Typo'd client-scoped registrations raise at generation with a
-  spellchecked hint (register_type("Pett") => "did you mean 'Pet'?")
-  instead of silently no-oping
-- Abstract selections narrow: __typename is only required when the
-  selection varies by concrete type. Interface-level-fields-only
-  selections generate one shared struct (no dispatch); a single
-  `... on X` condition generates X's struct, always nilable — a
-  non-matching runtime type casts to nil, so narrowing doubles as
-  filtering
-- Zero-config rspec: require "graph_weaver/rspec" now defaults
-  auto_fake on and auto-locates the schema from the committed dump
-  (config.schema= / config.auto_fake = false to override) — one line is
-  the whole test setup in a conventional app
-- examples/: runnable demos, all directly executable — countries.rb
-  (public API, no auth, all dynamic), rick_and_morty.rb (filtered
-  search, pagination, a block-built type helper), and github/ (auth,
-  checked-in generated modules; stars the repo ⭐ then tours the
-  stargazers, their top repos, and what else they've starred); excluded
-  from the gem package
-- Fix: requires: now load before codec probing, so inference sees
-  methods the required file provides — register_scalar("DateTime", Time,
-  requires: "time") correctly infers Time.parse in a fresh process
-  (previously the cast was silently skipped unless "time" was already
-  loaded)
-- docs/quickstart.md renamed to docs/getting_started.md
-- Rails Railtie: the graph_weaver:* rake tasks self-register (no
-  Rakefile edit) and depend on :environment, and generated modules load
-  at boot (after initializers) when generated_path exists; outside
-  Rails, require "graph_weaver/tasks" and call load_generated! as before
-- BREAKING (vs 0.1.0): reset_scalars! lost its coerce: flavor —
-  GraphWeaver.auto_coerce = true is the one way to default-coerce
-  (broader: convertible built-ins AND full cast/serialize scalars,
-  resolved lazily, per-registration coerce: still wins)
-- GraphWeaver.client= — the blessed global wiring: assign the app's
-  default client and generated modules resolve through it (per call ->
-  per module -> baked -> executor= -> client). executor= stays as the
-  low-level override, so test fakes still win
-- Enum mappings: register_enum("Species", PetKind) (+ bulk
-  register_enums, client-scoped variants) — generated code speaks YOUR
-  T::Enum, with the wire mapping inferred by name, pinned via map:,
-  exhaustiveness-checked at generation (fails naming gaps), and
-  fallback: to absorb unknown wire values on cast (inputs stay strict);
-  translation tables emitted into the source (X_FROM_WIRE / X_TO_WIRE)
-- Type helpers: register_type("Pet", PetHelpers) (global or
-  client-scoped, additive) — app-owned modules included into every
-  struct generated from that GraphQL type, so derived values live as
-  methods beside the honest wire data and srb tc checks them against
-  each query's selection. Or build the mixin inline with a block
-  (module_eval'd into an auto-named GraphWeaver::TypeHelpers constant —
-  quick decoration, invisible to srb tc)
-- BREAKING (vs 0.1.0): register_scalar takes the type positionally —
-  register_scalar("Money", Money, requires: ...) — matching the new
-  registrars: the GraphQL name + your Ruby type up front, options as
-  kwargs
-- GraphWeaver::Client — transport, schema, and scalars for one server in
-  one object: GraphWeaver.new(url_or_schema) takes a url (transport
-  built, schema introspected lazily per cache:/ttl:) or a schema source
-  (live class — also the in-process executor — or a path/SDL/dump);
-  #parse and #execute/#execute! bind the implicit schema + transport;
-  #register_scalar scopes scalar mappings to the client (overlaying the
-  global registry), so two servers can disagree about a scalar type
-- BREAKING: GraphWeaver.connect removed — GraphWeaver.new(url) replaces
-  it (wire generated modules with GraphWeaver.executor = client.executor)
-- BREAKING: the one-shots are now GraphWeaver.execute(url_or_schema,
-  query, **variables) / execute! — Client#execute on a throwaway client;
-  variables are plain kwargs, as on a generated module
-- Client#load_queries! — parse every query file into modules named like
-  generation would name them (reloadable; namespace: to scope): the
-  no-build-step analog of generate! + load_generated!
-- Introspected schema dumps record provenance (source url + timestamp):
-  a parsable SDL header comment, a "graph_weaver" sibling key in JSON —
-  read it back with SchemaLoader.provenance(path), check drift with
-  SchemaLoader.stale?(path) or rake graph_weaver:schema:verify, rewrite
-  with rake graph_weaver:schema:refresh (GRAPHWEAVER_AUTH for tokens)
-- generate!/verify_generated!/rake auto-locate the schema dump at
-  schema_path in any supported format; SchemaLoader.locate is public
-- Calling a result field by its camelCase wire name raises a pointed
-  NoMethodError naming the snake_case prop that does exist
-  (result.addPet => "use 'add_pet'"), and near-miss typos in either
-  casing get a spellchecked suggestion (result.addPt => "did you mean
-  'add_pet'?") — the runtime companion to srb tc's static flag
-- BREAKING: an operation whose only variable is a required input object
-  (the Relay convention) now flattens the input's fields into execute's
-  kwargs — AdoptQuery.execute!(name:, species:) instead of
-  execute!(input: {...}); multi-variable / nullable-input operations
-  keep the input: kwarg (struct or hash)
-- Enum kwargs accept the T::Enum or its wire value (T.any(Enum, String))
-  everywhere — variables now match input-hash fields
-- BREAKING: HttpExecutor / FaradayExecutor are now Transport::HTTP /
-  Transport::Faraday, subclasses of the new abstract GraphWeaver::Transport
-  base, which owns the shared flow (encode, TransportError reclassify,
-  non-2xx ServerError, parse) — a custom transport just implements
-  post(body) => [status, body]. Opt-in require moved:
-  "graph_weaver/faraday_executor" -> "graph_weaver/transport/faraday"
-- SchemaLoader.introspect cache: reuses a fresh dump in ANY supported
-  format before re-introspecting (an existing schema.graphql wins over
-  writing schema.json), and accepts :json / :graphql / :gql to pick the
-  format at GraphWeaver.schema_path's location
-- rubydoc.info rendering: ship .yardopts (markdown markup, docs/ guides
-  as extra files) and re-indent docstring examples so code blocks and
-  backticks render; make docs previews locally
-- GraphWeaver.connect(url, auth:, headers:, retries:): one-shot setup —
-  best transport (Faraday when the app loads it; detection is defined?,
-  never a require), bearer/verbatim auth, opt-in RetryExecutor wrapping
-  (true / options Hash; off by default), wired in as the global executor
-- Generation workflow: GraphWeaver.generate! (queries dir -> generated
-  dir), verify_generated! (the freshness guard — raises naming stale
-  files), load_generated! (factory_bot-style explicit loading), rake
-  tasks (require "graph_weaver/tasks": graph_weaver:generate / :verify),
-  all defaulting to configurable conventional paths (queries_path /
-  generated_path / schema_path)
-- GraphWeaver.auto_coerce = true: default input coercion for scalars
-  without an explicit coerce:, resolved lazily at generation time (no
-  reset_scalars! ordering dance) — convertible built-ins take their
-  conversion, cast/serialize pairs take parse-style coercion
-- SchemaLoader.introspect cache: true — caches at GraphWeaver.schema_path,
-  in the format the extension picks: .json (verbatim wire artifact) or
-  .graphql/.gql (SDL — human-readable, PR-reviewable diffs);
-  the same dump rake graph_weaver:generate reads
-- docs/transports.md: connect, the executor contract, Faraday, retries
-- Cassette workflow: GRAPHWEAVER_RECORD=1 / config.record force
-  re-recording; config.anonymize scrubs responses as they are recorded
-  (caller sees the anonymized data too, so assertions hold on replay);
-  rake graph_weaver:cassettes:anonymize; docs/cassettes.md guide
-- auto_coerce reaches input-object fields: raw scalar values inside
-  input hashes coerce via the registry, mutations included
-- RetryExecutor: composable retries over any transport — tries:,
-  exponential/linear/custom backoff with jitter and max clamp,
-  retry-by-error-class (5xx yes, 4xx no by default; retry_if: override)
-  and retry-by-GraphQL-code (retry_codes: ["THROTTLED"])
-
-###  v0.1.0  (2026-07-11)
-- Structured errors: execute returns a typed Response envelope (#data/#data!,
-  #errors, #errors?, #extensions) instead of raising on GraphQL errors, so
-  partial data and top-level extensions (cost/throttle) survive. Error classes
-  under GraphWeaver::Error — TransportError (network), ServerError (non-2xx
-  HTTP, #status/#body), QueryError (#errors/#data/#extensions/#codes),
-  ValidationError (build-time) — plus a GraphQLError value object with #code.
-  Transport-error classification is an extensible Set (GraphWeaver.transport_errors
-  / register_transport_error): each transport seeds its own network exceptions
-  and apps can add more (e.g. a connection-pool timeout).
-  The envelope is a single generic GraphWeaver::Response[Result] (no per-query
-  wrapper class). execute! is the shortcut for execute(...).data! — the typed
-  result or a raised QueryError — on both generated modules and the one-shot
-  GraphWeaver.execute!/execute.
-  BREAKING: module #execute returns Response; use #execute! (or #data!) for
-  the old raise-or-result behavior. GraphWeaver.execute now returns the
-  envelope too; GraphWeaver.execute! returns the result.
-- GraphWeaver.register_scalar: custom scalar deserialization into rich Ruby
-  objects. cast/serialize inferred from a class type via paired codecs
-  (.parse/#to_s or .load/.dump), or given as a Symbol/Proc (:itself opts out);
-  requires: emits (validated, and require-checked when type: is a class)
-  requires into generated source — the built-in Date scalar carries
-  require "date" so Date-using queries are self-contained; coerce: true lets a
-  variable accept the value or its raw input (coerce: :to_f for a built-in
-  conversion), casting/converting the latter — reset_scalars!(coerce: true)
-  reloads the built-ins coercible; built-in scalars pre-registered in one
-  overridable registry (reset_scalars!/clear_scalars!)
-- FaradayExecutor: url, Faraday connection, or middleware block
-- GraphWeaver.executor default transport; per-module executor= override
-- GraphWeaver.parse and GraphWeaver.execute (dynamic queries)
-- Codegen.generate shorthand; executor: takes a constant; module_name
-  derived from operation or file name
-- Error ergonomics: schema_stale? (validation-shaped rejections hint at
-  regeneration), errors_at(path) + each_error/errors_by_field filtering,
-  #report (field-keyed rollup with entity ids resolved from partial
-  data), #to_h across the hierarchy (JSON-ready machine output), and
-  GraphWeaver::TypeError wrapping cast failures with the failing struct
-- SchemaLoader: introspect(executor, cache:, ttl:) fetches schemas from
-  live endpoints with file caching; load accepts introspection JSON /
-  SDL content / Hashes as well as paths (cache round-trips)
-- GraphWeaver::Testing (require "graph_weaver/testing", or
-  "graph_weaver/rspec" for the rspec integration): FakeExecutor
-  fabricates schema-correct castable responses (mode: :faker semantic
-  values / :literal; overrides by GraphQL name; seeded; list_size /
-  null_chance), failure simulation (Failure.transport/server/graphql/
-  throttled/stale_schema, SequenceExecutor for retries, fail_at: with
-  spec-correct null propagation, corrupt: for derived type mismatches),
-  cassette record/replay above the transport, and Cassette#anonymize!
-  (shape-preserving, consistent id mapping). rspec: seed follows
-  --seed; auto_fake installs a fake executor per example
-- one-off integration specs against live GitHub + Countries APIs
-  (make integration)
-- Input objects: INPUT_OBJECT variables generate module-level T::Structs
-  with serialize (aliased to_h) producing the wire hash; execute kwargs
-  also accept plain hashes, normalized + type-checked via the generated
-  .coerce (underscored Symbol/String keys, enums as instances or wire
-  values, nested inputs as hashes)
-- fields under @skip/@include generate nilable regardless of schema
-  nullability; FakeExecutor honors first/last/limit when sizing lists
-- eval hardening for parse: module names must be constant names, and
-  QUERY heredocs can't be terminated early by block strings
-- GraphWeaver::Selection: one shared query-walk (codegen, FakeExecutor,
-  anonymizer); codegen split into scalar_type / nodes / emit
-- docs/: generated_modules, real_world, scalars, errors, testing;
-  README slimmed to pitch + quickstart
-
-###  v0.0.1  (2026-07-07)
-- voila: typed codegen (T::Structs, T::Enums, typed variable kwargs)
-- queries + mutations; fragments, unions, interfaces, enums, custom scalars
-- schema sources: live class, introspection JSON, SDL (incl. supergraph)
-- pluggable executor: in-process schema or HTTP
-- dynamic (no-build) mode for development