graph_weaver 0.7.5 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53034719b6dcd597d098091606e08b6f4a33a15a89826374cf6b14df841aa0fc
-  data.tar.gz: cb64c3e12070f522a44353066aaac80ea7faf9df7d8a564a1abfcd053584049b
+  metadata.gz: 3a68eaeb8cd0f3139cc9e50b88d98a50e04acd0c2c94c7825233f04405d30c42
+  data.tar.gz: '08df5051075500cb81c710cd65705f387dec16bc29a626e2b8069bbf5c61b3a1'
 SHA512:
-  metadata.gz: 6b320bc47a5839ef8561f44ac12b78eba36cc8b33078397f2818db59ce1268fef5f3b6b4aa347ef1e21443c9e213dd1ea6c5a297d14d8fa5c651ff8bcacd3052
-  data.tar.gz: 35abfec468ca9f50327c7f6a33a7f881884c004daf294019dd0a27c12498c010ec4383404a86d7015ed74616d114978e62e081703acffbcba58b9b3abad69add
+  metadata.gz: ee7b2971697409f7180e31d40569fd44108404c0f1d811b259bec6e000f7cf82142e7640de164510d1dbd253916392c6cc866619ee2d37e35e610b1ed0be9741
+  data.tar.gz: 9d219008a1db9bc353ef3b033b9c39f64657e58d1d2548fb074fc1a60973052e4abd0c1950d93622ad1cfc0414e7ca1219d9c770e32e445cedba287636f58a73

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.5)
+    graph_weaver (0.7.6)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -299,7 +299,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.7.5)
+  graph_weaver (0.7.6)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5

data/docs/errors.md

