graph_weaver 0.5.1 → 0.6.1

data/docs/testing.md

@@ -1,5 +1,10 @@
 # Testing
 
+How to run a spec that executes a GraphQL query without a server — against
+fabricated data, against your own resolvers, or across a federated graph. Read
+this once when you set the suite up; after that the one thing to remember is
+the `graphql:` tag.
+
 One line in your spec helper:
 
 ```ruby
@@ -24,9 +29,9 @@ it "authorizes drafts",       graphql: :in_process do … end
 
 | mode | reach for it when | what it costs |
 |---|---|---|
-| `graphql: :fake` | most unit tests — you need *a* well-shaped response | no resolver code runs |
-| `graphql: :in_process` | the point of the test is that your resolver logic works | slower; needs a live schema class |
-| `graphql: :router` | the same, across a federated graph | needs a composed supergraph; [refuses](federation.md#what-it-refuses) shapes it can't plan faithfully |
+| [`:fake`](#fabricated-data--graphql-fake) | most unit tests — you need *a* well-shaped response | no resolver code runs |
+| [`:in_process`](#real-resolvers--graphql-in_process) | the point of the test is that your resolver logic works | slower; needs a live schema class |
+| [`:router`](#a-federated-graph--graphql-router) | the same, across a federated graph | needs a composed supergraph; [refuses](federation.md#what-it-refuses) shapes it can't plan faithfully |
 | [cassettes](cassettes.md) | pinning a real server's exact response | must be re-recorded when the query changes |
 
 The tag installs its client as `GraphWeaver.client` for that example, so
@@ -46,14 +51,19 @@ tagged one:
 before { GraphWeaver.client = GraphWeaver::Testing::Failure.throttled }
 ```
 
-Everything here is a *client* — the one interface queries run through:
-anything with `execute(query, variables:, operation_name:)` returning
-`{"data" => ..., "errors" => ...}` (see [transports](transports.md)). Fakes,
-the router, failures, and cassettes all slot in wherever a real transport
-would, so they work outside rspec too (`require "graph_weaver/testing"` —
-never from production code). Outside the tags there's no `GraphWeaver.client`
-to lean on, so parse from the fake or the router itself — anything holding a
-schema parses against it, and the module runs on what parsed it:
+Both at once and the assignment wins: the tag installs its client from a
+suite-level `before`, which rspec runs ahead of any group hook. So a tagged
+example with a `before` of its own runs against the client the `before`
+built — tag the group for the mode, override the one example that needs
+something else.
+
+Everything here is a *client* — the one interface queries run through (the
+contract is in [transports](transports.md)). Fakes, the router, failures and
+cassettes all slot in wherever a real transport would, so they work outside
+rspec too (`require "graph_weaver/testing"` — never from production code).
+Outside the tags there's no `GraphWeaver.client` to lean on, so parse from
+the fake or the router itself — anything holding a schema parses against it,
+and the module runs on what parsed it:
 
 ```ruby
 router = GraphWeaver::Testing::Router.new(supergraph: "app/graphql/supergraph.graphql")
@@ -72,9 +82,6 @@ looked for — rather than guessing**:
 
 - **the schema** is `config.schema` if you set one, else the committed dump
   at `GraphWeaver.schema_path`, else the schema `GraphWeaver.client` talks to.
-  (A federated app has no one schema class, so `config.schema` is the whole
-  graph's shape and an example names the subgraph whose resolvers it wants —
-  see `graphql_in_process` below.)
 - **`:in_process`** needs the live schema *class*, since only that has
   resolvers: the one your client already runs in-process, else the loaded
   class that defines everything the schema declares — the same
@@ -96,84 +103,95 @@ GraphWeaver::Testing.configure do |config|
   # config.context = { tenant: }     # baseline context every example starts from
   # config.default_mode = :fake      # what an UNtagged example runs against
   #                                  # (graphql: false opts one back out)
-  # config.mode = :faker             # or :literal (plain typed values); nil = auto
-  # config.overrides = { "Person.name" => "Daniel" }
+  # config.seed = 4242               # defaults to rspec's own --seed
+  # config.overrides = { "Money" => "12.00", "Person.name" => "Daniel" }
   # config.list_size = 1..3
-  # config.null_chance = 0.1         # nullable fields go nil sometimes
-end
-```
-
-## The context your resolvers see
-
-`graphql_context` is available in every example. It **merges** onto
-`config.context` — the baseline survives unless you override a key — and is
-**reset before the next example**, so one example running as somebody else
-can't leak into the one after it.
-
-Context is setup, so it usually belongs in a `before` block — a group of
-examples sharing one identity says who they are once:
-
-```ruby
-describe "as the owner", graphql: :in_process do
-  before { graphql_context(current_user: alice) }
-
-  it "shows the drafts" do
-    expect(DraftsQuery.execute!.drafts.size).to eq 2
-  end
-
-  it "counts them" do … end
-end
-```
-
-The reset runs ahead of any group hook, so each example re-applies that
-`before` from the same baseline rather than stacking onto the last one's
-context. Set it inline for the one-off:
-
-```ruby
-it "shows the owner's drafts", graphql: :in_process do
-  graphql_context(current_user: alice)
-  expect(DraftsQuery.execute!.drafts.size).to eq 2
 end
 ```
 
