graph_weaver 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af7804f6f324bf878d1b11ba4da8e2adc8e2ea4c055fb80a703e91d8ca4eb3cd
-  data.tar.gz: fe6fd6340203a8937c836281342c0efcdb701203295e8a4fcf37260892a5afec
+  metadata.gz: 12bea1d4f3d38c00c496ec595788629ea6c12c9f7590fc7938976570d8c86917
+  data.tar.gz: e7f8e60574801cc70032a4e2502a05d6ec8f9ac170ab22b53fa12b4f2633835a
 SHA512:
-  metadata.gz: 1e5bd51d719bec6ddb81a75bab2bc68bb7b7ab9fd0c656fbbb0fd2497433ebe733893bda80e7d5dc1b4735487c1d787c5d10156dd7b0f8634e6740907af4fe01
-  data.tar.gz: 4fd87cae3d8c320c9dfb61b08f4464d3d2978c831a35c0b26c4262b27929e90da52e1a528d411b6b1689d45e24edca5d2727c3e9dc42bb5bf6202589d0973d71
+  metadata.gz: e913ad4e5104a983b7ba0d87ae838de4a6e9e238aa7fc70c3d8d673ee24faba7eecf2734c7d403443cd2acdf93d4723adbc01bc0fc485e738df608f63adf43c1
+  data.tar.gz: cc1d344c3f99c5d587a3abb5e385626048d4821766c458ae7a7401b639ab9851c6c253d618282b9e314310bae88583240b0770588b06c898052e7a96d8472975

data/CHANGELOG.md

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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.5.1)
+    graph_weaver (0.6.1)
       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.1)
+  graph_weaver (0.6.1)
   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