graph_weaver 0.7.0 → 0.7.1

data/docs/errors.md

@@ -26,17 +26,71 @@ response.extensions     # { "cost" => … } — rides on success too
 response.data!          # the Result, or raise GraphWeaver::QueryError
 ```
 
-**`execute!` raises whenever `errors` is non-empty** — partial data included,
-so a mutation that created the order and then failed on the way out still
-raises, with the data hanging off `QueryError#data`. Reach for `execute` when
-a partial answer is one you can use.
+**`execute!` raises whenever `errors` is non-empty** — partial data included, so a
+mutation that created the order and then failed on the way out still raises, with
+the data hanging off `QueryError#data`. Reach for `execute` when a partial answer
+is one you can use.
 
-The envelope is a single generic `GraphWeaver::Response[Result]` — `response.data`
-stays fully typed to *this* query's result, no per-query wrapper class.
+Every `GraphQLError` exposes `#message`, `#locations`, `#path`, `#extensions`, and
+`#code` (`extensions["code"]`) — match on the **code**, not the message string
+(`response.errors.first.code == "THROTTLED"`).
 
-Every `GraphQLError` exposes `#message`, `#locations`, `#path`, `#extensions`,
-and `#code` (`extensions["code"]`) — match on the **code**, not the message
-string (`response.errors.first.code == "THROTTLED"`).
+## The three you'll meet first
+
+**A variable that won't convert** raises `GraphWeaver::InputError` before the
+request leaves — top-level scalars, input-object fields, at any depth. One rescue
+point turns invalid input into a 422:
+
+```ruby
+rescue GraphWeaver::InputError => e
+  render json: e.to_h, status: :unprocessable_entity
+  # { "error" => "GraphWeaver::InputError",
+  #   "message" => "$input of AdoptMutation: species: \"LIZARD\" is not a valid " \
+  #                "GraphQLTypes::Species — expected one of: CAT, DOG",
+  #   "kind" => "not_a_member", "path" => ["input", "species"],
+  #   "coordinate" => "AdoptionInput.species", "field" => "species",
+  #   "value" => "LIZARD", "details" => { "members" => ["CAT", "DOG"] },
+  #   "struct" => "GraphQLTypes::AdoptionInput" }
+end
+```
+
+**The server rejecting the input** arrives as ordinary `GraphQLError`s, and
+`#input_errors` reads the ones that are about your input back into the same
+`InputError` — so one renderer serves both halves:
+
+```ruby
+response = AdoptMutation.execute(input: params[:pet])
+
+response.input_errors   # [GraphWeaver::InputError] — [] when none
+response.errors         # still every error, input or not
+```
+
+**Everything else is a class to rescue.** The network broke, the server answered
+non-2xx, or it answered 200 and complained:
+
+```ruby
+begin
+  person = PersonQuery.execute!(id: "1").person
+rescue GraphWeaver::TransportError
+  retry                                   # network blip
+rescue GraphWeaver::ServerError => e
+  e.throttled? || e.status >= 500 ? backoff : raise  # a plain 4xx is our bug
+rescue GraphWeaver::QueryError => e
+  e.throttled? ? backoff : raise          # the same question, asked of the errors array
+end
+```
+
+**Which arm catches a failure is the server's choice**, not a rule you can rely
+on: an origin server answers 429 with no body and you get a `ServerError`, while
+Apollo Router answers the same rate limit with `503` *and* a GraphQL errors body,
+so it arrives as a `QueryError` — as do its 500s, 401s and 403s. So don't put the
+retry decision in the `ServerError` arm: hand it to
+[`Retry`](transports.md#retries), which asks the same question of both.
+`#throttled?` spells the same on both for the same reason, and knows the codes the
+big graphs send (`GraphWeaver::GraphQLError::THROTTLE_CODES` — Shopify's
+`THROTTLED`, GitHub's `RATE_LIMITED`, Apollo Router's `REQUEST_RATE_LIMITED`).
+
+## The classes
 
 Everything GraphWeaver *concludes* descends from `GraphWeaver::Error` — a
 transport failure, a rejected query, a response that wouldn't cast, a plan the
@@ -57,58 +111,41 @@ subclass says where it failed:
 | `Testing::MissingRecording` | a [cassette](cassettes.md) holds no entry for this request — the message prints the variables, and the ones it did record |
 
 An argument that is wrong *on its face* raises a plain `ArgumentError` instead
-(`pool_size: must be >= 1`, `cast: must be a Symbol, Proc, :itself, or nil`),
-like any Ruby method — a bug at the call site, not a condition to rescue. The
-line is whether the library had to read your schema to reach the verdict: it
-did for `ConfigurationError`, which is why a spec helper can rescue that one.
-
-```ruby
-begin
-  person = PersonQuery.execute!(id: "1").person
-rescue GraphWeaver::TransportError
-  retry                                   # network blip
-rescue GraphWeaver::ServerError => e
-  e.throttled? || e.status >= 500 ? backoff : raise  # a plain 4xx is our bug
-rescue GraphWeaver::QueryError => e
-  e.throttled? ? backoff : raise          # the same question, asked of the errors array
-end
-```
-
-`#throttled?` deliberately spells the same on both: an API may say "slow
-down" with a 429 or with a `THROTTLED` error in a body, and a caller
-shouldn't have to know which. It recognizes the codes the big graphs
-actually send (`GraphWeaver::GraphQLError::THROTTLE_CODES` — Shopify's
-`THROTTLED`, GitHub's `RATE_LIMITED`, Apollo Router's
-`REQUEST_RATE_LIMITED`); pass that constant to `Retry`'s `retry_codes:`
-instead of hand-writing the strings.
-
-**Which arm catches a failure is the server's choice, not a rule you can
-rely on.** An origin server answers 429 with no body and you get a
-`ServerError`; Apollo Router answers the same rate limit with `503` *and* a
-GraphQL errors body, so the same failure arrives as a `QueryError` — and
-its 500s, 401s and 403s come the same way. So don't put the retry decision
-in the `ServerError` arm: hand it to [`Retry`](transports.md#retries), which
-asks the same question of both, and keep these arms for what you do with a
-failure you aren't retrying.
-
-**A status with an obvious next step says it.** A 3xx appends "redirects are
-not followed" and the `Location` to repoint the client at — replaying a POST,
-with its `Authorization` header, at a host the server named isn't the
-library's call. A 401 or 403 appends "check `auth:` — the token, and its
-scopes".
-
-**And both network failures name the endpoint**, in the message and on `#url`,
-because an app with more than one graph has more than one answer to "which
-server did this". The url they name is the one the gem is willing to *say*:
-userinfo, and any query parameter
-[`filter_parameters`](logging.md) already filters, are folded to `[FILTERED]`
-before it reaches a message, a log line or your APM. `Transport#url` stays the
-real endpoint; `Transport#safe_url` is the sayable one.
-
-**Everything you pass to `execute` is caller input**, so a value that won't
-convert raises `GraphWeaver::InputError` — top-level scalar variables included.
-They name the variable and the operation, since the value alone locates nothing
-in an app that runs a hundred queries:
+(`pool_size: must be >= 1`), like any Ruby method — a bug at the call site, not a
+condition to rescue. The line is whether the library had to read your schema to
+reach the verdict: it did for `ConfigurationError`, which is why a spec helper can
+rescue that one. A *missing* required kwarg is Ruby's own `ArgumentError` too
+("missing keyword: :id").
+
+**A status with an obvious next step says it.** A 3xx appends "redirects are not
+followed" and the `Location` to repoint the client at — replaying a POST, with its
+`Authorization` header, at a host the server named isn't the library's call. A 401
+or 403 appends "check `auth:` — the token, and its scopes". Both name the endpoint,
+in the message and on `#url`, with credentials
+[folded to `[FILTERED]`](logging.md#filtered-variables) first.
+
+**A partial answer only survives as far as the nearest nullable field.** That is
+GraphQL's null propagation, not this client, and the conventional Relay payload is
+exactly where it bites: given `ChargePayload { order: Order!, receiptUrl: String! }`,
+a resolver that raises on `receiptUrl` *after the order was charged* nulls
+`receiptUrl`, which is non-null, so the null climbs to the payload and on to the
+root — `response.data` and `QueryError#data` are both `nil`, and the order you just
+created is nowhere in the response. Making the **payload field** nullable doesn't
+help: the null stops at `{"charge" => nil}` and the order was inside it. Two things
+do — make the field *that can fail* nullable (`receiptUrl: String`), which leaves
+`order` on `data` beside the error; or accept that the write's outcome is not in
+the response and read the order back.
+
+Business/validation failures returned *as data* (Shopify-style
+`userErrors { field message code }`) aren't errors here — they're fields you
+selected, so they deserialize onto `response.data` like anything else.
+
+## Input errors
+
+`InputError` is raised for anything you pass to `execute` that won't convert,
+including a top-level scalar variable. The message names the variable and the
+operation, since the value alone locates nothing in an app that runs a hundred
+queries:
 
 ```
 $count of Compute: expected an Int, got "lots"
@@ -116,56 +153,33 @@ $count of Compute: expected an Int, got "lots"
 
 The value is usually the whole diagnosis, so it is quoted — unless the key it
 arrived under is one your `filter_parameters` covers, in which case the message
-reads `$password of Login: [FILTERED]`. A filtered key *inside* the value is
-covered too, at any depth: `got {"user" => "d", "token" => "[FILTERED]"}`, the
-same scrubbing `#value` gets. Error messages reach the log at `warn`,
-above the level that gates the variables line, so they are scrubbed by the same
-list ([logging](logging.md#filtered-variables)).
-
-A *missing* required kwarg is still a plain `ArgumentError` ("missing keyword:
-:id") — that's Ruby's, and it is a programming bug rather than bad input.
-
-**What's inside an input object** reports the same way. Pass one as a hash (or
-struct) and it's built through the generated `coerce`, and anything wrong in
-there raises `GraphWeaver::InputError` too — so one rescue point turns invalid
-input into a 422:
-
-```ruby
-rescue GraphWeaver::InputError => e
-  render json: e.to_h, status: :unprocessable_entity
-  # { "error" => "GraphWeaver::InputError",
-  #   "message" => "$input of AdoptMutation: species: \"LIZARD\" is not a valid " \
-  #                "GraphQLTypes::Species — expected one of: CAT, DOG",
-  #   "kind" => "not_a_member", "path" => ["input", "species"],
-  #   "coordinate" => "AdoptionInput.species", "field" => "species",
-  #   "value" => "LIZARD", "details" => { "members" => ["CAT", "DOG"] },
-  #   "struct" => "GraphQLTypes::AdoptionInput" }
-end
-```
-
-`to_h` carries only the keys that have something to say, so a key is **absent**
-rather than `null` — `"value"` is missing both when the value was never known
-and when it was null, and `"kind"` tells those apart (`"missing"` has no value
-by definition). Read it with `hash["value"]`, not `hash.key?("value")`.
-
-**A JSON controller underscores on the way in.** Generated input structs take
-the prop spelling, so a camelCase request body makes *every* key an unknown
-one — `params.deep_transform_keys(&:underscore)` before `execute`.
-`details[:suggestion]` is how you tell that from a typo: a casing problem hands
-the same key back in snake_case (`customerEmail` → "did you mean
-'customer_email'?"), a real typo suggests a different field.
-
-A nested filter reports the innermost input type, so the error points at the
-input that actually held the bad field. Passing something that is neither — a
-bare `String` where the input goes — reports the same way. A call site that
-*spells* the wrong type is caught earlier and better, by `srb tc`: the sig is
-as narrow as the schema, and only untyped values reach the runtime check
+reads `$password of Login: [FILTERED]`, and a filtered key *inside* the value is
+covered at any depth ([logging](logging.md#filtered-variables)).
+
+`to_h` (above) carries only the keys that have something to say, so a key is
+**absent** rather than `null` — `"value"` is missing both when the value was never
+known and when it was null, and `"kind"` tells those apart. Read it with
+`hash["value"]`, not `hash.key?("value")`.
+
+**A JSON controller underscores on the way in.** Generated input structs take the
+prop spelling, so a camelCase request body makes *every* key an unknown one —
+`params.deep_transform_keys(&:underscore)` before `execute`. `details[:suggestion]`
+is how you tell that from a typo: a casing problem hands the same key back in
+snake_case (`customerEmail` → "did you mean 'customer_email'?"), a real typo
+suggests a different field.
+
+A nested filter reports the innermost input type, so the error points at the input
+that actually held the bad field; passing something that is neither — a bare
+`String` where the input goes — reports the same way. A call site that *spells* the
+wrong type is caught earlier and better, by `srb tc`
 ([why](generated_modules.md#variables-become-typed-kwargs)).
 
+The one-shot `GraphWeaver.run` / `run!` mirror `execute` / `execute!`.
+
 ### What an InputError says, without reading English
 
-`#message` is the developer's line and it will be reworded. Everything a form
-or an API response needs is beside it, as data:
+`#message` is the developer's line and it will be reworded. Everything a form or
+an API response needs is beside it, as data:
 
 | | |
 |---|---|
@@ -175,52 +189,47 @@ or an API response needs is beside it, as data:
 | `#value` | the rejected value, through [`filter_parameters`](logging.md#filtered-variables), and always JSON-representable (a non-finite Float travels as `"NaN"`/`"Infinity"`). `nil` when it was never known — a missing field has none, and an unknown key owns no slot to hold one |
 | `#details` | kind-specific facts, never pre-formatted — `{ members: ["CAT", "DOG"] }`, `{ type: "Int" }`, `{ suggestion: "species" }`. `type` is the **schema's** name for the type (`Money`, `AdoptionInput`), never the Ruby class it maps to |
 | `#field` | `#path`'s last *named* segment — the one field a form highlights. A trailing list index is a position, not a field, so `["ids", 2]` is still `"ids"` |
-| `#struct` | the input type being built |
+| `#struct` | the input type being built — the generated struct *class* where generation produced one, and the GraphQL type *name* where it didn't (a federation representation builds a plain Hash). `to_h`'s `"struct"` is the name either way |
 
 So a form reads `e.field` and either `e.message` or — better — its own sentence
 built from `e.kind` and `e.details`.
 
-**When the leaf isn't a field.** A Hasura-shaped filter puts a comparison
-operator at the bottom, so `where: { height: { _gte: "abc" } }` refuses with
-`#path` `["where", "height", "_gte"]` and `#field` `"_gte"` — right by the rule,
-and useless to a form. Key the form on `#path` there: the column is the segment
-before the operator.
+**When the leaf isn't a field.** A Hasura-shaped filter puts a comparison operator
+at the bottom, so `where: { height: { _gte: "abc" } }` refuses with `#path`
+`["where", "height", "_gte"]` and `#field` `"_gte"` — right by the rule, and
+useless to a form. Key the form on `#path` there: the column is the segment before
+the operator.
 
-**Long values are cut.** An error is built for whatever a caller sent and
-whatever a server echoed back, either of which can be megabytes — and every
-raised one writes a `warn` line as well as landing in `to_h`. So each String
-`#value` holds (at every depth), the value `#message` quotes, and a sentence a
-server wrote are capped at `GraphWeaver::InputError::VALUE_LIMIT` — 1024 bytes,
-with `…(N more bytes)` in place of the rest.
+**Long values are cut.** An error is built for whatever a caller sent and whatever
+a server echoed back, either of which can be megabytes, and every raised one writes
+a `warn` line. So each String `#value` holds (at every depth), the value `#message`
+quotes, and a sentence a server wrote are capped at
+`GraphWeaver::InputError::VALUE_LIMIT` — 1024 bytes, with `…(N more bytes)` in
+place of the rest.
 
 #### Which spelling a path is in
 
-**`#path`, `#field` and `#coordinate` are the schema's spelling**
-(`issuedOn`, `externalId`) — one rule, whichever side refused. A server can
-produce no other, and the client knows both, so this is the only spelling both
-halves can agree on: a form keyed on `e.field` finds the same slot for a
-refusal raised before the request left and for one the server sent back.
+**`#path`, `#field` and `#coordinate` are the schema's spelling** (`issuedOn`,
+`externalId`) — one rule, whichever side refused. A server can produce no other,
+and the client knows both, so this is the only spelling both halves can agree on:
+a form keyed on `e.field` finds the same slot for a refusal raised before the
+request left and for one the server sent back.
 
-The **prop** (`issued_on`) is what you type in Ruby — `.new`, `.coerce`, the
-kwargs of `execute` — and it is `#message`, the developer's line, that names
-it: `"external_id: expected an Int, got \"lots\""`. Two names for one field,
-each where it helps.
-
-In a Rails form the field names are the props, so underscore on the way in —
-and give the nil case a home, because **`#field` is `nil` whenever nothing named
-a slot**, which is what a `:refused` error from a server that stated no input
-path gives you:
+The **prop** (`issued_on`) is what you type in Ruby — `.new`, `.coerce`, the kwargs
+of `execute` — and it is `#message`, the developer's line, that names it. In a
+Rails form the field names are the props, so underscore on the way in — and give
+the nil case a home, because **`#field` is `nil` whenever nothing named a slot**:
 
 ```ruby
 form.errors.add(e.field&.underscore || :base, render_input_error(e))
 ```
 
-The one segment that is neither is an **unknown key** — a typo names no field,
-so the schema has no spelling for it. It comes back exactly as you wrote it,
-and `details[:suggestion]` is the prop to type instead.
+The one segment that is neither is an **unknown key** — a typo names no field, so
+the schema has no spelling for it. It comes back exactly as you wrote it, and
+`details[:suggestion]` is the prop to type instead.
 
-**`#path` is rooted at the variable**, so its first segment is the kwarg you
-passed and its last is the field that actually held the value:
+**`#path` is rooted at the variable**, so its first segment is the kwarg you passed
+and its last is the field that actually held the value:
 
 | you called | `#path` | `#coordinate` |
 |---|---|---|
@@ -231,21 +240,9 @@ passed and its last is the field that actually held the value:
 | `AdoptionInput.coerce(name: "Rex", speceis: "DOG")` — no variable to name | `["speceis"]` — a typo names no field, so it is echoed as written | `nil` — the type defines no such field |
 | `execute(count: "lots")` — a top-level scalar | `["count"]` | `nil` — a variable names no schema element |
 
-`#coordinate` is `nil` wherever the schema has no name for the slot: a
-variable, a key the input type doesn't define, a nested `@key` path in a
-federation representation, or a server that didn't say which type it meant.
-
-`#struct` is the generated input struct *class* where generation produced one,
-and the GraphQL type *name* where it didn't — a federation representation
-builds a plain Hash, so an entity has only its name to give. `to_h`'s
-`"struct"` is the name either way, so branch on that.
-
-Business/validation failures returned *as data* (Shopify-style `userErrors { field
-message code }`) aren't errors here — they're just fields you selected, so they
-deserialize onto `response.data` like anything else and you inspect them there.
-
-The one-shot `GraphWeaver.run` / `run!` mirror this: `run` returns
-the envelope, `run!` the result-or-raise.
+`#coordinate` is `nil` wherever the schema has no name for the slot: a variable, a
+key the input type doesn't define, a nested `@key` path in a federation
+representation, or a server that didn't say which type it meant.
 
 ### When the *server* rejects the input
 
@@ -261,28 +258,14 @@ three it knows by name, and claims nothing from the rest:
 | **Hasura** | `extensions.path` naming an argument — `"$.selectionSet.<field>.args.<name>"` — under `validation-failed` or `parse-failed` | the field; `:not_a_member`, `:unknown` or `:missing` for the three sentences it always writes, `:refused` otherwise |
 | **anything else** | nothing | `#input_errors` is `[]` — see [the fallback](#when-your-server-marks-nothing) |
 
-`InputError` is the client-side half — graph_weaver refuses before the request
-leaves. When the *server* is the one that says no, the rejection arrives as
-ordinary `GraphQLError`s, and `#input_errors` reads the ones that are about
-your input back into **the same `InputError`** — so one renderer serves both
-halves:
-
-```ruby
-response = AdoptMutation.execute(input: params[:pet])
-
-response.input_errors   # [GraphWeaver::InputError] — [] when none
-response.errors         # still every error, input or not
-```
-
 `QueryError#input_errors` asks the same question of the raised envelope, and
-`GraphQLError#input_errors` of one error. It is **plural on every one of them**:
-a single variable-coercion error routinely carries several problems about
-different fields, and keeping only the first would lose the rest silently.
-These are values, not raises — building one writes no log line. `#message` and
-`#value` go through `filter_parameters` here exactly as they do on the client
-side: a server quotes the value it rejected as a matter of course
-(`Could not coerce value "hunter2" to Int`), and that is a message about a key
-your list covers.
+`GraphQLError#input_errors` of one error. It is **plural on every one of them**: a
+single variable-coercion error routinely carries several problems about different
+fields, and keeping only the first would lose the rest silently. These are values,
+not raises — building one writes no log line. `#message` and `#value` go through
+`filter_parameters` here exactly as they do on the client side: a server quotes the
+value it rejected as a matter of course (`Could not coerce value "hunter2" to
+Int`), and that is a message about a key your list covers.
 
 Generated modules always send **variables**, never literals, which narrows a
 graphql-ruby server to two shapes (measured against 2.6.10):
@@ -293,32 +276,27 @@ graphql-ruby server to two shapes (measured against 2.6.10):
 | a `validates:` rule failed — range, format, inclusion, length | an **execution** error: `response.data` is present with the field nulled (so `success?` is false on a response that still carries data), `path` is the **response** path (`["adopt"]` — the field, not the input field), and there is **no `extensions` key at all** | **nothing** — see below |
 
 **A `validates:` failure is not claimed.** With no `extensions` at all it is
-indistinguishable from "the database is down", and attaching *that* to a form
-field is worse than missing it — so it stays an ordinary error in
-`response.errors` and `#input_errors` says nothing it can't know. One line on
-the server fixes it, and the next section is that line.
+indistinguishable from "the database is down", and attaching *that* to a form field
+is worse than missing it — so it stays an ordinary error in `response.errors`. One
+line on the server fixes it, and [the next section](#what-your-server-can-send) is
+that line.
 
 **Hasura is read off the path, not a code.** `validation-failed` is the code it
-sends for a query that doesn't parse *and* for a value it won't take, so the
-code alone would attach your own `.graphql` file to a form field. The argument
-in `extensions.path` is what settles it, and only three of its sentences earn a
-`kind`: `limit: -5` comes back `:refused` on `path: ["limit"]`, because the
-sentence Hasura writes for it ("expected a non-negative 32-bit integer for type
-'Int', but found a number") is the same one it writes for `limit: "lots"` —
-a wrong type, not a value out of range. The field is worth having; the guess
-isn't.
-
-And the commonest real Hasura input mistake isn't read at all: a `where:` value
-that Hasura's comparison type accepts but the underlying Postgres column
+sends for a query that doesn't parse *and* for a value it won't take, so the code
+alone would attach your own `.graphql` file to a form field. The argument in
+`extensions.path` is what settles it, and only three of its sentences earn a
+`kind`: `limit: -5` comes back `:refused`, because the sentence Hasura writes for
+it ("expected a non-negative 32-bit integer for type 'Int', but found a number")
+is the same one it writes for `limit: "lots"`. The field is worth having; the guess
+isn't. And the commonest real Hasura input mistake isn't read at all: a `where:`
+value that Hasura's comparison type accepts but the underlying Postgres column
 rejects (`{ id: { _eq: "abc" } }` on a `uuid`) gets past validation and fails at
-the database, which comes back as `data-exception` at path `"$"` — neither code
-read here, and no argument named. `#input_errors` is `[]`, and
-`invalid input syntax for type uuid` is the server's sentence to render.
+the database, arriving as `data-exception` at path `"$"` with no argument named.
 
 #### When your server marks nothing
 
-Then `#input_errors` is `[]` and says so — which is the signal to render what
-the server *did* send, not to parse its prose:
+Then `#input_errors` is `[]` and says so — which is the signal to render what the
+server *did* send, not to parse its prose:
 
 ```ruby
 response = AdoptMutation.execute(input: params[:pet])
@@ -337,10 +315,10 @@ end
 ### What your server can send
 
 Two of the eight kinds — `:out_of_range` and `:invalid_format`, the everyday
-"right type, wrong value" — **cannot be produced from either side on their
-own.** The client doesn't know the schema's bounds, and graphql-ruby puts a
-`validates:` failure on the wire as a bare sentence. Only the server can say
-it, so there is one key to say it under:
+"right type, wrong value" — **cannot be produced from either side on their own.**
+The client doesn't know the schema's bounds, and graphql-ruby puts a `validates:`
+failure on the wire as a bare sentence. Only the server can say it, so there is one
+key to say it under:
 
 ```json
 "extensions": {
@@ -356,170 +334,87 @@ it, so there is one key to say it under:
 ```
 
 `code` is the ecosystem's coarse bucket, so a client that has never heard of
-graph_weaver still understands; `input` is the fine one. Only `kind` is
-required, and it must come from [the table](i18n.md#the-vocabulary) — an
-unrecognized one degrades to `:refused` rather than being passed through, and
-any key outside `type`/`members`/`min`/`max`/`pattern`/`suggestion` is dropped
-rather than reaching `#details`. None of those six is a name I18n reserves for
-itself, so `I18n.t(key, **details)` can never raise on the splat.
-
-`path` must be an **Array of field names and list indices**. A dotted String,
-or a segment that is neither, is dropped whole rather than parsed — and nothing
-stands in for it: `#path` is `[]` and `#field` is `nil`. In particular the
-GraphQL error's own `path` is never borrowed, because it names a *selection*
-(`["createOrder"]`) rather than an input slot, and a form that trusted `#field`
-there would highlight a field called `create_order`. Everything else the server
-did state — the `kind`, the `details` — still stands.
-
-In graphql-ruby this rides on a `Validator` raising `GraphQL::ExecutionError`:
-
-```ruby
-class AtLeastValidator < GraphQL::Schema::Validator
-  def initialize(min:, **rest)
-    @min = min
-    super(**rest)
-  end
-
-  def validate(_object, _context, value)
-    return if value.nil? || value >= @min
-
-    raise GraphQL::ExecutionError.new(
-      "#{validated.graphql_name} must be at least #{@min}",
-      extensions: {
-        "code" => "BAD_USER_INPUT",
-        "input" => {
-          "kind" => "out_of_range",
-          "path" => ["input", validated.graphql_name],
-          "coordinate" => "#{validated.owner.graphql_name}.#{validated.graphql_name}",
-          "value" => value,
-          "min" => @min,
-        },
-      },
-    )
-  end
-end
-GraphQL::Schema::Validator.install(:at_least, AtLeastValidator)
-
-class RangeInput < GraphQL::Schema::InputObject
-  argument :min, Integer, required: true, validates: { at_least: { min: 1 } }
-end
-```
-
-and for a scalar, on `GraphQL::CoercionError`, whose extensions arrive nested
-under `problems[i].extensions`:
-
-```ruby
-class EmailScalar < GraphQL::Schema::Scalar
-  graphql_name "Email"
-
-  def self.coerce_input(value, _ctx)
-    return value if value.to_s.match?(/\A[^@\s]+@[^@\s]+\z/)
-
-    raise GraphQL::CoercionError.new(
-      "#{value.inspect} is not an email address",
-      extensions: { "input" => { "kind" => "invalid_format", "pattern" => "name@example.com" } },
-    )
-  end
-
-  def self.coerce_result(value, _ctx) = value
-end
-```
-
-**You author that `path`, and a validator on a field cannot know its list
-index.** `Validator#validate(object, context, value)` is handed the argument
-*definition* (`validated`, shared by every element), the value, and a context
-whose `current_path` is the **response** path (`["createOrder"]`) — graphql-ruby
-coerces a list with a plain `map` and keeps no index (measured against 2.6.10).
-Install the validator above on a `qty` inside `lines: [LineInput!]!` and it
-writes `["input", "qty"]` for every element alike, so a 200-line order can't say
-which line was wrong.
-
-Where the index matters, install the validator on the **list argument** instead:
-`value` is then the whole coerced Array, so you index it yourself.
+graph_weaver still understands; `input` is the fine one. Only `kind` is required,
+and it must come from [the table](i18n.md#the-vocabulary) — an unrecognized one
+degrades to `:refused` rather than being passed through, and any key outside
+`type`/`members`/`min`/`max`/`pattern`/`suggestion` is dropped rather than reaching
+`#details`. None of those six is a name I18n reserves for itself, so
+`I18n.t(key, **details)` can never raise on the splat.
+
+`path` must be an **Array of field names and list indices**. A dotted String, or a
+segment that is neither, is dropped whole rather than parsed — and nothing stands
+in for it: `#path` is `[]` and `#field` is `nil`. In particular the GraphQL error's
+own `path` is never borrowed, because it names a *selection* (`["createOrder"]`)
+rather than an input slot, and a form that trusted `#field` there would highlight a
+field called `create_order`. Everything else the server did state still stands.
+
+In graphql-ruby it rides on two raises. A `GraphQL::Schema::Validator` raising
+`GraphQL::ExecutionError` covers a `validates:` rule, with `validated` giving you
+the argument's own name and owner for the `path` and `coordinate`:
 
 ```ruby
-class LinesValidator < GraphQL::Schema::Validator
-  def validate(_object, _context, lines)
-    lines.each_with_index do |line, index|
-      next if line[:qty] >= 1
-
-      raise GraphQL::ExecutionError.new(
-        "qty must be at least 1",
-        extensions: { "code" => "BAD_USER_INPUT", "input" => {
-          "kind" => "out_of_range", "path" => ["input", "lines", index, "qty"],
-          "coordinate" => "LineInput.qty", "value" => line[:qty], "min" => 1,
-        } },
-      )
-    end
-  end
-end
-
-field :create_order, OrderType do
-  argument :lines, [LineInput], required: true, validates: { LinesValidator => {} }
-end
+raise GraphQL::ExecutionError.new(
+  "#{validated.graphql_name} must be at least #{@min}",
+  extensions: { "code" => "BAD_USER_INPUT", "input" => {
+    "kind" => "out_of_range", "path" => ["input", validated.graphql_name],
+    "coordinate" => "#{validated.owner.graphql_name}.#{validated.graphql_name}",
+    "value" => value, "min" => @min,
+  } },
+)
 ```
 
-Per-element validators run first and the list's own runs after, so by the time
-this one sees `lines` every element is fully coerced.
-
-What the client then reads:
-
-```ruby
-# min: 0 into the validator above
-{ "kind" => "out_of_range", "path" => ["input", "min"], "coordinate" => "RangeInput.min",
-  "field" => "min", "value" => 0, "details" => { "min" => 1 },
-  "message" => "min must be at least 1" }
-
-# email: "nope" into the scalar above
-{ "kind" => "invalid_format", "path" => ["email"], "field" => "email", "value" => "nope",
-  "details" => { "pattern" => "name@example.com" },
-  "message" => "\"nope\" is not an email address" }
-```
-
-Say it plainly: **without the convention**, that range failure is
-`:refused` at best — the message and nothing else, and only if the server
-stamped `BAD_USER_INPUT`. **With it**, it is `:out_of_range` with `min` as a
-number your form can compare against. A server that follows none of this
-degrades; it does not guess.
-
-**One problem per call.** `#input_errors` is plural, but a single call rarely
-fills it — neither side collects the way `ActiveModel::Errors` does:
-
-- *Client side*, `coerce` walks the input type's fields in declaration order
-  and raises on the first one whose value won't convert; the rest are never
-  looked at. The two cases it does gather are the ones it can see all of
-  without walking further — **unknown keys** and **absent required fields** are
-  both listed in full in the message (`missing required key(s) for
-  AdoptionInput: name, species`), though `#path` names only the first, because
-  a path that points at two fields points at neither.
-- *Server side*, graphql-ruby (measured against 2.6.10) aborts variable
-  validation at the first `GraphQL::ExecutionError` a `validates:` rule raises,
-  across the whole input tree — a bad `coupon` and an out-of-range `qty` in one
-  submit come back as one error, and so do two bad elements of one list.
-
-Build the form expecting to iterate, in other words, rather than to show every
-problem after one round trip. The exception is a graphql-ruby **coercion**
-failure, which carries a `problems` array and really does report several fields
-at once.
+A custom scalar's `coerce_input` does the same with `GraphQL::CoercionError`
+(`extensions: { "input" => { "kind" => "invalid_format", "pattern" => … } }`),
+whose extensions arrive nested under `problems[i].extensions`.
+
+The client then reads `{ "kind" => "out_of_range", "path" => ["input", "min"],
+"coordinate" => "RangeInput.min", "field" => "min", "value" => 0, "details" =>
+{ "min" => 1 }, "message" => "min must be at least 1" }` — a number your form can
+compare against, where without the convention that range failure is `:refused` at
+best, and only if the server stamped `BAD_USER_INPUT`. A server that follows none
+of this degrades; it does not guess.
+
+**You author that `path`, and a validator on a field cannot know its list index.**
+`Validator#validate(object, context, value)` is handed the argument *definition*
+(`validated`, shared by every element), the value, and a context whose
+`current_path` is the **response** path — graphql-ruby coerces a list with a plain
+`map` and keeps no index (measured against 2.6.10). Install the validator above on
+a `qty` inside `lines: [LineInput!]!` and it writes `["input", "qty"]` for every
+element alike, so a 200-line order can't say which line was wrong. Where the index
+matters, install the validator on the **list argument** instead: `value` is then the
+whole coerced Array, so you index it yourself and write
+`["input", "lines", index, "qty"]`. Per-element validators run first, so by then
+every element is fully coerced.
+
+**One problem per call.** `#input_errors` is plural, but neither side collects the
+way `ActiveModel::Errors` does: `coerce` raises on the first field whose value
+won't convert, and graphql-ruby aborts variable validation at the first
+`GraphQL::ExecutionError` a `validates:` rule raises, across the whole input tree.
+The two cases the client does gather are the ones it can see without walking
+further — **unknown keys** and **absent required fields** are listed in full in the
+message (`missing required key(s) for AdoptionInput: name, species`), though
+`#path` names only the first, because a path that points at two fields points at
+neither. So build the form expecting to iterate. The exception is a graphql-ruby
+**coercion** failure, which carries a `problems` array and really does report
+several fields at once.
 
 ## Extending TransportError
 
-What counts as a `TransportError` is an **extensible set** — each transport
-seeds its own network exceptions (`Errno::*`, `SocketError`, timeouts, TLS; the
-Faraday transport adds its own), and you can register more so a custom adapter's
-or connection pool's failure gets the same treatment:
+What counts as a `TransportError` is an **extensible set** — each transport seeds
+its own network exceptions (`Errno::*`, `SocketError`, timeouts, TLS; the Faraday
+transport adds its own), and you can register more so a custom adapter's or
+connection pool's failure gets the same treatment:
 
 ```ruby
 GraphWeaver.register_transport_error(ConnectionPool::TimeoutError)
 GraphWeaver.transport_errors << MyAdapter::ResetError   # it's just a Set
 ```
 
-
 ## Programmatic surfacing
 
 Every error is dual-surface: `#message` for humans, `#to_h` for machines — a
-JSON-ready hash (error class, per-error `path`/`code`/`locations`/`extensions`)
-you can nest straight into a log line or an API response.
+JSON-ready hash (error class, per-error `path`/`code`/`locations`/`extensions`) you
+can nest straight into a log line or an API response.
 
 Field-level tooling lives on both `Response` and `QueryError`:
 
@@ -537,37 +432,34 @@ response.report
 #   nil => { "codes" => ["DOWN"], ... } }   # global errors under nil
 ```
 
-`GraphQLError#field` strips list indices (`people.3.email` → `people.email`) —
-the stable grouping key; the raw `#path` keeps indices for exact location.
+`GraphQLError#field` strips list indices (`people.3.email` → `people.email`) — the
+stable grouping key; the raw `#path` keeps indices for exact location.
 
-`Response#to_h` decomposes the envelope the same way: `{"data" =>, "errors" =>,
-"extensions" =>}`, with each error as its JSON-ready hash. `data` stays the
-typed struct — it is deliberately not re-serialized, because `T::Struct#serialize`
-would give snake_case keys where the wire is camelCase, drop null fields, and
-leave a registered scalar as the Ruby object its codec built. That output would
-look like the server's response without being one, so serialize the typed data
-yourself when you need to re-emit it.
+`Response#to_h` decomposes the envelope the same way, with each error as its
+JSON-ready hash. `data` stays the typed struct, deliberately: `T::Struct#serialize`
+would give snake_case keys where the wire is camelCase, drop null fields, and leave
+a registered scalar as the Ruby object its codec built — output that would look
+like the server's response without being one.
 
 ## Stale schemas
 
-GraphQL has no schema-version signal, so a schema change surfaces as the
-server rejecting your query's shape. `response.schema_stale?` /
-`QueryError#schema_stale?` detect validation-shaped rejections (Apollo's
-`GRAPHQL_VALIDATION_FAILED` code, or the message patterns graphql-ruby and
-GitHub use), and the raised message says what to do: regenerate modules and/or
-refresh the schema cache.
+GraphQL has no schema-version signal, so a schema change surfaces as the server
+rejecting your query's shape. `response.schema_stale?` / `QueryError#schema_stale?`
+detect validation-shaped rejections (Apollo's `GRAPHQL_VALIDATION_FAILED` code, or
+the message patterns graphql-ruby and GitHub use), and the raised message says what
+to do: regenerate modules and/or refresh the schema cache.
 
 ## Cast failures
 
-When wire data disagrees with the types the schema promised at generation time
-(a nil where non-null was declared, a malformed scalar, an unknown enum value),
-casting raises `GraphWeaver::CastError` naming the failing generated struct,
-with the original exception as `#cause`.
+When wire data disagrees with the types the schema promised at generation time (a
+nil where non-null was declared, a malformed scalar, an unknown enum value),
+casting raises `GraphWeaver::CastError` naming the failing generated struct, with
+the original exception as `#cause`.
 
-A cast's own complaint is about the value and nothing else — "invalid date"
-locates nothing on a struct holding four of them — so a casting leaf also
-carries **its response key**, and three failures that keep happening say whose
-bug it is rather than leaving you sorbet's words:
+A cast's own complaint is about the value and nothing else — "invalid date" locates
+nothing on a struct holding four of them — so a casting leaf also carries **its
+response key**, and three failures that keep happening say whose bug it is rather
+than leaving you sorbet's words:
 
 | what came back | what the message adds |
 |---|---|