graph_weaver 0.6.1 → 0.7.0

data/docs/errors.md

@@ -26,6 +26,11 @@ 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.
+
 The envelope is a single generic `GraphWeaver::Response[Result]` — `response.data`
 stays fully typed to *this* query's result, no per-query wrapper class.
 
@@ -40,12 +45,12 @@ subclass says where it failed:
 
 | Class | When |
 |-------|------|
-| `TransportError` | no response came back — DNS, connection refused, TLS, timeout, a socket that died mid-body |
-| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body`, `#headers`, `#retry_after`, `#throttled?` |
-| `QueryError` | 200 body with top-level GraphQL errors — `#errors`, `#data`, `#extensions`, `#codes`, `#throttled?` |
-| `TypeError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
-| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field, wrong number of @oneOf fields — `#field`, `#struct` |
-| `ValidationError` | build time: the query didn't validate against the schema |
+| `TransportError` | no response came back — DNS, connection refused, TLS, timeout, a socket that died mid-body — `#url`, `#cause` |
+| `ServerError` | reached it, non-2xx HTTP — `#status`, `#body`, `#headers`, `#retry_after`, `#throttled?`, `#url` |
+| `QueryError` | a body with top-level GraphQL errors, whatever its status — `#errors`, `#data`, `#extensions`, `#codes`, `#throttled?` |
+| `CastError` | the response wouldn't cast into the generated structs — `#struct`, `#cause` |
+| `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field, wrong number of @oneOf fields — `#kind`, `#path`, `#coordinate`, `#value`, `#details`, `#field`, `#struct` |
+| `QueryValidationError` | build time: the query didn't validate against the schema |
 | `Codegen::Aliases::UnknownSegment` | build time: an [`alias:`](generated_modules.md#flat-accessors-with-alias) path names a field no type here has — a typo, so `optional: true` won't skip it |
 | `ConfigurationError` | setup judged against your schema — which Ruby schema serves which subgraph (`Testing::Router`, `federation:diff`) |
 | `Testing::Unplannable` | the local test router won't plan this operation — `#category`, `#detail` |
@@ -70,15 +75,21 @@ end
 ```
 
 `#throttled?` deliberately spells the same on both: an API may say "slow
-down" with a 429 or with a `THROTTLED` error in a 200 body, and a caller
+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`, and friends); pass that constant to
-`Retry`'s `retry_codes:` instead of hand-writing the strings.
-
-Or skip the hand-rolling: [`Retry`](transports.md#retries) wraps any client and
-already defaults to exactly the policy above — transport failures always,
-`ServerError` on 5xx plus 408/429, and GraphQL error codes you name.
+`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,
@@ -86,6 +97,14 @@ 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
@@ -97,7 +116,9 @@ $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]`. Error messages reach the log at `warn`,
+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)).
 
@@ -113,11 +134,27 @@ input into a 422:
 rescue GraphWeaver::InputError => e
   render json: e.to_h, status: :unprocessable_entity
   # { "error" => "GraphWeaver::InputError",
-  #   "message" => "unknown key(s) for …Input: staus (did you mean 'status'?)",
-  #   "field" => "staus", "struct" => "…Input" }
+  #   "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
@@ -125,6 +162,79 @@ bare `String` where the input goes — reports the same way. A call site that
 as narrow as the schema, and only untyped values reach the runtime check
 ([why](generated_modules.md#variables-become-typed-kwargs)).
 
+### 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:
+
+| | |
+|---|---|
+| `#kind` | one of eight Symbols — `GraphWeaver::InputError::KINDS`. The key an app translates; [i18n](i18n.md) has the table of what each means |
+| `#path` | the route from the variable down, Strings and list indices: `["where", "_and", 0, "_not", "species"]`. Every named segment is the **schema's** spelling — see [which spelling](#which-spelling-a-path-is-in) |
+| `#coordinate` | the [schema coordinate](https://github.com/graphql/graphql-spec/pull/794) for the slot — `"PetFilter.species"`. `nil` when there isn't one |
+| `#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 |
+
+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.
+
+**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.
+
+#### 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.
+
+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:
+
+```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.
+
+**`#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` |
+|---|---|---|
+| `execute(input: {name: "Rex", species: "LIZARD"})` | `["input", "species"]` | `"AdoptionInput.species"` |
+| `execute(input: {issued_on: "x", external_id: "lots"})` — a camelCase field | `["input", "externalId"]` — the schema's spelling | `"InvoiceInput.externalId"` |
+| `execute(where: {_and: [{_not: {species: "LIZARD"}}]})` | `["where", "_and", 0, "_not", "species"]` | `"PetFilter.species"` |
+| `execute(ids: [1, 2, "x"])` — a list of leaves | `["ids", 2]` | `nil` — a list element is a position, not a slot |
+| `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
@@ -137,6 +247,261 @@ 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.
 
+### When the *server* rejects the input
+
+**Nothing here is portable.** The GraphQL spec reserves `extensions` for
+implementors and defines no codes at all, so "this error is about the input you
+sent" is a convention each server invents — or doesn't. graph_weaver reads the
+three it knows by name, and claims nothing from the rest:
+
+| server | what marks an error as being about the input | what you get |
+|---|---|---|
+| **graphql-ruby** | the variable-coercion `problems` array, or one of four rule names in `extensions.code` (`GraphWeaver::GraphQLError::INPUT_CODES`) | the field, and a `kind` read off a closed table of its explanations |
+| **Apollo** | `extensions.code` = `BAD_USER_INPUT` (Apollo Router's `VALIDATION_INVALID_TYPE_VARIABLE` is not read; graphql-js sends no `extensions` at all) | `:refused` with the server's sentence, and the field only where `argumentName` is stated |
+| **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.
+
+Generated modules always send **variables**, never literals, which narrows a
+graphql-ruby server to two shapes (measured against 2.6.10):
+
+| the server's rejection | what arrives | `#input_errors` |
+|---|---|---|
+| the variable didn't coerce — wrong type, not an enum member, a required field null, a key the input type doesn't define, a custom scalar's `GraphQL::CoercionError` | a **request** error: no `data` key at all, one error with no `path`, and `extensions` = `{"value" => «the whole variable», "problems" => [{"path" => ["level2","count"], "explanation" => "Could not coerce value \"nope\" to Int"}]}` — but **no `code`** | one per problem, `kind` from a table over `explanation`, `path` = `[variable, *problem.path]` |
+| 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.
+
+**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
+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.
+
+#### 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:
+
+```ruby
+response = AdoptMutation.execute(input: params[:pet])
+
+if response.input_errors.any?
+  response.input_errors.each { |e| form.errors.add(e.field&.underscore || :base, e.message) }
+elsif response.errors.any?
+  # nothing claimed to be about the input: show what was said, and log the
+  # rest — #extensions is where a server you're onboarding states its own
+  # convention, and the next section is how to make it one this reads
+  flash[:alert] = response.errors.map(&:message).join(", ")
+  Rails.logger.warn(response.report)
+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:
+
+```json
+"extensions": {
+  "code": "BAD_USER_INPUT",
+  "input": {
+    "kind": "out_of_range",
+    "path": ["input", "min"],
+    "coordinate": "RangeInput.min",
+    "value": 0,
+    "min": 1
+  }
+}
+```
+
+`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.
+
+```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
+```
+
+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.
+
 ## Extending TransportError
 
 What counts as a `TransportError` is an **extensible set** — each transport
@@ -196,7 +561,7 @@ refresh the schema cache.
 
 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::TypeError` naming the failing generated struct,
+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"