graph_weaver 0.7.2 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cb0372c9f8505bec490fbb13344cbd586da68cb4932cbce0f86de2467d0eaf4
-  data.tar.gz: 6bc17449eea717c8cb145c159a2395f61f484a2f585c016ee31521f979f1a6d6
+  metadata.gz: f631eac2f0c9bbd78b50cfe1b7a0178911a8939cc697d57328bc63b3b60cd0d7
+  data.tar.gz: 771837c86ab744d47de6b1f58e990575ee7618d9cb362e871614f6aeebcded18
 SHA512:
-  metadata.gz: 63670eee3838644725166822028b4816164450c853e24d74dd6ce47212e4e18c2bda7309d5549f8830e709d547e73678425ae9984d960a5367b97f5102613f5c
-  data.tar.gz: d7b30350095090f9c69e7b5316137ac5324b60965a242ffe5c9be4a893812a48351a172bde26f36000797d830eb01c3e15ea0352eea8ecda9ac775f55b12ac82
+  metadata.gz: 8f24e3485d8ff839de3a9fd626b2c0038c0617c322b6249742aa90eae3552073d3cbf3335de430364072bfa990304689a7e9ad3db652ae527d46ac711573a276
+  data.tar.gz: a484029fbbdd141af8be0586d8a830e2439f13fdbbc1b9f4826840f289af3e000a81457749657e5573cd67c4ae2017aa2929bfb34a300e9777669b9265c22eb5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.2)
+    graph_weaver (0.7.4)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -195,16 +195,16 @@ GEM
     rubydex (0.2.7-x86_64-darwin)
     rubydex (0.2.7-x86_64-linux)
     securerandom (0.4.1)
-    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)
+    simplecov (1.3.0)
+    sorbet (0.6.13498)
+      sorbet-static (= 0.6.13498)
+    sorbet-runtime (0.6.13498)
+    sorbet-static (0.6.13498-aarch64-linux)
+    sorbet-static (0.6.13498-universal-darwin)
+    sorbet-static (0.6.13498-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13498)
+      sorbet (= 0.6.13498)
+      sorbet-runtime (= 0.6.13498)
     spoom (1.8.3)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
@@ -299,7 +299,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.7.2)
+  graph_weaver (0.7.4)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
@@ -350,13 +350,13 @@ CHECKSUMS
   rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
   rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
-  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
+  simplecov (1.3.0) sha256=d9886307863c1ead47657dcbed869bfffd82318808b09014d8f0ff77dcfe7492
+  sorbet (0.6.13498) sha256=cb5279f6a9dbfc8d526bc9fb71d05020afb8043c40708e4aff2244ba329ce224
+  sorbet-runtime (0.6.13498) sha256=2da4627f9341a1fc6e4148cc891989b7b108106c206c46ca69940e10a21e9133
+  sorbet-static (0.6.13498-aarch64-linux) sha256=cbee732c49379d38029f295b45edaeb5757ab180d308d8383dc79f03fd4991be
+  sorbet-static (0.6.13498-universal-darwin) sha256=4cc97aa0da3dd175b8278e1617954d6dd9ba1f5aeb62981f21616b9ec791fb75
+  sorbet-static (0.6.13498-x86_64-linux) sha256=75d02e8af7d6c1081d4693e2ebefe679760327f1304377519970784faf9f913d
+  sorbet-static-and-runtime (0.6.13498) sha256=5f5686869dceae893b4171b05e3db159fe12f1aadf04aa8c2bf9dfa3edc0d902
   spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
   tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73

data/docs/federation.md

@@ -690,8 +690,9 @@ the rest.
 
 The table is also what a good error message wants. When the schema dump is a
 composed supergraph, `rake graph_weaver:queries:check` brands each validation error
