graph_weaver 0.5.0 → 0.6.0

data/docs/getting_started.md

@@ -1,8 +1,8 @@
 # Getting started: the production path (Rails)
 
-The setup that ships: queries live as `.graphql` files, generation writes
-`# typed: strict` Ruby you check in, and CI fails when anything drifts.
-In Rails one generator does the setup. (Exploring an API from a console
+The setup that ships, end to end: queries live as `.graphql` files, generation
+writes `# typed: strict` Ruby you check in, and CI fails when anything drifts.
+Follow it once when you add the gem to an app. (Exploring an API from a console
 instead? Start with [dynamic mode](real_world.md) — no build step.)
 
 Rails is assumed below; the [non-Rails note](#not-rails) at the bottom
@@ -24,6 +24,7 @@ rails g graph_weaver:install https://api.example.com/graphql
 ```
       create  config/initializers/graph_weaver.rb
       create  app/graphql/queries/.keep
+      create  app/graphql/fragments/.keep
       create  app/graphql/generated/.keep
       create  graphql.config.yml
   introspect  app/graphql/schema.json from https://api.example.com/graphql
@@ -41,7 +42,7 @@ initializer that fits:
 
 | flag | |
 |---|---|
-| `--auth` | name of the ENV var holding the auth token — default `GRAPHWEAVER_AUTH`. Url only. Name a different one and the initializer follows, but `schema:refresh`/`schema:diff` still read `GRAPHWEAVER_AUTH` — set both |
+| `--auth` | name of the ENV var holding the auth token — default `GRAPHWEAVER_AUTH`. Url only. The name is recorded into the dump, so `schema:refresh`/`schema:diff`/`queries:check` read the same one the initializer does |
 | `--no-schema` | skip writing the dump; `rake graph_weaver:schema:refresh URL=...` does it later |
 
 Re-running is safe — every file goes through the usual Rails conflict
@@ -84,13 +85,15 @@ What it wrote:
   RubyMine schema autocomplete, hover docs, and validation as you type in
   `.graphql` files — no JS project, no `npm install`. Details and the honest
   limits in [editors](editors.md).
-- **`app/graphql/queries/`, `app/graphql/generated/`.** Where you write
-  queries and where generation writes Ruby.
+- **`app/graphql/queries/`, `app/graphql/fragments/`, `app/graphql/generated/`.**
+  Where you write queries, where shared fragments live, and where generation
+  writes Ruby.
 
 Rake needs no wiring either: in Rails the `graph_weaver:*` tasks register
 themselves (a Railtie) and depend on `:environment`, so your initializer —
-and its registrations — runs first. The generated modules load at boot the
-same way, after `config/initializers`.
+and its registrations — runs first. The generated modules load at boot from
+a `to_prepare` block, so a helper or enum you registered in one is already
+in place when the file that names it loads.
 
 ### Your app's own schema, in-process
 
@@ -122,11 +125,16 @@ client = GraphWeaver.new(MyApp::Schema, context: { current_user: })
 PetQuery.execute!(client:, id: "1").pet.owner   # => the context's user
 ```
 
+Each query gets its own copy of that hash, so a resolver writing
+`context[:loader] =` can't hand what it wrote to the next request — which
+matters because one in-process client is normally the whole app's.
+
 **Keep the dump in step with the schema.** Codegen reads the committed
 dump at `GraphWeaver.schema_path`, never the live class — that's what
 makes `rake graph_weaver:verify` a deterministic CI check. The generator
 writes the first dump; after that it's an artifact derived from code in
-your own repo, so rebuild it with graphql-ruby's own rake task:
+your own repo, so rebuild it with graphql-ruby's own rake task, ahead of
+`verify` in CI:
 
 ```ruby
 # lib/tasks/graphql.rake
@@ -140,13 +148,16 @@ rake graphql:schema:json     # rewrites app/graphql/schema.json
 rake graph_weaver:generate
 ```
 
-Run the dump step ahead of `rake graph_weaver:verify` in CI — that check
-compares committed Ruby against the committed dump, so a stale dump makes
-it fail on a query that is fine. `rake graph_weaver:queries:check` is
-unaffected: when `GraphWeaver.client` runs in-process it validates
-against the live class, not the dump. (`graph_weaver:schema:diff` and
-`:refresh` are for servers you *don't* own; a dump taken from a schema
-class records no url, and they say so.)
+A stale dump makes `verify` fail on a query that is fine. `queries:check` is
+unaffected: running in-process it validates against the live class, not the
+dump. (`schema:diff` and `:refresh` are for servers you *don't* own; a dump
+taken from a schema class records no url, and they say so.)
+
+**Scaffolding the app too?** On a `rails new --skip-active-record`,
+`rails g graphql:install` writes `config.active_record.query_log_tags` lines
+into `config/application.rb` that an app without ActiveRecord can't boot
+with — a graphql-ruby bug. Run it as
+`rails g graphql:install --skip-query-logs`, or delete the lines it wrote.
 
 ### A schema dump you already have
 
@@ -174,19 +185,28 @@ query($id: ID!) {
 rake graph_weaver:generate   # writes app/graphql/generated/person_query.rb
 ```
 
-Commit the schema dump and the generated files. Generated code is
-reviewed like any other code — and never edited by hand.
-
 ```ruby
 PersonQuery.execute!(id: "1").person&.name   # typed, via GraphWeaver.client
 ```
 
-### Autocomplete while you write the query
+Commit the schema dump and the generated files. Generated code is reviewed like
+any other code — and never edited by hand. The module name comes from the file
+name; the full set of naming rules is in
+[generated modules](generated_modules.md#naming).
 
 `graphql.config.yml` is already there, so VS Code and RubyMine validate the
 `.graphql` files as you type, with schema autocomplete and hover docs — see
 [editors](editors.md).
 
+**In development you don't type that command again.** While the server is
+running, a `.graphql` edit — or a refreshed schema dump — regenerates before
+the next request, the way a route or a locale change takes effect. A query that
+doesn't compile is logged with its file and position while the modules already
+loaded keep serving, so a file saved mid-edit doesn't take the server down.
+Development only, and `config.graph_weaver.watch = false` turns it off. The
+generated files are still what ships: commit them, and keep `rake
+graph_weaver:verify` in CI.
+
 ### Shared fragments
 
 Define reusable fragments once and spread them from any query:
@@ -205,29 +225,10 @@ Fragment files hold only fragments (no operations), and names are unique across
 them. Point elsewhere with `GraphWeaver.fragments_paths` (an appendable list,
 default `app/graphql/fragments`).
 
-### Shared unions
-
-When a shared fragment *is* the whole selection on a union field, its type is
-hoisted once into the shared `GraphQLTypes` module and every query that spreads
-it aliases the same type — so a `union` selected across many queries becomes one
-Ruby type family, and you write one exhaustive `case … when … T.absurd` that
-works everywhere:
-
-```graphql
-# app/graphql/fragments/feed_item.graphql
-fragment FeedItemFields on FeedItem {
-  __typename
-  ... on Post { title }
-  ... on Photo { url }
-}
-
-# any query
-query { feed { ...FeedItemFields } }   # feed : T::Array[FeedItemFields::Type]
-```
-
-There's no flag: hoisting triggers when the union field's selection is exactly
-that one spread. Mix in other fields, or shadow the fragment with a query-local
-one of the same name, and the union stays inlined in that query — see
+One payoff worth knowing about: when a shared fragment *is* the whole selection
+on a union field, its type is hoisted once into `GraphQLTypes` and every query
+that spreads it gets the same Ruby type — so one exhaustive `case … T.absurd`
+works everywhere. See
 [abstract types](generated_modules.md#abstract-types).
 
 ## 4. Test against fakes
@@ -241,47 +242,74 @@ require "graph_weaver/rspec"
 it "renders the empty state", graphql: :fake do … end   # or tag the describe
 ```
 
+The tag installs a seeded, schema-correct `FakeClient` for that example — no
+server, no stubs, and `rspec --seed 1234` reproduces the fake data along with
+test order. The schema it fabricates from is derived (the committed dump, or
+your client's), so there's nothing to configure. Tag `graphql: :in_process`
+instead and the same example runs against your real resolvers. Pinning values,
+simulating failures, and the federated `graphql: :router` are in
+[testing](testing.md).
+
 A fresh `rails g rspec:install` leaves the `spec/support` glob commented
 out in `spec/rails_helper.rb`, so uncomment it — or put the require in
 `rails_helper.rb` itself. Nothing warns you that a support file went
 unread.
 
-The tag installs a seeded, schema-correct `FakeClient` for that example —
-no server, no stubs, and `rspec --seed 1234` reproduces the fake data along
-with test order. The schema it fabricates from is derived (the committed
-dump, or your client's), so there's nothing to configure. Tag
-`graphql: :in_process` instead and the same example runs against your real
-resolvers; pin values with `overrides:`, simulate failures with `Failure.*`
-— see [testing](testing.md).
-
 ## 5. Verify in CI
 
-```sh
-rake graph_weaver:verify         # generated code fresh? fails on any drift
-rake graph_weaver:schema:diff    # server drifted? re-introspects and compares
-rake graph_weaver:queries:check  # did that drift break any of your queries?
+Four questions, four tasks — the last only on a federated graph:
+
+| ask | task | needs network |
+|---|---|---|
+| is the checked-in Ruby fresh? | `rake graph_weaver:verify` | no |
+| has the server's schema drifted from the dump? | `rake graph_weaver:schema:diff` | yes |
+| did that drift break any of my queries? | `rake graph_weaver:queries:check` | yes |
+| did a subgraph change without a recompose? | `rake graph_weaver:federation:diff` | no |
+
+`verify` compares the committed generated files against what the current
+schema + queries + registrations would produce, so it belongs in every CI
+build. `schema:diff` needs a dump with a recorded source url (introspected
+dumps have one) and `GRAPHWEAVER_AUTH` for private APIs — run it on a
+schedule and repair with `rake graph_weaver:schema:refresh`.
+`federation:diff` needs no network either, so it goes in the same PR run;
+see [federation](federation.md#has-the-supergraph-been-recomposed).
+
+`schema:diff` names what moved, breaking changes first — breaking meaning
+a query written against your dump stops validating, or stops casting:
+
 ```
+app/graphql/schema.json vs https://api.example.com/graphql: 8 changes, 5 breaking
+
+breaking:
+  AdoptionInput.nickname          String -> String!
+  Person.email                    removed
+  Person.pets                     [Pet!]! -> [Pet!]
+  Query.person(includeArchived:)  argument added: Boolean! — required
+  Species.CAT                     enum value removed
 
-Three different questions — four on a federated graph, where
-`rake graph_weaver:federation:diff` asks whether anyone changed a subgraph
-without recomposing the supergraph you committed. It needs no network
-either, so it belongs in the same PR run; see
-[federation](federation.md#has-the-supergraph-been-recomposed).
+other:
+  Person.birthday  deprecated: use bornOn
+  Pet.nickname     added: String
+  Species.BIRD     enum value added
 
-`graph_weaver:verify` compares the committed generated files against what the
-current schema + queries + registrations would produce. No network — run it in
-every CI build.
+app/graphql/schema.json is stale — the server's schema has drifted (rake graph_weaver:schema:refresh)
+```
 
-`graph_weaver:schema:diff` asks whether the *server* has moved since the
-dump was taken. It needs network, a dump with a recorded source url
-(introspected dumps have one), and `GRAPHWEAVER_AUTH` for private APIs;
-run it on a schedule and refresh with `rake graph_weaver:schema:refresh`.
+Nullability is judged from your side, which is why the two above point
+opposite ways: `Person.pets` losing its `!` hands a generated struct the
+nil it declared it wouldn't get, while `AdoptionInput.nickname` gaining
+one rejects a query that omits it. Any drift exits non-zero — whether a
+change matters is yours to judge.
 
-`graph_weaver:queries:check` answers the question that actually matters
-when it *has* moved: **which of your queries no longer validate, and
-why.** It re-introspects the recorded url (without rewriting the dump) and
-validates every `.graphql` file against the schema as it is right now,
-naming each error's line and column:
+`GraphWeaver::SchemaLoader.diff(path)` is the same summary as an object —
+`#breaking`, `#compatible`, `#to_h`, and `#empty?` for the plain "has it
+drifted" question.
+
+`queries:check` answers the question that actually matters when the schema
+*has* moved: **which of your queries no longer validate, and why.** It
+re-introspects the recorded url (without rewriting the dump) and validates
+every `.graphql` file against the schema as it is right now, naming each
+error's line and column, and exits non-zero:
 
 ```
 app/graphql/queries/person.graphql
@@ -290,9 +318,6 @@ app/graphql/queries/person.graphql
 1 invalid query
 ```
 
-It exits non-zero when anything fails, so it drops straight into CI or a
-scheduled job.
-
 The Ruby behind it returns the same thing as data, so you can wire it into
 whatever you already have (a spec, a Slack ping, an issue):
 
@@ -303,18 +328,17 @@ GraphWeaver.check_queries
 #         "line" => 4, "column" => 5 }] }
 ```
 
-Empty means everything validates. Pass `schema:` a loaded schema and nothing
-touches the network — handy for checking a *proposed* schema (a subgraph about
-to ship) before it's live:
+Empty means everything validates. Pass `schema:` a *loaded* schema (not a path)
+and nothing touches the network — handy for checking a proposed subgraph before
+it's live:
 
 ```ruby
 GraphWeaver.check_queries(schema: GraphWeaver::SchemaLoader.load("proposed.graphql"))
 ```
 
-It wants the loaded schema, not the path. Left off, it re-introspects the url
-the dump records — and when that dump is a composed supergraph, each error also
-names the subgraphs behind the type it points at
-([federation](federation.md#the-routing-table)).
+Left off, it re-introspects the url the dump records — and when that dump is a
+composed supergraph, each error also names the subgraphs behind the type it
+points at ([federation](federation.md#the-routing-table)).
 
 ## Sorbet, with or without
 

data/docs/logging.md

@@ -14,8 +14,9 @@ What logs at which level — pick the level, get the story:
 | Level | What you see |
 |-------|--------------|
 | `debug` | the wire: query + variables per call (long queries truncated), response status/bytes, request timing, connection open/drop, dynamically parsed modules |
-| `info` | schema introspection (with timing) and cache hits/misses, generated files written and any unregistered scalars, query modules loaded |
-| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` |
+| `info` | schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
+| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
+| `error` | development only: a `.graphql` edit that won't compile, with its file and position — the modules already loaded keep serving |
 
 Every line carries `graph_weaver` as the progname, so formatter-based
 filtering works out of the box. Wire lines are tagged
@@ -24,8 +25,37 @@ name — so a request's lines stay paired when threads interleave.
 
 **PII note**: queries, variables, and response sizes appear at debug
 only — variables can carry user data, so keep production loggers at
-info or above (or scrub in your formatter). Auth headers never log at
-any level.
+info or above. Auth headers never log at any level.
+
+## Filtered variables
+
+Debug gets switched on during an incident, which is exactly when a
+`login(password:)` mutation's variables must not land in the log. So the
+values of sensitive keys are replaced with `[FILTERED]` before the line is
+written — at any depth, including inside input objects.
+
+In Rails you configure nothing: the railtie adopts the app's own
+`config.filter_parameters`, so GraphWeaver scrubs whatever the request logs
+already scrub.
+
+Everywhere else, one list:
+
+```ruby
+GraphWeaver.filter_parameters = [:password, /token/]
+```
+
+Strings and Symbols match as case-insensitive substrings — `:token` covers
+`apiToken` — and Regexps match themselves. The default is `[:password,
+:token, :secret, :authorization]`, which covers the usual names before
+anyone configures anything; assigning replaces it rather than adding to it,
+and `[]` turns filtering off. Anything answering `#filter(hash)` is used
+as-is, which is how the railtie hands over an
+`ActiveSupport::ParameterFilter`.
+
+The same list scrubs error messages, which reach the log at `warn` rather
+than `debug`: a variable, input field, or entity key whose name is filtered
+is rejected with `[FILTERED]` in place of the value — everything else keeps
+quoting it, since `expected an Int, got "lots"` is the whole diagnosis.
 
 ## Instrumentation
 
@@ -52,7 +82,7 @@ response. Its payload carries:
 | Key | |
 |-----|--|
 | `:url` | the endpoint — nil in-process |
-| `:schema` | the schema class, in-process only |
+| `:schema` | the schema class's name, in-process only — a String, so a payload logs as it stands |
 | `:operation` | the operation name sent with the request (a generated module always has one) — what a trace keys on |
 | `:status` | the HTTP status, added once the response lands |
 

data/docs/scalars.md

@@ -22,11 +22,18 @@ GraphWeaver.register_scalar("User.birthday", Date)     # this field only
 ```
 
 A field override wins over the scalar-name registration — which is also how two
-servers that disagree about a `DateTime` coexist in one process. Coordinates are
-validated against the schema, so a typo'd field raises.
+servers that disagree about a `DateTime` coexist in one process.
 
-Pass a real class as `type:` and the cast/serialize are **inferred** from it by
-probing the deserialize side and pairing its serializer:
+Registrations are validated against the schema you generate against, and only
+what that schema can **disprove** fails generation: a name it declares as
+something else (`register_scalar("Species")` where `Species` is an enum), or a
+coordinate whose field it declares as a composite. A name it simply can't match
+only warns — one registry serves a whole graph, so that name may belong to the
+subgraph next door (see
+[federation](federation.md#generating-for-a-federated-graph)).
+
+Pass a real class as the second argument and the cast/serialize are
+**inferred** from it by probing the deserialize side and pairing its serializer:
 
 | the class defines | cast          | serialize      |
 |-------------------|---------------|----------------|
@@ -42,40 +49,128 @@ you need to:
 - a `Proc` for anything a method name can't express: `cast: ->(expr) { "Money.new(#{expr})" }`
 - `:itself` to force pass-through, opting out of inference (rare)
 
-`type:` also accepts a plain string (`"BigDecimal"`) when you'd rather not
+The type also accepts a plain string (`"BigDecimal"`) when you'd rather not
 reference the class. `requires:` (a string or array) names files emitted as
-`require`s atop the generated source so the cast/type resolve. When `type:` is
+`require`s atop the generated source so the cast/type resolve. When the type is
 a real class (so the runtime is loaded), each path is also `require`d at
 registration — a typo fails now, not in the generated file.
 
-Pass `coerce: true` to let a variable of this scalar accept **either** the value
-object **or** its raw input, normalizing the latter before it goes on the wire:
+The testing harness can't invent a wire value for a scalar registered as your
+own class — only `Money.parse` knows what it accepts — so it refuses rather than
+guess. Say it in test config, where that answer belongs: a pin for the type,
+`GraphWeaver::Testing.config.overrides = { "Money" => "12.00" }`, or per example
+([testing → pins](testing.md#pins)). A scalar registered as `Time`, `Date`,
+`Integer`, `Float`, `String` or `T::Boolean` needs nothing.
+
+A registration whose type is a class **JSON can't parse into** needs a
+`cast:` to build one — `BigDecimal` is the one people reach for, and it defines
+neither `.parse` nor `.load`, so inference finds no codec and the prop would be
+unsatisfiable. Generation refuses it where a query reads that scalar back,
+naming the field:
+
+```
+register_scalar("Money", BigDecimal) has no cast, so nothing builds a BigDecimal
+out of the JSON at Product.price — give it one ...
+```
+
+A registration used only for a variable is untouched: nothing casts it.
+
+`cast:` is also what a *variable* of this scalar coerces through, so the same
+registration gets you both directions with nothing to switch on:
 
 ```ruby
-GraphWeaver.register_scalar("Money", Money, coerce: true)
-# generated execute now takes T.any(Money, String); "12.00" is parsed
+GraphWeaver.register_scalar("Money", Money)
 StoreQuery.execute(budget: "12.00")          # Money.parse("12.00") under the hood
-StoreQuery.execute(budget: Money.new(1200))  # passed straight through
+StoreQuery.execute(budget: Money.new(1200))  # already a Money — passed straight through
 ```
 
-`GraphWeaver.auto_coerce = true` is the same switch for every scalar at once —
-set it any time before you generate; an explicit `coerce:` on a registration
-always wins. Off by default either way: the strict typed kwarg is the norm.
-
-*How* a scalar coerces isn't yours to pick — the scalar already knows. `Int` and
-`Float` convert (`"5"` → `5`, sent as a native number); anything with a full
-cast/serialize pair (`Date`, your `Money`) parses, and bad input still explodes
-because the cast raises. A pass-through scalar — `String`, `ID`, `Boolean` — has
-neither a conversion nor a codec pair, so it can't coerce at all: `coerce: true`
-on one raises rather than emitting a no-op.
+The kwarg is still typed `Money`, not `T.any(Money, String)`: `execute`'s sig
+stays as narrow as the schema and the conversion happens in its body (see
+[typed variables](generated_modules.md#variables-become-typed-kwargs)). So
+`budget: "12.00"` written literally in a `# typed:` file is still an `srb tc`
+error — as it should be, since you have a `Money` right there — while
+`budget: params[:budget]` typechecks and converts.
 
 The built-in scalars (`Date`, `ID`, `Int`, …) are pre-registered through the
 same path (`Date` even carries its own `require "date"`), so a later
 `register_scalar` overrides them.
 
-`GraphWeaver.reset_registrations!` is the clean slate between tests: built-in
-scalars restored, enum mappings and type helpers dropped. To reset one registry
-rather than all of them, `GraphWeaver::Codegen` has the pieces —
+## What the wire carries
+
+The rule is one sentence: **generated code takes every JSON spelling a
+spec-compliant server may write, and refuses the rest.** The tables below are
+the whole of it, and [`bin/round-trip`](../bin/round-trip) fuzzes both
+directions against them — the accepted spellings as real values, the refused
+ones under `--hostile`, where generated code has to name what it turned down.
+
+The one place "spec-compliant" is doing real work is `Float`. JSON has a single
+number type and encoders write the shortest form, so `1.0` reaches Ruby as `1`
+from graphql-js and from Go. Nothing does the reverse: `2.0` for an `Int` is the
+server writing a non-integer where the spec says integer, so it is refused.
+
+### Coming back — what `from_h` accepts
+
+| scalar | accepted | refused |
+|---|---|---|
+| `Int` | any JSON integer, including past 2³¹ and 2⁵³ (lossless in Ruby) | `2.0`, `1.5`, `"1"`, `true` |
+| `Float` | any JSON number, `3` and `-0.0` and `1e308` included; also a decimal string | a non-numeric string, `true`, a list/object |
+| `String` | any JSON string — empty, unicode, newlines, control characters | a number, `true`, a list/object |
+| `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 |
+| an enum | a declared value, as a string | an undeclared value, a non-string |
+| unregistered | anything — `T.untyped`, straight through | nothing |
+
+A refusal is a [`GraphWeaver::TypeError`](errors.md) naming the field and the
+generated struct (which names the query). Two refusals carry advice rather than
+only sorbet's words: an unquoted `ID`, and a registration with no cast (above).
+
+Numeric strings — here, and in the going-out table below — are read as a wire
+format, not as Ruby source: `"010"` is ten, and `"0x1f"` and `"1_0"` are
+refused. `Kernel#Integer` and `Kernel#Float` accept all three as literals,
+which would let a zero-padded form field silently mean something else.
+
+### Going out — what a variable kwarg accepts
+
+The kwarg's **type** is what `srb tc` holds a call site to, and it is exactly
+what the schema says. The **value** reaching `execute` at runtime is coerced,
+because a Rails param is a String whatever the sig says (see
+[typed variables](generated_modules.md#variables-become-typed-kwargs) for why
+the 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 |
+| `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 | `iso8601` |
+| `Time` | `Time` | a string `Time.parse` takes | `iso8601` |
+| 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 | its `serialize:` |
+| unregistered | `T.untyped` | anything | straight through |
+
+Two rows are judgment calls worth stating. **`ID` takes an `Integer`** because
+the GraphQL spec says an ID serializes as a string but accepts an integer input,
+and `execute(id: user.id)` off a model is the everyday call; `String` gets no
+such license, since an `Integer` where a `String` belongs is more often a bug
+than a spelling. **`Boolean` takes no string** — Ruby has no `Kernel#Boolean`,
+so every rule for reading `"0"`, `"off"`, `"no"` is somebody's convention, and
+the library will not pick one for you; convert at the call site.
+
+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.
+Input-object fields go through this table too, so `{first: "20"}` inside a
+filter hash reads the same as `first: "20"` as a kwarg.
+
+`GraphWeaver.reset_registrations!` is the clean slate between tests, or between
+generations for different schemas: built-in scalars restored, enum mappings and
+type helpers dropped. To reset one registry rather than all of them,
+`GraphWeaver::Codegen` has the pieces —
 `reset_scalars!` (restore the built-ins), `clear_scalars!` (empty the registry
 entirely), `reset_enums!`, `reset_type_helpers!`.