graph_weaver 0.7.4 → 0.7.6

data/docs/logging.md

@@ -13,8 +13,8 @@ Pick the level, get the story:
 
 | Level | What you see |
 |-------|--------------|
-| `debug` | the wire: query + variables per call (long queries truncated), response status/bytes/content type, request timing, connection open/drop, dynamically parsed modules |
-| `info` | one line per operation in Rails (see [Instrumentation](#instrumentation)), schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
+| `debug` | the wire: query + variables per call (long queries truncated), response status/bytes/content type, request timing, one line per attempt (its url status and which retry it was), connection open/drop, dynamically parsed modules |
+| `info` | one line per call in Rails (see [Instrumentation](#instrumentation)), schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
 | `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `QueryValidationError`, `CastError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
 | `error` | development only: a `.graphql` edit that won't compile, with its file and position — the modules already loaded keep serving |
 
@@ -61,9 +61,10 @@ value, since `expected an Int, got "lots"` is the whole diagnosis.
 ## Instrumentation
 
 A logger tells a human what happened; an APM needs to time it and count it.
-`GraphWeaver.instrumenter` is one callable wrapping every request — over the wire
-*and* in-process. **In Rails you set nothing**: the railtie installs the adapter
-below and attaches `GraphWeaver::LogSubscriber` on top of it. Everywhere else:
+`GraphWeaver.instrumenter` is one callable wrapping every call GraphWeaver
+makes — over the wire *and* in-process. **In Rails you set nothing**: the
+railtie installs the adapter below and attaches `GraphWeaver::LogSubscriber` on
+top of it. Everywhere else:
 
 ```ruby
 GraphWeaver.instrumenter = lambda do |event, payload, &block|
@@ -76,40 +77,74 @@ An instrumenter you set yourself is never replaced — including
 and return its value; a failure propagates through it, so the hook sees the
 exception and can record it.
 
-The one event is `GraphWeaver::EXECUTE_EVENT` (`"execute.graph_weaver"`) — one
-request, start to parsed response, whichever client slot served it:
+There are two events, and the second happens inside the first:
+
+| Event | One of these is |
+|-------|-----------------|
+| `GraphWeaver::OPERATION_EVENT` (`"operation.graph_weaver"`) | one call of a generated module's `execute`/`execute!`, start to typed result or raise — the request it made, every retry and backoff beneath it, and the cast into your structs |
+| `GraphWeaver::EXECUTE_EVENT` (`"execute.graph_weaver"`) | one request, start to parsed response, whichever client slot served it — so a call a [`Retry`](transports.md#retries) took three goes at is one operation event and three of these |
+
+**Alert on the operation event**: it is the one that says what the *caller*
+got. A `CastError` is raised after the response is back, so the request has
+already closed `:ok` by the time the app sees a failure. It also fires at the
+module seam, which every client slot passes through — a [test mode's](testing.md)
+fake, the router and a cassette all report here, so a spec can assert on
+instrumentation under any `graphql:` tag.
 
 ```ruby
-ActiveSupport::Notifications.subscribe(GraphWeaver::EXECUTE_EVENT) do |*, payload|
+ActiveSupport::Notifications.subscribe(GraphWeaver::OPERATION_EVENT) do |*, payload|
   StatsD.timing("graphql.#{payload[:operation] || "anonymous"}", payload[:duration_ms],
     tags: ["status:#{payload[:status]}", "kind:#{payload[:kind]}", "code:#{payload[:code]}"])
 end
 ```
 
-**A subscriber that raises takes the request down with it** — the response was
+Two calls don't produce one. `from_response` on its own reports nothing — no
+call was made. And a module generated by 0.7.5 or earlier shows this seam
+only half of one, so it emits the request event alone until you regenerate:
+half a call reported `:ok` is the very thing the event exists to stop.
+
+**A subscriber that raises takes the call down with it** — the response was
 computed and is then thrown away. That is `ActiveSupport::Notifications`' own
 semantics, the same on `sql.active_record`, so rescue inside the block. A
 `GraphWeaver::LogSubscriber` subclass already does.
 
-### The payload
+### The operation payload
 
 | Key | When | |
 |-----|------|--|
 | `:operation` | always | the operation name sent with the request, nil for an anonymous document — what a trace keys on (a generated module always has one) |
-| `:client` | always | the class that ran it: `GraphWeaver::Transport::HTTP`, `GraphWeaver::InProcess`, your own |
+| `:module` | always | the generated module's name, as a String — `nil` for one with no name (a [`GraphWeaver.parse`](getting_started.md)). The fact this seam has and the request doesn't: two graphs can name the same operation, and a trace that is slow wants the file |
+| `:graph` | always | the [graph](getting_started.md#more-than-one-schema) the module was declared under, as a Symbol — `nil` for a module that names none. Never inferred from the client |
 | `:kind` | always | `:query`, `:mutation` or `:subscription` — what the document runs, so a write failure rate is a payload question rather than a guess at the operation's name. The shorthand `{ ... }` document is a `:query`. The same reading decides whether [`Retry`](transports.md#retries) may repeat the request |
+| `:client` | always | the client the module **resolved to**: a test mode's stand-in names itself, a graph's client names itself, and over the wire it is `GraphWeaver::Client` — the request event beneath names the transport that carried it |
+| `:status` | always | `:ok` (a typed result), `:errors` (the response carried GraphQL errors — what `execute!` raises `QueryError` for), or `:failed` (the call raised: the transport, a `CastError`, anything) |
+| `:duration_ms` | always | the caller's wall clock — dispatch, every retry *and its backoff*, and the cast |
+| `:code` | on `:errors` | the machine-readable reason, as on the request event |
+| `:error` | on `:failed` | the exception's class name |
+
+Not on it: `:url`, `:http_status`, `:retries`. Those describe one attempt, and
+a call that took three goes has no single answer for any of them — read them
+off the request events nested inside.
+
+### The request payload
+
+| Key | When | |
+|-----|------|--|
+| `:operation` | always | the operation name sent with the request, nil for an anonymous document |
+| `:client` | always | the class that ran it: `GraphWeaver::Transport::HTTP`, `GraphWeaver::InProcess`, your own |
+| `:kind` | always | `:query`, `:mutation` or `:subscription`, read off the document |
 | `:status` | always | `:ok`, `:errors` (a response carrying GraphQL errors), or `:failed` (it raised) |
-| `:duration_ms` | always | start to parsed response, for **this attempt** — under a [`Retry`](transports.md#retries) no event covers the backoff sleep, so a tracer recovers the caller's wall clock from the sibling spans instead: the first attempt's start to the last one's end |
+| `:duration_ms` | always | start to parsed response, for **this attempt** — the backoff between attempts belongs to the operation event above, which is where the caller's wall clock lives |
 | `:url` | over the wire | the endpoint; nil in-process |
 | `:http_status` | over the wire | what the server answered with, success or not; nil in-process |
 | `:schema` | in-process | the schema class's name, as a String, so a payload logs as it stands |
 | `:code` | on `:errors` | the machine-readable reason, always a String or `nil` — the first `extensions.code` *any* of the errors carries, not the first error's, since a code that exists beats the absence of one at position 0. Present and `nil` when the errors carry none. Never an HTTP status: that is `:http_status` |
 | `:error` | on `:failed` | the exception's class name |
 | `:retries` | under a `Retry` | how many retries this attempt follows. Each attempt is its own event, so one retried call is three events reading 0, 1, 2 — present at 0 rather than absent, so its absence means nothing was retrying |
-| `:graph` | always | the [graph](getting_started.md#more-than-one-schema) the generated module was declared under, as a Symbol — `nil` for a module that names none, and for a client called directly. Never inferred from the client: a wrong graph on a request is worse than no graph |
+| `:graph` | always | the same label the operation above it carries, and `nil` for a request no generated module made — a client called directly. Never inferred from the client: a wrong graph on a request is worse than no graph |
 
-Every key is filled in before your callable's block returns, so a subscriber reads
-a complete payload; `ActiveSupport::Notifications` adds `:exception` and
+Every key is filled in before your callable's block returns, so a subscriber
+reads a complete payload; `ActiveSupport::Notifications` adds `:exception` and
 `:exception_object` of its own when the block raises.
 
 **`:graph` labels one request**, never what a *server* does while answering one:
@@ -117,33 +152,35 @@ an in-process resolver that calls out produces an event of its own. The label is
 fiber-local, so a dispatch that crosses a `Fiber` — graphql-ruby's `Dataloader`
 does — arrives with `:graph` unset. No label rather than a wrong one.
 
-**Never the query text or the variables**: the payload fans out to subscribers
-that know none of the filtering rules, so the rule here isn't "scrub it", it's
-that it was never there. `:url` is the one thing on the payload that *is*
-scrubbed, because a url can itself be a credential — and the default names apply
-to its query parameters even when you have emptied or narrowed
-`filter_parameters`. Your list widens that; it can't narrow it.
+**Never the query text or the variables**, on either event: the payload fans out
+to subscribers that know none of the filtering rules, so the rule here isn't
+"scrub it", it's that it was never there. `:url` is the one thing on either
+payload that *is* scrubbed, because a url can itself be a credential — and the
+default names apply to its query parameters even when you have emptied or
+narrowed `filter_parameters`. Your list widens that; it can't narrow it.
 
 ### One line per operation
 
-In Rails the railtie also attaches `GraphWeaver::LogSubscriber`, which turns each
-event into one line — the shape ActiveRecord uses for a query:
+In Rails the railtie also attaches `GraphWeaver::LogSubscriber`, which turns
+each operation event into one line — the shape ActiveRecord uses for a query:
 
 ```
 GraphWeaver PersonQuery (12.3ms) ok
 GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
 GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
-GraphWeaver PersonQuery (5.0ms) ok (retry 2)
+GraphWeaver PersonQuery (44.0ms) failed GraphWeaver::CastError
 GraphWeaver billing/InvoicesQuery (12.3ms) ok
 ```
 
-The operation is prefixed by its graph when the request carried one, so an app
+The operation is prefixed by its graph when the call carried one, so an app
 with several graphs sorts its own log and an app with one never sees the prefix.
 
-**The summary is info, the wire is debug.** This is the only GraphWeaver line at
-info, so a production log gets one per operation and nothing that can carry PII;
-debug adds the query, the variables and the response *beneath* it. It writes
-through `GraphWeaver.logger`.
+**The operation is info, the attempt is debug.** The info line is one *call*, so
+it says what the caller got and a production log gets one per call — a retried
+call included, whose attempts and their backoff are inside that one duration.
+Debug adds a line per attempt in the same shape, carrying the url's status and
+which try it was, beneath the query and the variables. It writes through
+`GraphWeaver.logger`.
 
 Outside Rails the same line is an instrumenter of your own, writing
 `payload[:operation]`, `[:duration_ms]` and `[:status]` from an `ensure` — the
@@ -151,11 +188,15 @@ shape the two tracing examples below use.
 
 ### OpenTelemetry
 
+A span per operation, with a span per attempt inside it:
+
 ```ruby
 tracer = OpenTelemetry.tracer_provider.tracer("graph_weaver")
 
-GraphWeaver.instrumenter = lambda do |_event, payload, &block|
-  tracer.in_span("graphql #{payload[:operation] || "query"}") do |span|
+GraphWeaver.instrumenter = lambda do |event, payload, &block|
+  name = event == GraphWeaver::OPERATION_EVENT ? "graphql #{payload[:operation] || "query"}" : "graphql request"
+
+  tracer.in_span(name) do |span|
     block.call
   ensure
     span.add_attributes(payload.compact.transform_keys { "graphql.#{_1}" }.transform_values(&:to_s))
@@ -171,7 +212,8 @@ span status itself for a *raise* only, which is the last line's reason to exist.
 **Span status is not the alerting signal; `payload[:status]` is.** A response
 carrying GraphQL errors is a 200 that returned normally, so nothing raises and a
 span left to itself is `UNSET` — an SLO built on span status alone misses every
-GraphQL-level failure there is. Alert on `:status` and group by `:code`.
+GraphQL-level failure there is. Alert on the operation event's `:status` and
+group by `:code`.
 
 **Propagating the trace outward** is a header, and a
 [header value may be a callable](transports.md#headers) resolved per request —
@@ -191,9 +233,11 @@ GraphWeaver.instrumenter = lambda do |event, payload, &block|
 end
 ```
 
-Datadog's Net::HTTP and Faraday contribs already trace the transport layer, so
-with them on you have a span for the POST. This adds the span *above* it, named
-for the operation — the one that means anything, since every GraphQL call is a
+One hook covers both events, and the event name is the span name — so an
+operation and its attempts nest under distinct resources. Datadog's Net::HTTP
+and Faraday contribs already trace the transport layer, so with them on you have
+a span for the POST as well. This adds the spans *above* it, and the one named
+for the operation is the one that means anything, since every GraphQL call is a
 POST to the same url.
 
 ## Details

data/docs/migrating.md

@@ -0,0 +1,126 @@
+# Migrating from graphql-client (or a hand-rolled client)
+
+**The wire doesn't change.** The same query text goes out and the same JSON comes
+back, so this is a sequence of small commits rather than a cutover: queries move
+across one at a time while the old client keeps serving, and most of the spec
+suite you already have keeps passing untouched.
+
+Budget 3–4 weeks of one engineer for an app with ~40 queries and 25k lines of
+code reading them — [what it costs](#what-it-costs) breaks that down. If the app
+doesn't run Sorbet and has fewer than ten queries, don't migrate: the wins that
+survive without `srb tc` are real, but they don't pay for a checked-in code
+generator ([alternatives](alternatives.md#graphlient)).
+
+## From graphql-client, in Rails
+
+**Both gems stay in the Gemfile until the last commit.** `rails g
+graph_weaver:install` boots the app to read your configuration, so an initializer
+that still requires graphql-client has to keep resolving — remove the gem first
+and the generator dies on `cannot load such file -- graphql/client`. Running the
+two side by side is the right shape anyway.
+
+1. **Install beside graphql-client**, pointed at the dump you already have:
+   `rails g graph_weaver:install db/petstore_schema.json` ([a schema dump you
+   already have](getting_started.md#a-schema-dump-you-already-have)). Commit that
+   and nothing else.
+2. **Adopt the dump.** It records no source url, so `schema:diff` and
+   `queries:check` have no server to ask. `rake graph_weaver:schema:refresh`
+   rewrites it from the client the app points at (or `URL=<your endpoint>` once)
+   and records the provenance. Do it now: until you do, `queries:check` is
+   re-reading the file it is meant to be checking against, and says so. It
+   rewrites the file **in place, in graph_weaver's format** — pretty-printed
+   introspection JSON with a `graph_weaver:` provenance key beside `data`.
+   graphql-client goes on reading it, since `load_schema` hands the parsed hash
+   to graphql-ruby and graphql-ruby takes `data` and ignores its siblings; a dump
+   anything *else* reads is worth checking once.
+3. **Register scalars and enums, and regenerate** — if the API declares any.
+   Plenty don't: one whose leaves are all `String`, `Int`, `ID` and `Boolean` has
+   nothing to register and skips this step whole. Registrations are baked into
+   generated source, so one added later reaches nothing until the next
+   `rake graph_weaver:generate` ([scalars](scalars.md)).
+4. **Port one query end to end** — write the `.graphql` file, generate, rewrite
+   its call site — and leave the specs alone. They pass untouched. That single
+   commit is the proof for every one after it.
+5. **Port the rest, one commit per query.** Each `Client.parse` constant stays
+   where it is until its last caller is gone.
+6. **Only now port the specs** to `graphql: :fake` ([testing](testing.md)). Keep
+   webmock until the last wire-level stub is gone, and keep one spec that really
+   serves HTTP.
+7. **Delete graphql-client.** Last commit.
+8. **Sigs through your own app are a separate project**, after all of the above —
+   [the types stop where your sigs do](getting_started.md#the-types-stop-where-your-sigs-do)
+   says what that work is.
+
+Keep your own error classes. Translating `GraphWeaver::QueryError`,
+`TransportError` and `ServerError` at one seam leaves a controller, its rescues
+and their specs untouched ([errors](errors.md)). Keep your presenters too, and
+your fixtures until step 6.
+
+### Why app code and specs are separate commits
+
+Because the wire is the same, a webmock suite doesn't notice which client sent
+the request. Swap the client under an untouched suite and most of it stays green
+— 18 of 22 stubbed examples in one migrated Rails app, same stubs, same JSON
+fixtures; the four that failed were unit specs feeding a hand-rolled `Struct` to
+a presenter. That is the difference between a reviewable migration and a big-bang
+one.
+
+## From a hand-rolled client
+
+Same skeleton, three differences.
+
+- **One branch, no seam.** There's no generator to keep bootable and a
+  hand-rolled client is sixty lines, so running two of them side by side costs
+  more than it saves.
+- **Set the load order first**: `GraphWeaver.load_generated!` goes before your own
+  requires ([not Rails?](getting_started.md#not-rails)). Add `rake` to the Gemfile
+  while you're there.
+- **Keep the old client's transport specs**, rewritten against a real
+  `GraphWeaver.new(url, retries: 2)` with webmock. Retries, timeouts and backoff
+  are the one thing fakes can't cover.
+
+## What you delete
+
+- **The retry loop.** A hand-rolled one usually retries everything, mutations
+  included. `retries: 2` excludes mutations by default, honours `Retry-After`,
+  and knows 408 and 429 ([retries](transports.md#retries)) — twenty lines gone and
+  a correctness bug gone with them.
+- **Scalar parsers.** `register_scalar("Money", Money)` is one line, and it
+  deletes the `"USD 12.50".split` sitting in every place that parsed one. `Date`
+  and `DateTime` need no registration at all ([scalars](scalars.md)).
+- **Fragment unwrapping.** graphql-client masks a spread fragment's fields on the
+  parent, so every call site reads `Petstore::PetFields.new(data.pet).name` and
+  carries the parent alongside for the fields the fragment didn't cover. Generated
+  structs inline the fragment, so it's `pet.name`; a fragment that is a whole
+  selection becomes one shared Ruby type
+  ([hoisting](generated_modules.md#a-shared-fragment-is-one-type)).
+- **JSON fixtures and stub helpers.** `graphql: :fake` fabricates a
+  schema-correct response and you pin the fields the example is about. Pins are
+  schema vocabulary (`"Pet.species" => "DOG"`), so they survive query refactors,
+  and they're spellchecked — a typo raises instead of leaving the example green
+  against random data ([testing](testing.md)).
+
+## The one behaviour change to plan for
+
+**Enum drift is fatal.** A hand-rolled client hands you the raw string, so a value
+the server added after you shipped falls through to whatever your code does with
+an unknown one — commonly a `humanize`. A generated enum refuses instead: casting
+raises and the whole response is lost, naming the value, the enum and the values
+it knows about.
+
+That is the right default for an API you own and a real risk for one you don't,
+because it breaks on a day nobody deployed. Before you port a query over an enum
+someone else can extend, register a fallback for it and unknown values land there
+instead — [enums](scalars.md#enums-map-onto-your-own-tenum).
+
+## What it costs
+
+| | how it scales | ~40 queries, 25k lines |
+|---|---|---|
+| `.graphql` files and generating | sublinear — the second query costs a tenth of the first | 2–3 days |
+| call sites | linear, and the bulk of it: every `data["x"]["y"]` becomes `x.y`, and every defensive `nil` guard either disappears or turns out to have been wrong | ~1 day per 3–4k lines of consuming code |
+| specs | linear, and pleasant — the fixture-to-pin conversion is the same edit every time | ~2 days |
+| sigs through your own app | the one that decides whether the migration paid off | weeks; a separate project |
+
+Coming off graphql-client, run the new one behind the old for the first two
+weeks. The wire compatibility makes that free.

data/docs/scalars.md

@@ -428,12 +428,17 @@ It raises naming every scalar that disagreed and which way:
 ```
 2 scalar(s) disagree with Catalog::Schema:
   Money: the server refused "12.5", the wire form serialize: writes (expected "12.50 USD")
-  Decimal: round-trips lossily — sent 0.123456789123456789e9, got back 0.1234567891234567e9
+  Decimal: round-trips lossily — sent 123456789.123456789, got back 123456789.1234567
 ```
 
 The fabricated value is all it has to work with, so pin the one that matters:
 `config.overrides = { "Decimal" => "123456789.123456789" }` is how the precision
-case gets exercised at all — two decimal places always survive a Float. Pass the
+case gets exercised at all — two decimal places always survive a Float. That is
+the only door onto a pin here: `check_scalars!` takes the schema and nothing
+else, and runs outside every fake, so `graphql_fake` would be a no-op. The last
+leg compares with `==`, so a registered class that defines none is reported as
+uncheckable rather than lossy — two identical spellings mean identity, not a
+loss. Pass the
 schema **class**; a dump's scalars pass values through, so against one this checks
 only that a registration's `cast:` accepts what its own `serialize:` writes, which
 is a different question (see below).
@@ -501,17 +506,56 @@ Two safety properties do the real work:
   a member, or generation fails naming the gaps (`PetKind has no member for
   Species value(s) DOG — add them, pin with map:, or absorb with fallback:`), so
   your enum drifting from the server's is caught by `rake graph_weaver:generate`,
-  not in production.
+  not in production. The other direction only *warns* — one app-wide `T::Enum` can
+  serve two APIs that each expose a subset — and a kwarg carrying a member this
+  schema declares no value for is refused by name at the call.
 - **`fallback:` for forward-compat**: `fallback: PetKind::Unknown` makes *casting*
   absorb wire values the server added after you generated, so responses keep
   flowing instead of raising. Inputs stay strict either way: a typo'd input is your
-  bug, not drift. A union or interface absorbs the same drift with no registration
-  — a member added upstream lands in the catch-all `Other` its dispatch always
-  carries ([generated modules](generated_modules.md#abstract-types)).
+  bug, not drift. You don't need an enum of your own for that:
+  `GraphWeaver.register_enum("Species", fallback: true)` gives the *generated* enum
+  the same forward-compat, [below](#values-the-server-hasnt-told-you-about-yet).
 
 The translation tables are emitted into the generated source (`SPECIES_FROM_WIRE` /
 `SPECIES_TO_WIRE`) — reviewable in the diff, no runtime registry.
 
+### Values the server hasn't told you about yet
+
+A server adding an enum value is a deploy you weren't part of, and by default the
+next response carrying it raises. `fallback: true` says take it anyway:
+
+```ruby
+GraphWeaver.register_enum("Species", fallback: true)
+```
+
+The generated `Species` gains one member, `Other`, and every wire value the schema
+doesn't declare casts to it — the leniency a union or interface already has for
+free, where a member added upstream lands in the catch-all `Other` its dispatch
+always carries ([generated modules](generated_modules.md#abstract-types)).
+
+```ruby
+pet.species                    # => GraphQLTypes::Species::Other, for "AXOLOTL"
+```
+
+Three things follow from that, and they are the whole rule:
+
+- **`Other` doesn't carry the value it absorbed.** A `T::Enum` member is a
+  singleton, so there is nowhere to put it; the cast writes one debug line
+  (`GraphQLTypes::Species absorbed "AXOLOTL" into Other`) and that is the record
+  — so a presenter humanising the server's spelling can't, and falls back to a
+  label of its own. `as_json` writes the member's own wire value, `"__other__"`,
+  which `from_h` reads straight back — but `render json: result` hands that
+  sentinel to whoever is downstream, and no server declares it.
+- **Inputs stay strict.** No wire value means `Other`, so a variable carrying it
+  is refused rather than sent. Everything else is unchanged: a typo'd input is
+  your bug, not drift.
+- **A schema that already declares `OTHER` keeps it.** The declared value stays
+  `Other`, and the fallback member is `Other2` — the same rule a union's
+  catch-all struct follows when a member is already named `Other`.
+
+It rides along with `alias:` on the one registration, and like every registration
+it belongs to one graph.
+
 ### Two spellings, one value
 
 A schema mid-rename declares both `LEGACY_MODE` and `legacy_mode` so old clients

data/docs/testing.md

@@ -136,6 +136,15 @@ leaving the example green against random data. **Schema vocabulary, not Ruby:**
 spelled the way *that* schema spells it, so a Hasura table type is
 `"pokemon_v2_pokemon"` and not a Ruby-cased guess at it.
 
+**The key is checked; the value is yours.** `"Pet.species" => "RABBIT"` is
+accepted on an enum declaring no `RABBIT`, and the fake serves it as written — a
+pin is the escape hatch, so nothing second-guesses what you put through it. On an
+enum registered
+[`fallback: true`](scalars.md#values-the-server-hasnt-told-you-about-yet) that is
+how you rehearse drift, since the value lands in the catch-all member exactly as
+a real server's new one would; without a fallback the cast raises where a real
+response would.
+
 A pin **merges**, and pins a **subtree** as readily as a leaf: name the fields
 the example is about and everything else in the selection is still fabricated. A
 pinned list is exactly as long as you write it — `{}` means "another one, all
@@ -158,7 +167,8 @@ snake_cased reader, puts the value on the wire the way its
 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"`). A FactoryBot sequence advances on
+concrete type — `"Person"` or `"Person.name"`, never `"Named"` or
+`"Named.name"`, and both spellings of the abstract one are refused. A FactoryBot sequence advances on
 its own counter, which is the one thing `--seed` can't reproduce.
 
 A **scalar type pin** is the one thing a scalar registered as *your own class*
@@ -217,9 +227,12 @@ 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.
+won't do), from the three places one can be named: `config.schema` when you set
+it to a class, else the class [that graph](getting_started.md#more-than-one-schema)
+names, else the class your own `GraphWeaver.client` already runs in-process.
+Nothing is *scanned* for: with none of the three it refuses, and names the fix
+that fits — declare the class on the graph, write `graphql_in_process(MySchema)`
+in the example, or set `config.schema = MySchema` for the suite.
 
 A federated app has no one live class, so the example says which subgraph it
 means: `graphql_in_process(Reviews::Schema)`. Testing one subgraph's resolvers
@@ -253,7 +266,11 @@ block to scope it for the example that needs two identities —
 `graphql_context(admin: true) { … }` — and call it with nothing to read 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.
+data nothing scoped. Pin the data itself instead. Under `graphql: :live` it
+refuses too — including in an untagged example, which is `:live` by default, and
+including when your own client is an `InProcess` running your resolvers: that
+client carries the context it was *built* with, and `graphql_context` reaches
+only the stand-ins the mode built for this example.
 
 ## A federated graph — `graphql: :router`
 
@@ -360,8 +377,17 @@ that is a pure *client* of someone else's API gets a schema-correct server
 without writing one. A graph with no schema at all is refused, **by `:wire`'s own
 name** — the one fallback the other tags have and this one can't use is your
 client's own schema, since reading it means introspecting the endpoint `:wire`
-has just stubbed. Commit a dump, or set `config.schema`. A graph whose `client`
-posts nowhere is refused by name too.
+has just stubbed. Commit a dump, or set `config.schema`. That refusal waits until
+one of *that graph's* modules runs, so a graph the example never touches never
+refuses it.
+
+**A graph whose `client` posts nowhere runs above the wire** — there is no
+endpoint to stub, so it is served in the client slot, exactly as
+`graphql: :in_process` would serve it. That is how an app that owns resolvers
+*and* calls someone else's API tests the remote half over the wire: its
+in-process graph runs in-process, and every graph posting to a url is still
+served at that url. An example where *no* graph posts anywhere is refused — a
+`:wire` that serves nothing tests no transport.
 
 **It says which, on the logger** — the choice is the one thing this tag makes for
 you, and it is invisible from inside the example. One line per endpoint, at
@@ -377,7 +403,12 @@ set `GraphWeaver::Testing.config.schema` — the case worth catching, because an
 app that owns real resolvers otherwise goes green against fabricated data with
 nothing said. A warning rather than a refusal, because a loaded class isn't proof
 you meant it *here* — a federated suite loads every subgraph's — and a fake
-behind the wire is a thing to want.
+behind the wire is a thing to want. A graph that ran above the wire gets a line
+of its own, since the transport the example asked for never ran for it:
+
+```
+graph_weaver: :wire has no endpoint for graph :orders — its client posts to none, so its modules run above the wire, as graphql: :in_process would
+```
 
 **A helper says what goes behind the wire.** Under the other tags a `graphql_*`
 helper takes the client slot; under `:wire` it is served instead — the client
@@ -423,7 +454,9 @@ time** — answering one means setting the client's context for the length of th
 dispatch, so the identity a request asked for is the identity it gets, whatever
 else is in flight. The lock is the client's own, so it holds however the endpoint
 is mounted. A `context:` hash is served **concurrently**: nothing writes it, so
-there is nothing to serialize.
+there is nothing to serialize. Either way a query reads its context once, so
+every subgraph it hops through runs as the identity it started with, even if
+the router's context is reassigned while it is in flight.
 
 ### Making the served endpoint fail
 
@@ -546,10 +579,14 @@ rather than guessing**:
   the wire value that graph's generated cast expects. (Pins and `overrides:` stay
   suite-wide, keyed by scalar name — one `"Money"` override for the run.)
 - **`:in_process`** needs the live schema *class*, since only that has resolvers:
-  the one that graph names, else the one your client already runs in-process,
-  else the loaded class that defines everything the schema declares — the same
-  derive-verify-refuse rule that
-  [maps subgraphs](federation.md#which-schema-serves-which-subgraph).
+  `config.schema` when you set it to a class, else the one that graph names, else
+  the one your client already runs in-process. Nothing is scanned for — a loaded
+  class is no evidence the app meant it *here* — so past those three
+  `:in_process` refuses, while [`:wire`](#over-the-wire--graphql-wire) reads the
+  same list and serves a fake, **warning** and naming the class it saw.
+  (Deriving a schema from what *is* loaded is the
+  [subgraph rule](federation.md#which-schema-serves-which-subgraph), where the
+  routing table says what a match has to define.)
 - **`:router`** plans against the composed supergraph **that graph** names, else
   `config.router = { supergraph: … }`, else the committed dump when *that*
   carries `@join__*` markers, else the dump your own client was built from
@@ -617,7 +654,17 @@ one ahead of yours, so a `before` setting `config.schema`, `config.router` or
 **refused**, not ignored — a green example running against the wrong stand-in is
 the expensive outcome.
 
-### Fabricated list lengths
+That hook is also why **a refusal the tag itself raises can't be asserted with
+`expect { }.to raise_error`**: it happens before the example body, and rspec
+records it as the example's failure rather than letting anything catch it — an
+`around` hook included, since `example.run` returns normally there. To assert
+one, call the helper in an **untagged** example, where the same refusal is
+raised in the body: `expect { graphql_in_process }.to raise_error(...)`, and the
+same for `graphql_fake` and `graphql_router`. `:wire` has no helper, so its
+whole-example refusal can only be read off the failure — the per-graph one it
+raises when a module runs is in the body, and assertable.
+
+### Fabricated list lengths and nulls
 
 `list_size` is how long an **unbounded** list is — an Integer exactly that many,
 a Range randomized within it, or a Hash saying it per list. A list with a
@@ -632,6 +679,23 @@ for the rest — `config.list_size = { "Row.tags" => 3, default: 1000 }` holds t
 inner list at 3 however large the outer one grows. Or cap it in the query
 (`tags(first: 3)`), where the query is yours to change.
 
+`null_chance` takes the same two shapes, and the same keys: a number from 0 to 1
+for every nullable field, or a Hash saying it per field with `default:` for the
+rest. So the example about one missing value says only that —
+`graphql_fake(null_chance: { "Person.nickname" => 1.0 })` — instead of nilling
+everything else alongside it. A misspelled key is refused and spellchecked, the
+way a pin's is.
+
+**Both are keyed by field, and the key has to be one the option can reach**: a
+type name (`"Person"`) is refused rather than read as the nearest field, a
+`null_chance` key naming a non-null field is refused (nothing there ever comes
+back null), and a `list_size` key naming a field that isn't a list likewise —
+all three are keys that would validate clean, fabricate nothing and leave the
+example green. `"default"` is always the fallback, never a field, so a schema
+field actually called `default` is reachable only as `"Type.default"`. And a
+[pin](#pins) on the same field beats both: a pinned value is used as written,
+so it is neither nulled nor resized.
+
 **A list field whose name ends in `errors` fabricates empty** — `userErrors`,
 `errors`, `mutationErrors`. The Relay/Shopify payload
 (`placeOrder { order userErrors }`) is the ecosystem's mutation shape, and a