-with the subgraphs behind the type it names, and `check_queries` carries the same
-list as a `"subgraphs"` key:
+with the subgraphs behind the type it names, and `check_queries` — or
+`client.check_query(source)`, for a client built from that dump — carries the
+same list as a `"subgraphs"` key:
 
 ```
 app/graphql/queries/product.graphql

data/docs/generated_modules.md

@@ -308,6 +308,19 @@ camelizes to nothing — `_` and `__` are both legal GraphQL — is refused at
 generation: there is no constant to name it. Map the enum onto one of yours
 instead.
 
+Two values that camelize to the *same* constant are refused for the same reason.
+A schema mid-rename declares exactly that — `LEGACY_MODE` alongside
+`legacy_mode`, so old clients keep working — and if they are one value, say
+which spelling goes on the wire:
+
+```ruby
+GraphWeaver.register_enum("Status", alias: { "legacy_mode" => "LEGACY_MODE" })
+```
+
+Both spellings then cast to `Status::LegacyMode`, only the target gets a
+constant, and a variable sends the target — see
+[scalars.md](scalars.md#two-spellings-one-value).
+
 `register_enum` replaces the generated `T::Enum` with your own app enum — see
 [scalars.md](scalars.md#enums-map-onto-your-own-tenum). Dynamic `parse` emits the
 enums into the query module itself; there's no cross-query set to share against,
@@ -470,16 +483,23 @@ The name is where the block is written and what it extends:
 `GraphWeaver::TypeHelpers::Billing::Pet` inside `GraphWeaver.graph :billing`.
 Generated code spells it, so it depends on your source and nothing else — two
 graphs can extend the same type name, and the name a `generate` bakes in is the
-one a boot creates.
-
-**Neither form is statically checked as written**, for the same reason: `srb tc`
-checks a mixin's method bodies in the module's own scope, not the including
-struct's, so a helper reading a wire field (`name`, `birthday`) fails with
-"method does not exist on the module" — and the block form has no source on disk
-for `srb tc` to read at all. A *named* module can carry real sigs, though, by
+one a boot creates. The module is minted at registration, so no file declares
+it; generation writes a `type_helpers.rbi` beside the modules that does, which
+is what lets your `srb tc` resolve the `include`. Ruby never loads an `.rbi`, so
+dropping the registration still fails loudly at require rather than quietly
+handing the struct an empty module.
+
+**Neither form has its method bodies statically checked**, for the same reason:
+`srb tc` checks a mixin's method bodies in the module's own scope, not the
+including struct's, so a helper reading a wire field (`name`, `birthday`) fails
+with "method does not exist on the module" — and the block form has no source on
+disk for `srb tc` to read at all. A *named* module can carry real sigs, though, by
 declaring the fields it leans on: `abstract!` plus a
 `sig { abstract.returns(String) }; def name; end` is how a mixin says "whatever
-includes me has these", and the struct's `const`s satisfy them.
+includes me has these", and the struct's `const`s satisfy them — generation
+declares the override Sorbet demands there (`const :name, String, override:
+true`, and `sig { override.returns(...) }` on an `alias:` accessor), which is
+the one thing you couldn't add by hand: a `const` has no sig to put it in.
 `T.unsafe(self).name` also silences it, at the cost of checking nothing. Either
 beats `# typed: false` for a helper you want checked.
 
@@ -534,6 +554,26 @@ excuses a field the query didn't select, not a segment the schema doesn't have:
 typo or a wire-cased name (`findPets` for `find_pets`) still raises, since no
 selection could ever satisfy it.
 
+**One call does both halves.** `alias:` and a block are independent parts of the
+same registration — the accessor is emitted into the struct body, the block
+becomes a mixin the struct includes — so a block method can call an accessor the
+same call declared. Inside the block the alias is spelled `alias_field`, which
+is the same keyword said next to the methods that use it: same paths, same
+errors, same accessor. Two positions, one thing.
+
+```ruby
+GraphWeaver.extend_type("Widget") do
+  alias_field :tag, "meta.tag"     # or alias_field "meta.tag" — accessor named `tag`
+  def shout = tag&.upcase
+end
+```
+
+The verb is `alias_field` because the block can't spell `alias` itself: it is a
+Ruby keyword, and the block is `module_eval`'d Ruby, so writing it there would
+define a method alias rather than a projection. A block says one alias per line
+and nothing else — the compact `{ }`/`[ ]` forms and `optional: true` stay on
+the keyword, since leniency describes the registration rather than one accessor.
+
 For anything beyond a passthrough projection — real logic, still typed — reopen
 the generated struct in your own file and add sig'd methods; Sorbet merges the
 bodies. Every form above, and every error it raises, is a named example in
