graph_weaver 0.7.3 → 0.7.5

data/docs/migrating.md

@@ -0,0 +1,119 @@
+# Migrating from graphql-client (or a hand-rolled client)
+
+**The wire doesn't change.** The same query text goes out and the same JSON comes
+back, so this is a sequence of small commits rather than a cutover: queries move
+across one at a time while the old client keeps serving, and most of the spec
+suite you already have keeps passing untouched.
+
+Budget 3–4 weeks of one engineer for an app with ~40 queries and 25k lines of
+code reading them — [what it costs](#what-it-costs) breaks that down. If the app
+doesn't run Sorbet and has fewer than ten queries, don't migrate: the wins that
+survive without `srb tc` are real, but they don't pay for a checked-in code
+generator ([alternatives](alternatives.md#graphlient)).
+
+## From graphql-client, in Rails
+
+**Both gems stay in the Gemfile until the last commit.** `rails g
+graph_weaver:install` boots the app to read your configuration, so an initializer
+that still requires graphql-client has to keep resolving — remove the gem first
+and the generator dies on `cannot load such file -- graphql/client`. Running the
+two side by side is the right shape anyway.
+
+1. **Install beside graphql-client**, pointed at the dump you already have:
+   `rails g graph_weaver:install db/petstore_schema.json` ([a schema dump you
+   already have](getting_started.md#a-schema-dump-you-already-have)). Commit that
+   and nothing else.
+2. **Adopt the dump.** It records no source url, so `schema:diff` and
+   `queries:check` have no server to ask. `rake graph_weaver:schema:refresh`
+   rewrites it from the client the app points at (or `URL=<your endpoint>` once)
+   and records the provenance. Do it now: until you do, `queries:check` is
+   re-reading the file it is meant to be checking against, and says so.
+3. **Register scalars and enums, and regenerate**, before porting any code.
+   Registrations are baked into generated source, so one added later reaches
+   nothing until the next `rake graph_weaver:generate` ([scalars](scalars.md)).
+4. **Port one query end to end** — write the `.graphql` file, generate, rewrite
+   its call site — and leave the specs alone. They pass untouched. That single
+   commit is the proof for every one after it.
+5. **Port the rest, one commit per query.** Each `Client.parse` constant stays
+   where it is until its last caller is gone.
+6. **Only now port the specs** to `graphql: :fake` ([testing](testing.md)). Keep
+   webmock until the last wire-level stub is gone, and keep one spec that really
+   serves HTTP.
+7. **Delete graphql-client.** Last commit.
+8. **Sigs through your own app are a separate project**, after all of the above —
+   [the types stop where your sigs do](getting_started.md#the-types-stop-where-your-sigs-do)
+   says what that work is.
+
+Keep your own error classes. Translating `GraphWeaver::QueryError`,
+`TransportError` and `ServerError` at one seam leaves a controller, its rescues
+and their specs untouched ([errors](errors.md)). Keep your presenters too, and
+your fixtures until step 6.
+
+### Why app code and specs are separate commits
+
+Because the wire is the same, a webmock suite doesn't notice which client sent
+the request. Swap the client under an untouched suite and most of it stays green
+— 18 of 22 stubbed examples in one migrated Rails app, same stubs, same JSON
+fixtures; the four that failed were unit specs feeding a hand-rolled `Struct` to
+a presenter. That is the difference between a reviewable migration and a big-bang
+one.
+
+## From a hand-rolled client
+
+Same skeleton, three differences.
+
+- **One branch, no seam.** There's no generator to keep bootable and a
+  hand-rolled client is sixty lines, so running two of them side by side costs
+  more than it saves.
+- **Set the load order first**: `GraphWeaver.load_generated!` goes before your own
+  requires ([not Rails?](getting_started.md#not-rails)). Add `rake` to the Gemfile
+  while you're there.
+- **Keep the old client's transport specs**, rewritten against a real
+  `GraphWeaver.new(url, retries: 2)` with webmock. Retries, timeouts and backoff
+  are the one thing fakes can't cover.
+
+## What you delete
+
+- **The retry loop.** A hand-rolled one usually retries everything, mutations
+  included. `retries: 2` excludes mutations by default, honours `Retry-After`,
+  and knows 408 and 429 ([retries](transports.md#retries)) — twenty lines gone and
+  a correctness bug gone with them.
+- **Scalar parsers.** `register_scalar("Money", Money)` is one line, and it
+  deletes the `"USD 12.50".split` sitting in every place that parsed one. `Date`
+  and `DateTime` need no registration at all ([scalars](scalars.md)).
+- **Fragment unwrapping.** graphql-client masks a spread fragment's fields on the
+  parent, so every call site reads `Petstore::PetFields.new(data.pet).name` and
+  carries the parent alongside for the fields the fragment didn't cover. Generated
+  structs inline the fragment, so it's `pet.name`; a fragment that is a whole
+  selection becomes one shared Ruby type
+  ([hoisting](generated_modules.md#a-shared-fragment-is-one-type)).
+- **JSON fixtures and stub helpers.** `graphql: :fake` fabricates a
+  schema-correct response and you pin the fields the example is about. Pins are
+  schema vocabulary (`"Pet.species" => "DOG"`), so they survive query refactors,
+  and they're spellchecked — a typo raises instead of leaving the example green
+  against random data ([testing](testing.md)).
+
+## The one behaviour change to plan for
+
+**Enum drift is fatal.** A hand-rolled client hands you the raw string, so a value
+the server added after you shipped falls through to whatever your code does with
+an unknown one — commonly a `humanize`. A generated enum refuses instead: casting
+raises and the whole response is lost, naming the value, the enum and the values
+it knows about.
+
+That is the right default for an API you own and a real risk for one you don't,
+because it breaks on a day nobody deployed. Before you port a query over an enum
+someone else can extend, register a fallback for it and unknown values land there
+instead — [enums](scalars.md#enums-map-onto-your-own-tenum).
+
+## What it costs
+
+| | how it scales | ~40 queries, 25k lines |
+|---|---|---|
+| `.graphql` files and generating | sublinear — the second query costs a tenth of the first | 2–3 days |
+| call sites | linear, and the bulk of it: every `data["x"]["y"]` becomes `x.y`, and every defensive `nil` guard either disappears or turns out to have been wrong | ~1 day per 3–4k lines of consuming code |
+| specs | linear, and pleasant — the fixture-to-pin conversion is the same edit every time | ~2 days |
+| sigs through your own app | the one that decides whether the migration paid off | weeks; a separate project |
+
+Coming off graphql-client, run the new one behind the old for the first two
+weeks. The wire compatibility makes that free.

data/docs/scalars.md

@@ -63,25 +63,47 @@ reach: the wire spelling (`BigDecimal#to_s` writes `"0.125e2"`, which is not wha
 any server means by 12.5) and the file to require, so the generated source stands
 alone.
 
+Taking `register_scalar("Count", <type>)` as the example:
+
 | Ruby type | cast | serialize | require |
 |---|---|---|---|
 | `BigDecimal` | `BigDecimal(v)` | `v.to_s("F")` | `bigdecimal` |
-| `Float` | `GraphWeaver::Coerce.float(v)` | — | — |
 | `Date` | `Date.iso8601(v)` | `v.strftime("%F")` | `date` |
-| `Time` | `Time.parse(v)` | `GraphWeaver::Coerce.timestamp(v)` | `time` |
+| `Time` | `Time.iso8601(v)` | `GraphWeaver::Coerce.timestamp(v)` | `time` |
 | `DateTime` | `DateTime.iso8601(v)` | `GraphWeaver::Coerce.timestamp(v)` | `date` |
+| `Integer` | `GraphWeaver::Coerce.integer(v, "Count")` | — | — |
+| `Float` | `GraphWeaver::Coerce.float(v, "Count")` | — | — |
+| `String` | `GraphWeaver::Coerce.string(v, "Count")` | — | — |
+| `T::Boolean` | `GraphWeaver::Coerce.boolean(v, "Count")` | — | — |
+| `Hash`, `Array` | — | — | — |
 
 For a timestamp reach for `Time`; Ruby's own `DateTime` is accepted if you
-register it, but never assumed. `Time.parse` is the tolerant reader, and about 7×
-the cost of a strict one — noise until you are casting thousands of timestamps per
-response, where `register_scalar("Timestamp", Time, cast: :iso8601)` is both
-cheaper and narrower.
+register it, but never assumed. All three read ISO 8601 and nothing else, which
+is the one spelling a spec-compliant server writes. To take `Time.parse`'s looser
+forms as well — a space instead of the `T`, a zone name, `"Jan 15 2024 10:20"` —
+say so: `register_scalar("Timestamp", Time, cast: :parse)`, at about 3× the cost
+per timestamp.
 
 **A trailing zero doesn't survive the round trip.** A `BigDecimal` holds the
 *number*, so `"10.00"` in comes back `"10.0"` — numerically identical, textually
 different, which matters only where the bytes are: diffing a request body, or
 hashing one for a signature.
 
+**The last five rows are the types JSON already holds**, so they write
+themselves — nothing to serialize — and naming one says the scalar *is* that
+Ruby type. The library's own rule for the class then runs in both directions,
+refusing in the scalar's name: `register_scalar("Count", Integer)` reads and
+writes exactly as `Int` coerces a variable, so `5`, `"5"` and `5.0` all arrive
+as `5`, while `"abc"`, `1.5` and `true` raise naming `Count`. `Hash` and `Array`
+pass through untouched — `Coerce` has no rule for either, and anything else
+would be a guess.
+
+Coming back that is the **lenient** reading, unlike the spec's own `Int`, which
+[refuses `"1"`](#coming-back--what-from_h-accepts): a compliant server writes an
+`Int` as a JSON number, but a custom scalar is the server's own and may well
+write the number as a string. The registration is you saying "make this an
+`Integer`"; refusing the garbage is what protects you.
+
 ## Registering a class of your own
 
 Pass the class and the cast/serialize are **inferred** from it, by probing the
@@ -102,6 +124,15 @@ response unequal, and useless as hash keys, while the `Money` inside them compar
 fine. Registration warns when it spots one; `alias_method :eql?, :==` plus a
 `hash` built from the same values is the whole fix.
 
+**A `cast:` with nothing to write back is half a codec**, and registration says
+so too. `Kernel#Type` is the inference that lands there — it reads the wire and
+pairs with nothing — so a variable of that scalar goes out as whatever `#to_json`
+makes of the object, and a result's `as_json` can't reproduce what the server
+sent. Both are silent, because every object answers `#to_json`. Name a
+`serialize:`, or `serialize: :itself` if the value really does go out as it is. A
+type JSON already holds (a `String`, `Integer`, `Float`, `Hash` or `Array`, or a
+subclass of one) writes itself, and is left alone.
+
 A type defining none of those probes stays pass-through rather than getting
 wrapped — every object has `#to_s`, so inferring a serializer off it would wrap
 plain types too. Override explicitly when you need to:
@@ -175,17 +206,18 @@ GraphWeaver.extend_type("Money") { def to_money = ::Money.from_amount(BigDecimal
 ```
 
 **One `serialize:` serves both directions** — the outbound variable *and* a
-result's [`as_json`](generated_modules.md#anatomy), which is what makes
-`from_h(JSON.parse(x.to_json)) == x` hold. So a scalar that sends an object and
-accepts a string can't have both: `as_json` writes the string the cast can't read,
-and the JSON round trip raises a `CastError` coming back (the wire itself is fine
-in both directions). The same asymmetry decides the [`:fake` pin](testing.md#pins):
-a pin stands in for a *result*, so pin what the server **sends**.
+result's [`as_json`](generated_modules.md#anatomy) — so a registration's `cast:`
+has to accept what its own `serialize:` writes, and a scalar that sends an object
+while accepting a string can't have both. That law, and where it is checked, is
+[below](#a-cast-must-accept-what-its-own-serialize-writes). The same asymmetry
+decides the [`:fake` pin](testing.md#pins): a pin stands in for a *result*, so pin
+what the server **sends**.
 
 Any of this can also be flatly wrong: the *format* a `Money` string has to match
-lives in the server's `coerce_input`, which no schema carries, so nothing before a
-real request says whether the server wants `"12.50"`, `"12.50 USD"` or the object.
-[Send one for real](#what-no-check-can-see).
+lives in the server's `coerce_input`, which no schema carries, so nothing
+`generate` reads says whether the server wants `"12.50"`, `"12.50 USD"` or the
+object — [check it against the schema
+class](#checking-the-half-no-schema-carries), or send one for real.
 
 ## Overriding one field
 
@@ -276,9 +308,10 @@ server writing a non-integer where the spec says integer, so it is refused.
 | `ID` | any JSON string | a number or `true` — **refused with a hint**: the server didn't quote it |
 | `Boolean` | `true`, `false` | `"true"`, `1`, `0` |
 | `Date` | ISO-8601: `"2024-01-01"`, `"20240101"`, and a full timestamp (truncated) | any other spelling, an epoch integer |
-| `DateTime`/`Time` (registered as `Time`) | RFC 3339 with `Z` or an offset, with or without fractional seconds, seconds optional; also a bare date and `Time.parse`'s looser forms | an epoch integer, an unparseable string |
+| `DateTime`/`Time` (registered as `Time`) | ISO 8601 as `Time.iso8601` reads it: `Z` or an offset, with or without fractional seconds | a bare date, seconds omitted, basic format (`"20240115T102030Z"`), `Time.parse`'s looser forms, an epoch integer |
 | `BigInt` | the decimal string graphql-ruby writes, past 2⁵³ included; also a JSON integer | `1.5`, `"1.5"`, a non-numeric string, `true` |
 | an enum | a declared value, as a string | an undeclared value, a non-string |
+| a scalar registered as `Integer`, `Float`, `String` or `T::Boolean` | that Ruby type's rule, *leniently* — a decimal string reads as an `Integer` | what the rule refuses, naming your scalar |
 | `JSON`, or unregistered | anything — `T.untyped`, straight through | nothing |
 
 A refusal is a [`GraphWeaver::CastError`](errors.md) naming the field and the
@@ -297,14 +330,14 @@ sig is `.checked(:never)`).
 
 | scalar | kwarg is typed | also accepts, at runtime | on the wire |
 |---|---|---|---|
-| `Int` | `Integer` | a decimal string, a whole `Float` | the integer |
-| `Float` | `Float` | a decimal string, an `Integer` | the float |
+| `Int` | `Integer` | a decimal string, a whole real `Numeric` — `2.0`, `BigDecimal("2")` | the integer |
+| `Float` | `Float` | a decimal string, a real `Numeric` — an `Integer`, a `BigDecimal`, a `Rational` | the float |
 | `String` | `String` | nothing | the string |
 | `ID` | `String` | an `Integer` — `execute(id: user.id)` | the string |
 | `Boolean` | `true`/`false` | nothing | the boolean |
 | `Date` | `Date` | an ISO-8601 string | `"2024-01-15"` |
-| `Time` | `Time` | a string `Time.parse` takes, a `DateTime`, `Time.zone.now` | ISO 8601, with microseconds when the value carries a fraction |
-| `BigInt` | `Integer` | a decimal string | the decimal string, which is what the server writes |
+| `Time` | `Time` | an ISO 8601 string, a `DateTime`, `Time.zone.now` | ISO 8601, with microseconds when the value carries a fraction |
+| `BigInt` | `Integer` | a decimal string, a whole real `Numeric` | the decimal string, which is what the server writes |
 | an enum | the member **or** its wire value | — | the wire value |
 | an input object | the struct **or** a Hash | — | the wire hash |
 | a registered custom scalar | its Ruby type | whatever its cast takes | what its serialize writes |
@@ -321,6 +354,12 @@ no string**, because every rule for reading `"0"`, `"off"`, `"no"` is somebody's
 convention. **A `Date` and a `Time` are not each other**, as above; what *is*
 accepted for a `Time` is anything that already is one.
 
+A **real `Numeric`** is the number it prints as, so a `BigDecimal` off a decimal
+column needs no conversion at the call site: it reaches a `Float` through `to_f`,
+at Float's own precision, and an `Int` only when the value is whole —
+`BigDecimal("2")` is `2` and `BigDecimal("2.5")` is refused, exactly as `2.5` is.
+`Complex` is the one `Numeric` that is not real, and no number rule takes it.
+
 Anything the table refuses raises `GraphWeaver::InputError` naming the variable,
 the operation and the value — `$count of Compute: expected an Int, got "lots"` —
 which is the same [422 rescue point](errors.md) as a bad input-object field. The
@@ -354,7 +393,7 @@ short-circuits — so a coercer written like the examples above raises
 `NoMethodError` on nil. Guard it, or `:in_process` will show it to you as a
 `ServerError`.
 
-## What no check can see
+## Checking the half no schema carries
 
 A custom scalar has two definitions that have to agree: the server's
 `coerce_input`/`coerce_result`, and your `register_scalar`. **No schema carries the
@@ -372,22 +411,56 @@ No `CastError`, no warning — just totals quietly wrong past the seventh
 significant figure, which is the precision a string-valued `Decimal` exists to
 protect.
 
-The check is a request that runs the real coercers: one `graphql: :in_process`
-example per registered scalar, round-tripping a value through the schema class.
+**Where the server runs in-process, both halves are callable, and that is the
+check.** One line, for every scalar at once:
 
 ```ruby
-it "round-trips a Money through the real server", graphql: :in_process do
-  price = Money.from_amount(BigDecimal("12.50"), "EUR")
-  expect(EchoPriceQuery.execute!(price:).echo_price).to eq price
+it "agrees with the server about every scalar" do
+  GraphWeaver::Testing.check_scalars!(Catalog::Schema)
 end
 ```
 
-Four lines, and it fails the moment either side moves. **`graphql: :fake` cannot
-stand in for it**: a fake fabricates from your *client* registration alone, so it
-hands back a value the real server would never send and accepts one the real
-server would reject. It is shape-correct, never rule-correct. A
-[cassette](cassettes.md) recorded against `:in_process` carries the rules to a
-suite that can't boot the schema class.
+Per scalar the schema declares and your app registered, it fabricates a value the
+way [`:fake`](testing.md) does, casts it, sends it back out through `serialize:`,
+through the server's `coerce_input` and `coerce_result`, and back through `cast:`.
+It raises naming every scalar that disagreed and which way:
+
+```
+2 scalar(s) disagree with Catalog::Schema:
+  Money: the server refused "12.5", the wire form serialize: writes (expected "12.50 USD")
+  Decimal: round-trips lossily — sent 123456789.123456789, got back 123456789.1234567
+```
+
+The fabricated value is all it has to work with, so pin the one that matters:
+`config.overrides = { "Decimal" => "123456789.123456789" }` is how the precision
+case gets exercised at all — two decimal places always survive a Float. Pass the
+schema **class**; a dump's scalars pass values through, so against one this checks
+only that a registration's `cast:` accepts what its own `serialize:` writes, which
+is a different question (see below).
+
+For a **remote** server the limit stands: nothing before a real request can say.
+Send one — a `graphql: :in_process` example against the same schema class if your
+app has one, otherwise a [cassette](cassettes.md) recorded against the real
+endpoint, which carries the server's rules to a suite that can't reach it.
+**`graphql: :fake` cannot stand in for either**: a fake fabricates from your
+*client* registration alone, so it hands back a value the real server would never
+send and accepts one the real server would reject. It is shape-correct, never
+rule-correct.
+
+### A cast must accept what its own serialize writes
+
+One `serialize:` serves both directions — the outbound variable and a result's
+[`as_json`](generated_modules.md#anatomy) — so a registration has a law to keep:
+**its `cast:` must accept what its `serialize:` writes.** That is what makes
+`from_h(JSON.parse(x.to_json)) == x` hold, and it is the innermost leg of
+`check_scalars!` above, which is where it is checked.
+
+A server whose `coerce_result` writes one shape and whose `coerce_input` accepts
+another can't be served by one `serialize:`, so don't try: write the **result**
+form, the one `cast:` reads, and have the server's `coerce_input` accept that too.
+If it can't, the asymmetry is the server's to fix — a second registration keyword
+for the result form would put a knob where a law belongs, and `as_json` would
+still have no way to choose between them.
 
 ## Enums: map onto your own T::Enum
 
@@ -432,12 +505,65 @@ Two safety properties do the real work:
 - **`fallback:` for forward-compat**: `fallback: PetKind::Unknown` makes *casting*
   absorb wire values the server added after you generated, so responses keep
   flowing instead of raising. Inputs stay strict either way: a typo'd input is your
-  bug, not drift. A union or interface absorbs the same drift with no registration
-  — a member added upstream lands in the catch-all `Other` its dispatch always
-  carries ([generated modules](generated_modules.md#abstract-types)).
+  bug, not drift. You don't need an enum of your own for that:
+  `GraphWeaver.register_enum("Species", fallback: true)` gives the *generated* enum
+  the same forward-compat, [below](#values-the-server-hasnt-told-you-about-yet).
 
 The translation tables are emitted into the generated source (`SPECIES_FROM_WIRE` /
 `SPECIES_TO_WIRE`) — reviewable in the diff, no runtime registry.
 
+### Values the server hasn't told you about yet
+
+A server adding an enum value is a deploy you weren't part of, and by default the
+next response carrying it raises. `fallback: true` says take it anyway:
+
+```ruby
+GraphWeaver.register_enum("Species", fallback: true)
+```
+
+The generated `Species` gains one member, `Other`, and every wire value the schema
+doesn't declare casts to it — the leniency a union or interface already has for
+free, where a member added upstream lands in the catch-all `Other` its dispatch
+always carries ([generated modules](generated_modules.md#abstract-types)).
+
+```ruby
+pet.species                    # => GraphQLTypes::Species::Other, for "AXOLOTL"
+```
+
+Three things follow from that, and they are the whole rule:
+
+- **`Other` doesn't carry the value it absorbed.** A `T::Enum` member is a
+  singleton, so there is nowhere to put it; the cast writes one debug line
+  (`GraphQLTypes::Species absorbed "AXOLOTL" into Other`) and that is the record
+  — so a presenter humanising the server's spelling can't, and falls back to a
+  label of its own.
+- **Inputs stay strict.** No wire value means `Other`, so a variable carrying it
+  is refused rather than sent. Everything else is unchanged: a typo'd input is
+  your bug, not drift.
+- **A schema that already declares `OTHER` keeps it.** The declared value stays
+  `Other`, and the fallback member is `Other2` — the same rule a union's
+  catch-all struct follows when a member is already named `Other`.
+
+It rides along with `alias:` on the one registration, and like every registration
+it belongs to one graph.
+
+### Two spellings, one value
+
+A schema mid-rename declares both `LEGACY_MODE` and `legacy_mode` so old clients
+keep working. `alias:` says they are one value — both spellings cast, and the
+target is what goes back on the wire:
+
+```ruby
+GraphWeaver.register_enum("Status", alias: { "legacy_mode" => "LEGACY_MODE" })
+```
+
+That is the whole registration when there is no enum of your own to map onto; it
+rides along with one when there is, where it also settles which spelling a
+member serializes to — inference is case/underscore-insensitive, so a rename
+pair lands on a single member. Either way generation refuses rather than pick:
+two values that name one Ruby constant, or that map onto one member, are
+ambiguous until you say. Delete the alias when the server drops the old
+spelling.
+
 Decorating a generated *struct* with your own methods is the sibling API —
 `extend_type`, in [generated modules](generated_modules.md#type-helpers).

data/docs/testing.md

@@ -64,6 +64,13 @@ client for anything, so a
 [client-side `InputError`](errors.md#what-an-inputerror-says-without-reading-english)
 raises the same way under every tag and under none.)
 
+A fake also can't reach a **custom scalar's** rules, for the same reason: it
+fabricates from your own [registration](scalars.md), so the round trip agrees
+with itself whatever the server thinks. Where the server is a schema class,
+`GraphWeaver::Testing.check_scalars!(Catalog::Schema)` runs both halves against
+each other and names every scalar that disagrees
+([how](scalars.md#checking-the-half-no-schema-carries)).
+
 Everything here is a *client* — the one interface queries run through (the
 contract is in [transports](transports.md)) — so fakes, the router, failures and
 cassettes work outside rspec too (`require "graph_weaver/testing"`, never from
@@ -403,8 +410,10 @@ middleware wrote, the headers it sent, the retry it does on a 500, and that
 `from_h` reads real JSON off a socket. What it can't tell you is whether your
 `cast:` agrees with the real server: the fabricated bytes are written to match
 your own [scalar registrations](scalars.md), so the round trip agrees with
-itself. Put the live schema class behind the wire for that, or pin a real
-response with a [cassette](cassettes.md).
+itself. Put the live schema class behind the wire for that —
+[`check_scalars!`](scalars.md#checking-the-half-no-schema-carries) asks the same
+question of one directly — or pin a real response with a
+[cassette](cassettes.md).
 
 `GraphWeaver::Testing::Endpoint` is an ordinary Rack app wrapping anything that
 satisfies the [client contract](transports.md), so mount it yourself
@@ -414,7 +423,9 @@ time** — answering one means setting the client's context for the length of th
 dispatch, so the identity a request asked for is the identity it gets, whatever
 else is in flight. The lock is the client's own, so it holds however the endpoint
 is mounted. A `context:` hash is served **concurrently**: nothing writes it, so
-there is nothing to serialize.
+there is nothing to serialize. Either way a query reads its context once, so
+every subgraph it hops through runs as the identity it started with, even if
+the router's context is reassigned while it is in flight.
 
 ### Making the served endpoint fail
 
@@ -635,6 +646,16 @@ the fly? The client in play exposes it as `GraphWeaver.client.schema`, and
 `GraphWeaver::Testing.config.schema` reads back what `config.schema =` set,
 falling back to the committed dump.
 
+A query built that way is worth an assertion of its own:
+
+```ruby
+expect(GraphWeaver.client.check_query(source)).to be_empty
+```
+
+[`check_query`](getting_started.md#5-verify-in-ci) answers with the
+errors rather than a boolean, so a failure prints what is wrong and where; a
+predicate would only say the query isn't valid.
+
 ## Test-only generated modules
 
 They don't have to live in `app/` — `generated_paths` is an appendable list, so a

data/docs/upgrading.md

@@ -1,11 +1,12 @@
 # Upgrading
 
 [Regenerate](#regenerate-on-every-upgrade) whichever version you're on, then read
-the one section that is yours: from [0.7.1](#upgrading-from-071), from
-[0.7.0](#upgrading-from-070) or from [0.6.1](#upgrading-from-061). Coming from
-0.6.0 or older, the path is that version's own upgrade notes — read them at the
-tag they shipped under (`git show v0.7.1:docs/upgrading.md`), then this page from
-0.6.1 down.
+the one section that is yours: from [0.7.4](#upgrading-from-074), from
+[0.7.3](#upgrading-from-073), from
+[0.7.1](#upgrading-from-071), from [0.7.0](#upgrading-from-070) or from
+[0.6.1](#upgrading-from-061). Coming from 0.6.0 or older, the path is that
+version's own upgrade notes — read them at the tag they shipped under
+(`git show v0.7.1:docs/upgrading.md`), then this page from 0.6.1 down.
 
 ## Regenerate on every upgrade
 
@@ -23,6 +24,51 @@ That's the reminder working, not a false alarm. Generation is deterministic, so
 the diff is exactly what the new version emits differently and nothing else —
 worth reading rather than rubber-stamping.
 
+## Upgrading from 0.7.4
+
+Read the left column and skip what isn't yours; the
+[changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| spread a shared fragment as a whole field — `grep -rln '{ *\.\.\.[A-Za-z]* *}' app/graphql/queries` | on an object type it now [hoists](generated_modules.md#a-shared-fragment-is-one-type) into `GraphQLTypes` under the fragment's name, as it already did on a union. **App code naming the struct it used to produce (`PetQuery::Result::Pet`) moves to `GraphQLTypes::PetFields`** — one type instead of one per query, so a `T.type_alias { T.any(…) }` written to paper over that goes away. Regenerating and running `srb tc` finds every site |
+| register an `abstract!` mixin — `grep -rn 'extend_type' app config lib`, then check which of those modules call `abstract!` | **generation refuses** where a query doesn't select everything the mixin declares, instead of leaving it for your `srb tc`. The message names the struct, the members and the fixes: select them in that query, or select the type through one shared fragment so a single hoisted struct answers for every query |
+| keep a hand-maintained schema dump on a graph that also names a `client` — `rake graph_weaver:graphs` lists both per graph | `rake graph_weaver:schema:refresh` **rewrites that dump from the client** where it used to refuse and exit 1. If the file is the source of truth, don't run `refresh` for that graph, or drop the client from it |
+| call `Codegen#used_union_names` | it is `used_fragment_names` — the set it reports now includes hoisted object fragments |
+
+Then regenerate, and the gate:
+
+```sh
+rake graph_weaver:generate
+rake graph_weaver:verify
+```
+
+## Upgrading from 0.7.3
+
+A patch release. One change can reach an app that never touched it — how a
+timestamp is read off the wire — one more reaches an app that maps an enum onto
+its own, and the rest is in the regenerate. Read the left column and skip what
+isn't yours; the [changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| register a timestamp scalar — `grep -rn 'register_scalar.*Time' app config lib`, which finds `Time` and `DateTime` alike | it reads the wire with `Time.iso8601` rather than `Time.parse`, so a spelling graphql-ruby's `coerce_result` never writes is refused: a bare date, seconds omitted, basic format (`"20240115T102030Z"`), a space and a zone name, `"Jan 15 2024 10:20"`. Same for a variable going out. **A server that writes one of those starts failing the cast** — `cast: :parse` keeps the tolerant reader: `register_scalar("DateTime", Time, cast: :parse)` |
+| have `DateTime` or `ISO8601DateTime` in your schema and register neither | same change: the gem registers both as `Time`, so the row above is yours without a line of your own |
+| map an enum onto your own `T::Enum` — `grep -rn 'register_enum' app config lib` — where the schema declares one value under two spellings (`LEGACY_MODE` beside `legacy_mode`) | inference is case/underscore-insensitive, so both landed on one member and the wire table silently sent whichever sorted last: the deprecated one. **Generation refuses now**, naming the pair — `alias: { "legacy_mode" => "LEGACY_MODE" }` says which spelling goes out |
+
+Then regenerate, and the gate:
+
+```sh
+# the timestamp cast is emitted, the input-struct FIELDS table grew a column,
+# and a graph with a block-form extend_type gains a type_helpers.rbi — commit
+# it with the rest
+rake graph_weaver:generate
+
+# red while any checked-in file is still what 0.7.3 wrote; 0.7.3's input
+# structs raise `ArgumentError: missing keyword: :type` at load until then
+rake graph_weaver:verify
+```
+
 ## Upgrading from 0.7.1
 
 A patch release, and one change with a shape: a generated module no longer

data/examples/github/generated/star_mutation.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.3 — do not edit.
+# Generated by GraphWeaver 0.7.4 — do not edit.
 
 module StarMutation
   extend T::Sig
@@ -49,6 +49,14 @@ module StarMutation
         rescue StandardError => e
           raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
         end
+
+        sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+        def as_json(*_options)
+          {
+            "stargazerCount" => stargazer_count,
+            "viewerHasStarred" => viewer_has_starred,
+          }
+        end
       end
 
       const :starrable, T.nilable(Starrable)
@@ -63,6 +71,13 @@ module StarMutation
       rescue StandardError => e
         raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
       end
+
+      sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def as_json(*_options)
+        {
+          "starrable" => starrable&.then { |v1| v1.as_json },
+        }
+      end
     end
 
     const :add_star, T.nilable(AddStar)
@@ -77,6 +92,13 @@ module StarMutation
     rescue StandardError => e
       raise GraphWeaver::CastError.new(struct: self, message: GraphWeaver::Hints.cast_message(self, data, e))
     end
+
+    sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def as_json(*_options)
+      {
+        "addStar" => add_star&.then { |v1| v1.as_json },
+      }
+    end
   end
 
   # client — see GraphWeaver::QueryModule
@@ -92,7 +114,7 @@ module StarMutation
   sig { params(id: String, client: T.untyped).returns(GraphWeaver::Response[Result]).checked(:never) }
   def self.execute(id:, client: nil)
     variables = {
-      "id" => GraphWeaver::Coerce.variable("id", OPERATION_NAME, id) { |v| GraphWeaver::Coerce.id(v) },
+      "id" => GraphWeaver::Coerce.variable("id", OPERATION_NAME, id) { |v| GraphWeaver::Coerce.id(v, "ID") },
     }
 
     from_response(dispatch(variables, client:))