-Pass a block to scope it, for the example that needs two identities:
-
-```ruby
-graphql_context(admin: true) { expect(SettingsQuery.execute!.settings).to be_present }
-```
+Anything whose honest answer differs per example belongs on the fake instead
+— `graphql_fake(null_chance: 1.0)` for the example that's about an empty
+state, `graphql_fake(values: :literal)` for the one that reads better without
+faker's prose. A suite-wide `null_chance` would sprinkle nils through every
+*other* example, one run in ten, on a seed the failure doesn't name.
 
-Called with nothing it reads the context back. Under `graphql: :fake` it
-refuses: there are no resolvers to receive a context, and silently ignoring
-one would leave an example asserting on data nothing scoped. Pin the data
-itself instead — `graphql_fake(overrides: …)`, below.
+Need the schema itself inside an example — to sample a field, or build a
+query on the fly? The client in play exposes it as
+`GraphWeaver.client.schema`, and `GraphWeaver::Testing.config.schema` reads
+back what `config.schema =` set, falling back to the committed dump.
 
 ## Fabricated data — `graphql: :fake`
 
 `FakeClient` fabricates schema-correct responses for whatever query
-arrives: real enum values, valid `__typename` members, iso8601 date scalars
-— every fake casts cleanly through your generated structs.
+arrives: real enum values, valid `__typename` members, and — for a custom
+scalar — a value the Ruby type you registered it as can hold, so every fake
+casts cleanly through your generated structs. `@skip`/`@include` are
+evaluated against the variables you passed (defaults included), so a field
+the server would leave out is left out. `rspec --seed 1234` reproduces the
+values along with test order.
 
 ```ruby
 fake = GraphWeaver::Testing::FakeClient.new   # schema: falls back to Testing.config
 
 person = PersonQuery.execute!(client: fake, id: "1").person
-person.name       # => "Eliza Kertzmann" (faker-matched on field name, when faker is loaded)
-person.birthday   # => a real Date
+person.name       # a plausible name, when faker is loaded
+person.birthday   # a real Date
 ```
 
