graph_weaver 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f9913a2f1dba64e814682cd54d4f6f3da0696071e1f20f0045aaf585eb8fe4b
-  data.tar.gz: 57f2f2b701f09c52235dd0acedee77891b8ed0a570f28a086e140ef3c7a7c57b
+  metadata.gz: 3847d3890b566828d7bfe496a6523b1032036d6aad4df0959f0b940bddb14d9b
+  data.tar.gz: d2a38677d13f8a0f2a92c67c9082a1a9523add9429bf4388419dbabc8959302f
 SHA512:
-  metadata.gz: 469bff9b186698995c51ed7997957ecccb613c70da29ea0a9788e9597cb9c4cb4a679ceb95cd23aade6475159dbbd47fa7f13c5073ee5a28b5f3f2b0e4dc3483
-  data.tar.gz: 0144261b27419fd180a96193c0cfc1a6bc2d023fbb9d2cbb55e45f9608118385b91d4e2ee5a453a21c0022a0804aa88e598981c925322b3519144bfd246d0c45
+  metadata.gz: 118114092cf2cd436e8189fb79dd5be733aa25e34d0aa727da9247e87bc5e309b2b3692248ffa9e40832bf743d672859db444c3fcffc4fc1cbb263b6c395b7e4
+  data.tar.gz: c0846cca1819d0e2b75d98f4b8d6a74af2f29113686998bd9e616a7d7d1e9a3a70edbe985412c4750a8ec63f0f0c4389e6363c1bc9d58b251a10b2f652d10e0b

data/CHANGELOG.md

@@ -1,3 +1,540 @@
+###  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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.5.0)
+    graph_weaver (0.6.0)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -99,16 +99,16 @@ GEM
     rubydex (0.2.7-arm64-darwin)
     rubydex (0.2.7-x86_64-darwin)
     rubydex (0.2.7-x86_64-linux)
-    simplecov (1.1.1)
-    sorbet (0.6.13454)
-      sorbet-static (= 0.6.13454)
-    sorbet-runtime (0.6.13454)
-    sorbet-static (0.6.13454-aarch64-linux)
-    sorbet-static (0.6.13454-universal-darwin)
-    sorbet-static (0.6.13454-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13454)
-      sorbet (= 0.6.13454)
-      sorbet-runtime (= 0.6.13454)
+    simplecov (1.2.0)
+    sorbet (0.6.13485)
+      sorbet-static (= 0.6.13485)
+    sorbet-runtime (0.6.13485)
+    sorbet-static (0.6.13485-aarch64-linux)
+    sorbet-static (0.6.13485-universal-darwin)
+    sorbet-static (0.6.13485-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13485)
+      sorbet (= 0.6.13485)
+      sorbet-runtime (= 0.6.13485)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -176,7 +176,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.5.0)
+  graph_weaver (0.6.0)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
@@ -206,13 +206,13 @@ CHECKSUMS
   rubydex (0.2.7-arm64-darwin) sha256=f0d28bbf4153568be79b671642424750053e0bea971b60ddf5cec19bf4563990
   rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
   rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
-  simplecov (1.1.1) sha256=25825ef13f0b2e74694d769817dad6ab8e90131dabdaa666e522fea105521e78
-  sorbet (0.6.13454) sha256=3273dda082b8aa5ecf79b7675e2b79127f202a45370d881124af3af19a3c2b35
-  sorbet-runtime (0.6.13454) sha256=b9441ae4bd265f51861c54240e8c5888f6355e3284885b21c5154b184e791d80
-  sorbet-static (0.6.13454-aarch64-linux) sha256=e09dd1e6cd7e63b3fb6c8c9c6785eeb55a6c4afecb0f932538ee4401b4552632
-  sorbet-static (0.6.13454-universal-darwin) sha256=6ac0cf10ae2b4e0e9ecabb886f9be739046424dc35d100e7888c8538a223f93a
-  sorbet-static (0.6.13454-x86_64-linux) sha256=569c52ea926e514ebfdc64825f65cd188b7aba5c1b480cc26e1870fd53d5e2c0
-  sorbet-static-and-runtime (0.6.13454) sha256=defc00684a6f8bd498bb70a4541f293b9232938a776137946247cba4baed3d20
+  simplecov (1.2.0) sha256=ea6acd05eece5a41990e2a5171c57d15700d329326c7666c85ee8c6a0dd0977e
+  sorbet (0.6.13485) sha256=b885d6a2fcde57bc46c3cdd597b9014b82619dee0f811a6fdf36f57c8f82c380
+  sorbet-runtime (0.6.13485) sha256=2982504e662eb424e515b3aa1c8139070451a014b6c1af2302250ed82495b4cc
+  sorbet-static (0.6.13485-aarch64-linux) sha256=5d802793633363442f189615fdb6c6d1be726b402d78a3d63eab96ca74b98d40
+  sorbet-static (0.6.13485-universal-darwin) sha256=6c7c4551872d556b37bf1f1a3495509b9fd9479b4a080bd57f9c5db0e8116658
+  sorbet-static (0.6.13485-x86_64-linux) sha256=e22d88df0bba5a97e664a329a2212ea59e6a2020626597a162c60c5ddfb4f9b4
+  sorbet-static-and-runtime (0.6.13485) sha256=b893346f9e1a244133071ad3c3d06b8ddf70c1b8246bb594c9aaa5cfc778df5f
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73