@@ -106,6 +106,7 @@ subclass says where it failed:
 | `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 |
+| `Codegen::Aliases::HoistedSegment` | build time: an [`alias:`](generated_modules.md#flat-accessors-with-alias) path reads *into* a struct [hoisted](generated_modules.md#a-shared-fragment-is-one-type) from a shared fragment — `optional: true` skips it, but only at the cost of the accessor for every query that spreads the fragment |
 | `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` |
 | `Testing::MissingRecording` | a [cassette](cassettes.md) holds no entry for this request — the message prints the variables, and the ones it did record |
@@ -219,9 +220,12 @@ 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. 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**:
+of `execute` — and it is `#message`, the developer's line, that names it, with the
+schema's spelling beside it where the two differ (`issued_on (issuedOn): expected
+a String`): the prop is what you fix, and the wire name is what you grep the
+`.graphql` for. 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))

data/docs/generated_modules.md

@@ -461,10 +461,12 @@ off `__typename` when the selection carries one unaliased and unguarded, and off
 narrowed fragment, or one whose `__typename` is itself guarded, is refused: a
 match would be indistinguishable from a miss.
 
-A whole union field selected as one named *shared* fragment
+A whole abstract field selected as one named *shared* fragment
 (`{ ...FeedItemFields }`) is [hoisted](#a-shared-fragment-is-one-type) into
-`GraphQLTypes` like any other, so the same union is one Ruby type family across
-queries rather than a fresh dispatch module per query.
+`GraphQLTypes` like any other, in whichever of the three shapes above the
+fragment has — a dispatch module, one struct, or a nilable narrowed struct. So
+which shape it is never decides whether consuming queries share a type, and
+adding a second `... on` to a shared fragment doesn't move their constant.
 
 ### Consuming a union — dispatch on the class, not `__typename`
 
@@ -673,7 +675,7 @@ to replace it; what the *example* says still wins.
 generated module). A generated file says nothing about transport — only a private
 `GRAPH` naming its graph, which is also how `graphql: :fake` fabricates each
 module's own schema with two graphs in play, and the
-`:graph` on every [instrumentation event](logging.md#the-payload) the module's
+`:graph` on every [instrumentation event](logging.md#instrumentation) the module's
 `execute` produces.
 
 ## Deserializing a response from another client
@@ -848,8 +850,10 @@ you — a script that generates its own modules sets all four:
    other [client](#clients) to reach for.
 
 Miss (3) and the script gets a `NameError` for its own module; miss (4) and it
-gets `PersonQuery: client must respond to #execute(query, variables:), got
-NilClass` from a module that otherwise looks fine.
+gets `no client configured — set GraphWeaver.client= or pass a client` from a
+module that otherwise looks fine. Set the slot to something that can't execute
+and the module names the contract instead: `PersonQuery: client must respond to
+#execute(query, variables:, operation_name:), got Hash`.
 
 Every directory setting is a list — `queries_paths`, `generated_paths`,
 `fragments_paths` — and every entry is read (entries may be globs; the generated

data/docs/getting_started.md

@@ -292,9 +292,11 @@ omits it. Any drift exits non-zero — whether a change matters is yours to judg
 (`#breaking`, `#compatible`, `#to_h`, `#empty?`).
 
 `queries:check` answers the question that matters when the schema *has* moved:
-**which of your queries no longer validate, and why.** It re-introspects the url
-the dump records (without rewriting the dump) and validates every `.graphql` file
-against the schema as it is right now, naming each error's line and column:
+**which of your queries no longer validate, and why.** It re-introspects
+whatever is behind each graph's dump (without rewriting the dump) — the same
+source `schema:refresh` rewrites from and `schema:diff` compares against — and
+validates every `.graphql` file against the schema as it is right now, naming
+each error's line and column:
 
 ```
 app/graphql/queries/person.graphql
@@ -355,8 +357,11 @@ named `generated`, plus `vendor`, `node_modules`, `tmp` and `log`, is skipped,
 as is any file defining a graphql-ruby **type** — a `field :sku` there is your
 *server* offering a field, not this app reading one back. A module handed whole
 to a serializer (`render json:`, `to_h`, `as_json`, a local and all) counts every
-prop as read, and the report quotes the line it followed. Nothing is edited and
-the exit is 0; `STRICT=1` exits 1 when anything is unread.
+prop as read, and the report quotes the line it followed — a plain local stands
+for the module only inside the method it was assigned in, so a same-named block
+param in the next method credits nothing, while an `@ivar` crosses that boundary
+the way a `before_action` does. Nothing is edited and the exit is 0;
+`STRICT=1` exits 1 when anything is unread.
 
 **It is a lint, not a proof**, and the task's own footer says so. It matches
 names as text, so a prop called `name` counts as read the moment anything says
@@ -441,18 +446,25 @@ the client the graph names, rewrites the dump, and records the source, so every
 later refresh and `schema:diff` re-read the right server. `URL=` names the
 endpoint instead, if you'd rather say it once than configure the client first.
 
-Do it early. Until the dump records a source, `queries:check` has nothing to
-re-introspect, so it validates against the committed file — a real check, but
-`verify`'s question rather than this one's — and the verdict says which:
+Until there is something behind the dump to re-read — the url it records, the
+server the graph's client posts to, or the graphql-ruby class that client runs
+in-process — `queries:check` validates against the committed file: a real check,
+but `verify`'s question rather than this one's, and the verdict says which:
 
 ```
 every query validates against db/schema.graphql as committed — not the server (rake graph_weaver:schema:diff asks whether the server moved)
 ```
 
-A dump with no recorded url and no client behind it *is* the schema — a
-hand-maintained SDL nothing serves. `schema:refresh` leaves that one alone
-(`records no source url and the graph names no client — left as checked in`) and
-refreshes the rest, rather than taking the whole task down with it.
+A dump with none of those behind it *is* the schema — a hand-maintained SDL
+nothing serves. All three tasks say so in one sentence:
+
+```
+db/schema.graphql records no source url and the graph names no server behind it — no client posting to one, and no graphql-ruby schema class in this process — so the file is the schema and nothing here can re-read it
+```
+
+`schema:refresh` steps over that graph and refreshes the rest; `schema:diff`
+still exits 1, because a gate that passes on having compared nothing is worse
+than one that says so.
 
 ## More than one schema
 
@@ -506,9 +518,10 @@ they belong to and nothing about transport, so they read it when they execute.
 A graph with no `client` falls back to `GraphWeaver.client`, the app default.
 Name the object (`client GraphWeaver.new(url, auth: …)`) or, when the constant
 holding it is defined later than the graph block, its name (`client "GITHUB"`),
-which is resolved on first use. `schema "x"` sets and a bare `schema` reads
-back; there is no `schema = "x"` form, since the block is `instance_eval`'d and
-that would be a local variable that silently does nothing.
+which is resolved on first use — and not a lambda, which `schema` needs and this
+doesn't, since the name is resolved at call time already. `schema "x"` sets and
+a bare `schema` reads back; there is no `schema = "x"` form, since the block is
+`instance_eval`'d and that would be a local variable that silently does nothing.
 
 **`namespace` nests everything that graph generates** — `person.graphql` becomes
 `Billing::PersonQuery` ([naming](generated_modules.md#naming)). Constants are
@@ -522,8 +535,9 @@ An app that is a pure client of someone else's GraphQL owns no schema class, so
 every graph's `schema` is a dump. Give each the file you want and a `client`
 that can fetch it: `rake graph_weaver:schema:refresh` introspects each graph's
 client into its own dump, recording the url so every later `schema:refresh` and
-`schema:diff` re-reads the right server. A graph with neither a recorded url nor
-a client is left as checked in and the rest still refresh. (`URL=` is for the
+`schema:diff` re-reads the right server. Every graph is its own job — one with
+no server behind its dump is left as checked in, one whose server is down is
+reported under its own heading, and the rest still refresh. (`URL=` is for the
 app that has one dump and no graphs.)
 
 In specs, `graph:` is how an example says which graph a helper stands in for —
@@ -680,6 +694,9 @@ GraphWeaver.client = GraphWeaver.new(
 GraphWeaver.load_generated!   # no Railtie to require the generated files
 ```
 
+**A public API needs no `auth:`** — leave the line out. It is in the example
+because most endpoints want a token, not because the constructor asks for one.
+
 **`load_generated!` goes before your own requires** when anything your app loads
 names a generated constant as it loads — a `STATUS_LABELS` table keyed on
 `GraphQLTypes::ShipmentStatus` raises `uninitialized constant` otherwise, and

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

@@ -27,10 +27,17 @@ two side by side is the right shape anyway.
    `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.
-3. **Register scalars and enums, and regenerate**, before porting any code.
-   Registrations are baked into generated source, so one added later reaches
-   nothing until the next `rake graph_weaver:generate` ([scalars](scalars.md)).
+   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.

data/docs/scalars.md

@@ -433,7 +433,12 @@ It raises naming every scalar that disagreed and which way:
 
 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,7 +506,9 @@ 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
@@ -536,7 +543,9 @@ Three things follow from that, and they are the whole rule:
   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.
+  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.

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
@@ -548,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
@@ -619,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
@@ -634,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