-Pin what matters, keyed by GraphQL names (schema vocabulary — keys
-survive query refactors); `"Type.field"` beats `"field"`:
+Values are semantic when the [faker](https://github.com/faker-ruby/faker) gem
+is loaded — `name` gets a name, `email` an email — and plain and type-derived
+(`"name-1"`, seeded numbers) when it isn't. Say `values: :literal` on a fake
+that reads better without the prose, or `values: :faker` to insist on the
+semantic ones and get told if the gem is missing:
 
 ```ruby
-GraphWeaver::Testing::FakeClient.new(schema:, overrides: {
-  "Person.name" => "Daniel",
-  "email" => -> { "test@example.com" },
-})
+graphql_fake(values: :literal)
+GraphWeaver::Testing::FakeClient.new(values: :literal)
 ```
 
-Keys are checked against the schema, spellchecked — `"Person.nmae"` raises
-rather than quietly pinning nothing and leaving the example green against
-random data.
+### Pins
+
+**A pin says what the fake uses instead of inventing a value** — keyed by a
+scalar type, an object type, or a field; worth a wire value, an object the fake
+reads the selected fields off, or a proc handed the seeded `Random`:
+
+```ruby
+graphql_fake("Money" => "12.00",            # every Money field, however deep
+             "Person" => build(:person),    # the selected fields, read off the object
+             "Order.total" => "999.00")     # this one field — and it beats the type's pin
+```
+
+Keys are schema vocabulary, so they survive query refactors — a type name, or
+`"Type.field"` (a bare `"field"` pins it on every type) — and they are checked
+and spellchecked: `"Person.nmae"` raises rather than quietly pinning nothing
+and leaving the example green against random data.
+
+An **object pin** is anything answering the field names — a FactoryBot build, a
+model, a `Struct`, an `OpenStruct`. For each selected field the fake calls the
+snake_cased reader, puts a Ruby value on the wire the way its
+[scalar registration](scalars.md) serializes it (a `Time` as its iso8601 string,
+a `T::Enum` as its value), recurses into nested objects and arrays of them, and
+**fabricates any field the object doesn't answer**. Readers are field names, not
+aliases; `__typename` comes from the key, so at a union or interface pin the
+concrete type (`"Person"`, never `"Named"`). One thing rspec's seed can't reach:
+a FactoryBot sequence advances on its own counter, so an object built from one
+isn't reproduced by `--seed`.
+
+A **scalar type pin** is the one thing a scalar registered as *your own class*
+needs — only `Money.parse` knows what wire value it accepts — so without one
+fabrication refuses at the path it reached (`at reader.orders.0.total`) and
+names the pin to add, rather than feeding your cast a placeholder that fails
+deep inside `from_h`. A scalar registered as `BigDecimal`, `Time`, `Date`,
+`Integer`, `Float`, `String` or `T::Boolean` needs nothing. Suite-wide, the same hash is
+`config.overrides`, and the [cassette anonymizer](cassettes.md) reads it too.
+
+Pins lead and options follow — `graphql_fake("Money" => "12.00", values:
+:literal)`. Options are lowercase words, so a key with a dot or a leading
+capital is a pin wherever it is written; `overrides:` takes the same hash by
+keyword, and the leading pins win where both name a key. A fake refuses an
+option it doesn't take, lists the ones it does, and guesses at what you meant —
+at every door: `FakeClient.new`, `graphql_fake`, `Router.new(fake:)` and
+`graphql_router(fake:)`.
 
 ### The example that's *about* the data
 
@@ -183,10 +201,8 @@ the example can say what it needs:
 
 ```ruby
 it "shows the two paid orders", graphql: :fake do
-  graphql_fake(overrides: {
-    "Reader.name" => "Ada",
-    "Reader.orders" => [{ "status" => "PAID" }, {}],
-  })
+  graphql_fake("Reader.name" => "Ada",
+               "Reader.orders" => [{ "status" => "PAID" }, {}])
 
   expect(DashboardQuery.execute!.reader.orders.size).to eq 2
 end
@@ -217,21 +233,26 @@ with no tag at all, since it installs the client itself. The tag is
 One thing to know: **two identical queries fabricate different data**, so
 assert a memoization with `requests.size`, not by comparing two responses.
 
-### Naming the schema your resolvers run on
+## Real resolvers — `graphql: :in_process`
 
-`graphql_in_process` is the same idea for real resolvers. The tag runs
-`config.schema` when that's a live class, which is the whole story for an app
-that serves the API it calls:
+Your actual resolvers, your actual `context`, in the same process — no
+socket, no serialization, and a resolver's real backtrace when it raises.
 
 ```ruby
-it "hides another reader's drafts", graphql: :in_process do
-  expect(DraftsQuery.execute!.drafts.map(&:id)).to eq %w[d3]
+it "hides other people's drafts", graphql: :in_process do
+  graphql_context(current_user: alice)
+  expect(DraftsQuery.execute!.drafts.map(&:owner)).to all(eq alice.name)
 end
 ```
 
+The live schema *class* is found for you (a schema dump has no resolvers,
+so it won't do). If two loaded classes match, or none does, it says so and
+asks for `config.schema = MySchema` — and in Rails, remember that an
+autoloaded schema isn't loaded until something references it.
+
 A federated app has no one live class, so the example says which subgraph it
-means — testing one subgraph's resolvers directly is a different question from
-`graphql: :router`, which plans across the whole graph and stitches. Both are
+means. Testing one subgraph's resolvers directly is a different question from
+`graphql: :router`, which plans across the whole graph and stitches; both are
 worth asking, and a suite asks them of different subgraphs:
 
 ```ruby
@@ -241,52 +262,95 @@ it "rejects a review from a blocked reader" do
 end
 ```
 
-Like `graphql_fake`, it needs no tag, works in a `before` block, and is
-restored after the example. Set the GraphQL context with `graphql_context`
-rather than the helper's `context:` — the helper's is a baseline, and
-`graphql_context` is what merges onto it per example.
+Like `graphql_fake`, `graphql_in_process` needs no tag, works in a `before`
+block, and is restored after the example.
 
-`rspec --seed 1234` reproduces fake data along with test order. `config.mode`
-picks value fabrication: `:faker` (semantic, field-name matched — raises if
-the gem is missing), `:literal` (plain type-derived), or nil to auto-detect
-faker.
+### The context your resolvers see
 
-Need the schema itself inside an example — to sample a field, or build a
-query on the fly? The client in play exposes it as
-`GraphWeaver.client.schema`, and `GraphWeaver::Testing.config.schema` reads
-back what `config.schema =` set, falling back to the committed dump.
+`graphql_context` is available in every example. It **merges** onto
+`config.context` — the baseline survives unless you override a key — and is
+**reset before the next example**, so one example running as somebody else
+can't leak into the one after it. (Use it rather than the
+`graphql_in_process(context:)` baseline, which is per-suite.)
 
-Test-only generated modules don't have to live in `app/` — `generated_paths` is
-an appendable list, so a support file can register a spec-local set:
+Context is setup, so it usually belongs in a `before` block — a group of
+examples sharing one identity says who they are once:
 
 ```ruby
-# spec/support/graph_weaver.rb
-GraphWeaver.generated_paths << "spec/graphql/generated"
-GraphWeaver.load_generated!   # the appended path needs this call
+describe "as the owner", graphql: :in_process do
+  before { graphql_context(current_user: alice) }
+
+  it "shows the drafts" do
+    expect(DraftsQuery.execute!.drafts.size).to eq 2
+  end
+end
 ```
 
-Both lines matter. In Rails the Railtie loads generated modules during boot,
-which is finished before `spec/support/*.rb` runs — so a path appended here is
-never loaded unless you load it. And keep the directory *outside*
-`spec/support/`: rspec-rails requires every `spec/support/**/*.rb` itself, in
-sorted order, so a generated module gets required before the shared `types.rb`
-it needs and dies on `LoadError`.
+The reset runs ahead of any group hook, so each example re-applies that
+`before` from the same baseline rather than stacking onto the last one's
+context. Set it inline for the one-off, or pass a block to scope it for the
+example that needs two identities:
+
+```ruby
+graphql_context(admin: true) { expect(SettingsQuery.execute!.settings).to be_present }
+```
+
+Called with nothing it reads the context back. Under `graphql: :fake` it
+refuses: there are no resolvers to receive a context, and silently ignoring
+one would leave an example asserting on data nothing scoped. Pin the data
+itself instead — `graphql_fake("Person.name" => "Ada")`, above.
+
+## A federated graph — `graphql: :router`
+
+Same thing across a federated graph: the tag builds a
+[`Testing::Router`](federation.md#the-local-router), which plans the query
+across your subgraphs and runs it against those **real resolvers** — no
+gateway, no node, no sockets.
+
+```ruby
+describe "the dashboard", graphql: :router do
+  it "stitches a user's reviews" do
+    graphql_context(current_user: user)
+    expect(DashboardQuery.execute!.me.reviews.size).to eq 2
+  end
+end
+```
+
+The router is built once for the suite (parsing a supergraph per example
+would be real time) and installed as `GraphWeaver.client` for each; its
+context is reset from `config.context` every time.
+
+`graphql_router` is the tag with options, the way `graphql_fake` is — one
+option, `fake:`, saying how the subgraphs the router
+[fakes](federation.md#a-supergraph-only-partly-local) fabricate: the pins and
+options `graphql_fake` takes, in one hash:
+
+```ruby
+graphql_router(fake: { "Shipment.carrier" => "UPS", list_size: 2 })
+```
+
+What it plans, what it **refuses** and why, how subgraphs are matched to your
+schema classes, and what to do about a supergraph only partly local:
+**[federation → the local router](federation.md#the-local-router)**.
 
 ## Simulating failures
 
-Every failure mode is just a client, so
-error-handling paths are testable without a server that misbehaves on cue:
+Every failure mode is just a client, so error-handling paths are testable
+without a server that misbehaves on cue:
 
 ```ruby
 Failure = GraphWeaver::Testing::Failure
 
-PersonQuery.execute(client: Failure.transport, id: "1")            # TransportError (cause preserved)
-PersonQuery.execute(client: Failure.server(status: 502), id: "1")  # ServerError
-PersonQuery.execute(client: Failure.throttled, id: "1")            # QueryError, code THROTTLED
+PersonQuery.execute(client: Failure.transport, id: "1")            # raises TransportError
+PersonQuery.execute(client: Failure.server(status: 502), id: "1")  # raises ServerError
+PersonQuery.execute(client: Failure.throttled, id: "1")            # errors.first.code => "THROTTLED"
 PersonQuery.execute(client: Failure.stale_schema, id: "1")         # schema_stale? => true
 PersonQuery.execute(client: Failure.graphql("boom"), id: "1")      # partial failure
 
-# retries: clients run in sequence (the last repeats) — here, two
+# a throttling server, with the header a backoff reads
+PersonQuery.execute(client: Failure.server(status: 429, headers: { "retry-after" => "2" }), id: "1")
+
+# testing a retry — clients run in sequence, the last one repeating: two
 # transport failures and then a FakeClient serving good responses
 fake = GraphWeaver::Testing::FakeClient.new(schema:)
 GraphWeaver::Testing::Sequence.new(Failure.transport, Failure.transport, fake)
@@ -302,8 +366,8 @@ GraphWeaver::Testing::FakeClient.new(schema:, fail_at: { path: "person.email", c
 
 ## Capture and replay
 
-Cassettes record real API responses and replay
-them offline, above the transport (no HTTP interception):
+Cassettes record real API responses and replay them offline, above the
+transport (no HTTP interception):
 
 ```ruby
 # records against the live client when the file is missing, replays after
@@ -315,44 +379,20 @@ response is scrubbed on its way to disk — the query and its variables are the
 replay key and are recorded verbatim, so read a cassette before committing it.
 The full workflow guide is **[cassettes](cassettes.md)**.
 
-## Real resolvers, one schema — `graphql: :in_process`
-
-Your actual resolvers, your actual `context`, in the same process — no
-socket, no serialization, and a resolver's real backtrace when it raises.
-
-```ruby
-it "hides other people's drafts", graphql: :in_process do
-  graphql_context(current_user: alice)
-  expect(DraftsQuery.execute!.drafts.map(&:owner)).to all(eq alice.name)
-end
-```
-
-The live schema *class* is found for you (a schema dump has no resolvers,
-so it won't do). If two loaded classes match, or none does, it says so and
-asks for `config.schema = MySchema` — and in Rails, remember that an
-autoloaded schema isn't loaded until something references it.
-
-## A federated graph — `graphql: :router`
+## Test-only generated modules
 
-Same thing across a federated graph: the tag builds a
-[`Testing::Router`](federation.md#the-local-router), which plans the query
-across your subgraphs and runs it against those **real resolvers** — no
-gateway, no node, no sockets.
+They don't have to live in `app/` — `generated_paths` is an appendable list,
+so a support file can register a spec-local set:
 
 ```ruby
-describe "the dashboard", graphql: :router do
-  it "stitches a user's reviews" do
-    graphql_context(current_user: user)
-    expect(DashboardQuery.execute!.me.reviews.size).to eq 2
-  end
-end
+# spec/support/graph_weaver.rb
+GraphWeaver.generated_paths << "spec/graphql/generated"
+GraphWeaver.load_generated!   # the appended path needs this call
 ```
 
-The router is built once for the suite (parsing a supergraph per example
-would be real time) and installed as `GraphWeaver.client` for each; its
-context is reset from `config.context` every time, so an example that runs
-as someone else can't leak into the next.
-
-What it plans, what it **refuses** and why, how subgraphs are matched to your
-schema classes, and what to do about a supergraph only partly local:
-**[federation → the local router](federation.md#the-local-router)**.
+Both lines matter. In Rails the Railtie loads generated modules during boot,
+which is finished before `spec/support/*.rb` runs — so a path appended here is
+never loaded unless you load it. And keep the directory *outside*
+`spec/support/`: rspec-rails requires every `spec/support/**/*.rb` itself, in
+sorted order, so a generated module gets required before the shared `types.rb`
+it needs and dies on `LoadError`.

data/docs/transports.md

@@ -1,5 +1,10 @@
 # Transports
 
+Where queries actually go: what fills the client slot, how to build and tune the
+bundled HTTP transports, and how a generated module decides which one to use.
+Read it when the default one-liner isn't enough — custom headers, mTLS, Faraday
+middleware, retries, or connection pooling under load.
+
 A *client* is anything with `execute(query, variables:, operation_name:)` whose result
 `to_h`s into `{"data" => ..., "errors" => ...}` — from a full
 `GraphWeaver::Client` down to a schema class
@@ -40,8 +45,9 @@ contract itself, so it goes anywhere a transport does — `Retry.new(client)`,
   scheme (`"Basic dXNlcjpwYXNz..."`)
 - `transport:` — `:http` (the default) or `:faraday`
 - `headers:` — anything else (API keys, custom headers)
-- `retries:` — off by default; `true` for a `Retry` with defaults,
-  or a Hash of its options
+- `retries:` — off by default; a count (`retries: 3`), or `true` for the
+  default count. Every other [`Retry`](#retries) option sits beside it
+  (`backoff:`, `retry_codes:`, ...)
 - `open_timeout:` / `read_timeout:` — seconds, defaulting to 10 and 30 on
   either transport
 - `cache:` / `ttl:` — schema introspection caching (see
@@ -149,6 +155,11 @@ warmest one; requests beyond that queue for a free slot rather than
 opening unbounded connections. A socket that errors is closed and its slot
 left empty, so the next call reconnects.
 
+A url client introspects its schema lazily, and the first requests of a cold
+process arrive together — so that fetch is done **once**, by whoever asks
+first, with the rest waiting on it rather than each making its own round trip
+and writing its own copy of the schema cache.
+
 `pool_size:` defaults to `RAILS_MAX_THREADS` (else 5) — the same variable
 Rails sizes its own connection pool from, because it is the same question:
 how many requests this process can have in flight at once. Lower it for a
@@ -173,35 +184,54 @@ takes a `Client` or any bare transport/fake):
 3. baked constant: `Codegen.generate(..., client: MyApi::CLIENT)`
 4. the app default: `GraphWeaver.client=`
 
-Nothing set anywhere raises with a message saying which knobs exist.
+Nothing set anywhere raises, naming the two you'd usually reach for:
+`no client configured — set GraphWeaver.client= or pass a client`.
 
 ## Retries
 
-`Retry` wraps any client/transport:
+A url client retries when you give it a count; the rest of the options
+sit beside it:
 
 ```ruby
-GraphWeaver::Retry.new(
-  inner_transport,
-  tries: 5,                        # total attempts, first included
+GraphWeaver.new(
+  url,
+  retries: 5,                      # attempts after the first
   backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
-  base: 0.5, max: 30,              # seconds; delays clamp at max:
+  base_delay: 0.5, max_delay: 30,  # seconds; delays clamp at max_delay:
   jitter: true,                    # randomize each delay by 50-100%
-  on: [GraphWeaver::TransportError, GraphWeaver::ServerError],
-  retry_if: ->(error) { ... },     # fine-grain within on:
+  retry_on: [GraphWeaver::TransportError, GraphWeaver::ServerError],
+  retry_if: ->(error) { ... },     # fine-grain within retry_on:
   retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
+  retry_mutations: false,          # true if your mutations are idempotent
 )
 ```
 
-Defaults: transport failures always retry (the request never arrived);
-`ServerError` on 5xx plus **408 and 429** — the rest of 4xx is a bug in
-the request, retrying won't fix it. `retry_codes:` re-inspects response
-envelopes so GraphQL-level throttling can retry too (off by default —
-pass the codes your API uses). Exhausting `tries:` re-raises the last
-error (or returns the last code-matched response).
+`GraphWeaver::Retry.new(inner_transport, ...)` takes the same options and
+wraps any client/transport directly — the client just passes them along.
+
+Defaults: transport failures always retry; `ServerError` on 5xx plus
+**408 and 429** — the rest of 4xx is a bug in the request, retrying
+won't fix it. `retry_codes:` re-inspects response envelopes so
+GraphQL-level throttling can retry too (off by default — pass the codes
+your API uses). Exhausting the retries re-raises the last error (or
+returns the last code-matched response).
+
+`retries:` counts the attempts *after* the first, so
+`GraphWeaver.new(url, retries: 3)` makes up to four and `retries: 0` never
+retries; `retries: true` takes `Retry`'s own default of 2. Every misspelling
+raises rather than quietly doing nothing — a retry option passed without a
+count says so, and the old Hash form (`retries: { retries: 5 }`) names its
+flat replacement.
+
+**A mutation gets one attempt.** A failure with no answer — a read
+timeout, a 502, a reset socket — does not say whether the server applied
+it, and a second `charge` is worse than a failed one.
+`retry_mutations: true` opts an idempotent API back in; the skipped
+retry says so on the logger.
 
 **`Retry-After` wins over the backoff.** When the server names a delay
 (seconds or an HTTP-date), that's the wait — the server is the only
-party that knows when its window reopens. It's clamped to `max:` so a
+party that knows when its window reopens. It's clamped to `max_delay:` so a
 "come back in an hour" can't park a thread for an hour, and not
 jittered, since it's an instruction rather than a guess.
 
@@ -217,7 +247,5 @@ rescue GraphWeaver::ServerError => e
 end
 ```
 
-Or via the client: `GraphWeaver.new(url, retries: { tries: 5, retry_codes: ["THROTTLED"] })`.
-
 What classifies as a transport failure is an extensible set — see
 [errors](errors.md#extending-transporterror) (`GraphWeaver.register_transport_error`).