@@ -602,6 +642,7 @@ app/graphql/
   generated/
     types.rb         # manifest: requires + forward declarations, in load order
     types/           # one file per shared type
+    type_helpers.rbi # only with a block-form extend_type — declares its module
     *_query.rb       # one module per query — generated, checked in, never edited
     *_mutation.rb    # ...and per mutation
 ```
@@ -678,8 +719,9 @@ spot a *schema* change for you — `schema:diff`, `schema:refresh`, `queries:che
 ### Loading what it wrote
 
 In Rails, loading is automatic — the Railtie requires every generated file at
-boot from a `to_prepare` block, after your initializers and after any
-registrations of your own in one. Elsewhere it's explicit, factory_bot-style:
+the end of boot, after your initializers and after any registrations of your own
+in a `to_prepare` block, and again after each development reload. Elsewhere it's
+explicit, factory_bot-style:
 `GraphWeaver.load_generated!` requires every file under `generated_paths`.
 
 **Outside Rails, four things have to agree**, and nothing wires them together for

data/docs/getting_started.md

@@ -99,8 +99,9 @@ What it wrote:
 
 Rake needs no wiring: in Rails the `graph_weaver:*` tasks register themselves and
 depend on `:environment`, so your initializer runs first. The generated modules
-load at boot from a `to_prepare` block, so a helper or enum you registered is
-already in place when the file that names it loads.
+load at the end of boot, after your initializers and after any `to_prepare`
+block of yours, so a helper or enum you registered is already in place when the
+file that names it loads.
 
 All of that describes **one** schema, which is the usual case; an app with a
 second one declares each as a graph ([more than one
@@ -299,6 +300,21 @@ it into a spec, a Slack ping, an issue. Pass it `schema:` a *loaded* schema (not
 a path) and nothing touches the network, which is how you check your queries
 against a proposed subgraph before it's live.
 
+A query you have as a **string** rather than on disk asks the same client the
+same question, and gets the same entries back:
+
+```ruby
+client.check_query('query($id: ID!) { person(id: $id) { nmae } }')
+# => [{ "message" => "Field 'nmae' doesn't exist on type 'Person' (Did you mean `name`?)",
+#       "line" => 1, "column" => 37 }]
+```
+
+Empty means it validates. It checks against that client's own schema — the one
+`execute` would run against — so nothing re-introspects, and an unparseable
+source comes back as an entry rather than an exception. Shared fragments are
+inlined from `fragments:`, defaulting to `GraphWeaver.fragments_paths` the way
+`parse` does.
+
 ### The selections nothing reads
 
 `rake graph_weaver:unused` asks the one question the others can't: not "is the

data/docs/i18n.md

@@ -121,10 +121,10 @@ I18n.t("graph_weaver.input.#{error.kind}", field: error.path.join("."), **error.
 Arrays stay arrays: `details[:members]` is `["CAT", "DOG"]`, so join it where you
 know the language — `members: e.details[:members].to_sentence`.
 
-`details[:type]` is the **GraphQL** name for the type — `Int`, `Money` — so a
-sentence built from it still says "Int" in the middle of the French. Translate
-the name yourself under a key of your own and pass it *after* the splat, which
-wins: `I18n.t(key, **e.details, type: I18n.t("types.#{e.details[:type]}"))`.
+`details[:type]` is the **GraphQL** spelling of the type — a name (`Int`,
+`Money`) or a whole signature (`[JSON!]`, `[Float!]!`) — so a sentence built
+from it still says "Int" in the middle of the French. Translate the spelling
+yourself under a key of your own and pass it *after* the splat, which wins: `I18n.t(key, **e.details, type: I18n.t("types.#{e.details[:type]}"))`.
 
 `@oneOf` violations are `:refused`, except exactly one field explicitly null,
 which is `:missing` on that field — a form gets the one slot to highlight. The

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 0.123456789123456789e9, got back 0.1234567891234567e9
+```
+
+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
 
@@ -439,5 +512,23 @@ Two safety properties do the real work:
 The translation tables are emitted into the generated source (`SPECIES_FROM_WIRE` /
 `SPECIES_TO_WIRE`) — reviewable in the diff, no runtime registry.
 
+### 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
@@ -635,6 +644,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,11 @@
 # 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.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 +23,32 @@ 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.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.2 — 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:))