graph_weaver 0.7.5 → 0.7.7

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

data/docs/upgrading.md

@@ -1,8 +1,9 @@
 # Upgrading
 
 [Regenerate](#regenerate-on-every-upgrade) whichever version you're on, then read
-the one section that is yours: from [0.7.4](#upgrading-from-074), from
-[0.7.3](#upgrading-from-073), from
+the one section that is yours: from [0.7.6](#upgrading-from-076), from
+[0.7.5](#upgrading-from-075), from
+[0.7.4](#upgrading-from-074), from [0.7.3](#upgrading-from-073), from
 [0.7.1](#upgrading-from-071), from [0.7.0](#upgrading-from-070) or from
 [0.6.1](#upgrading-from-061). Coming from 0.6.0 or older, the path is that
 version's own upgrade notes — read them at the tag they shipped under
@@ -24,6 +25,45 @@ That's the reminder working, not a false alarm. Generation is deterministic, so
 the diff is exactly what the new version emits differently and nothing else —
 worth reading rather than rubber-stamping.
 
+## Upgrading from 0.7.6
+
+Read the left column and skip what isn't yours; the
+[changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| set `namespace:` on any graph — `rake graph_weaver:graphs` lists them | its shared types module is `<Namespace>::Types`, not `<Namespace>::GraphQLTypes`. **Regenerate**, then move app code naming `<Namespace>::GraphQLTypes::X` to `<Namespace>::Types::X` — `srb tc` finds every site. Keep the old name with `types_module "GraphQLTypes"` in that graph's block, at the cost of the autoloadable layout below |
+| run Rails, and have a graph whose `namespace:` is the constant its output path spells | that tree is [left to Zeitwerk](generated_modules.md#the-rule-in-rails) — autoloaded on first reference, reloaded with the app, and no longer required at boot, so booting stops defining its parent namespace chain. Nothing to do; the Railtie says which side each graph fell on at debug. Every other tree is hidden and required exactly as before |
+
+Then regenerate, and the gate:
+
+```sh
+rake graph_weaver:generate
+rake graph_weaver:verify
+```
+
+## Upgrading from 0.7.5
+
+A patch release. The regenerate is what changes behaviour — every module gains
+the per-call event — and the rest reaches an app only where it already relied
+on the old wording. Read the left column and skip what isn't yours; the
+[changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| subscribe to `execute.graph_weaver`, or read `GraphWeaver::LogSubscriber`'s line | a second event, [`operation.graph_weaver`](logging.md#instrumentation), covers one `execute` start to typed result — retries, backoff and the cast — and the request events nest inside it. **The info log line is the operation's now**: `failed GraphWeaver::CastError` where it read `ok`, present under a `graphql:` tag, one line per retried call; the per-attempt line writes at debug. A module generated by 0.7.5 emits neither until regenerated |
+| spread a shared fragment on an interface or union that selects no `... on`, or exactly one — `grep -rn 'fragment .* on' app/graphql/fragments` | it [hoists](generated_modules.md#abstract-types) into `GraphQLTypes::<Fragment>` like every other shared fragment; app code naming `YourQuery::Result::Field` moves, and `srb tc` finds each site |
+| run `rake graph_weaver:queries:check` in CI for a graph that names its own `schema` — `rake graph_weaver:graphs` lists them | it re-introspects that graph's server (the dump's url, or the client's url or schema class) where it used to check the committed file, so CI needs the same reach a single-schema app already had. The verdict names what it checked against either way |
+| keep a composed supergraph on a graph that also names a `client` | `schema:refresh` steps over it with the recompose line where 0.7.5 could have overwritten it with the API schema |
+| parse `rake graph_weaver:unused` output, or run it `STRICT=1` | a `before_action`-loaded `@result` is credited again, and the coordinate printed comes from the query, not from any word in the file |
+
+Then regenerate, and the gate:
+
+```sh
+rake graph_weaver:generate
+rake graph_weaver:verify
+```
+
 ## Upgrading from 0.7.4
 
 Read the left column and skip what isn't yours; the
@@ -227,7 +267,7 @@ only one here that shows up in production rather than in your code.
   Nothing raises: a subscriber comparing it to an Integer just stops matching. **A
   subscriber that branched on a 4xx/5xx reads `:http_status` now**, which is nil
   in-process. The whole payload is a documented contract —
-  [logging](logging.md#the-payload).
+  [logging](logging.md#the-request-payload).
 - **`respond_to?` on a result struct no longer answers true for a name that doesn't
   exist.** It used to say true for any near miss, which broke the standard
   duck-typing guard. **A branch that read the old answer now takes the other path**,

data/examples/README.md

@@ -34,5 +34,7 @@ looks like an app:
   fellow stargazers.
 
 Regeneration introspects GitHub's schema (a few seconds, cached to a gitignored
-`github/schema.json`); `run.rb` alone never introspects, because the generated
-modules already carry their types.
+`github/schema.json`); once that dump is there the repo's own `bin/generate`
+refreshes these modules along with every other generated file, offline. `run.rb`
+alone never introspects, because the generated modules already carry their
+types.

data/examples/github/generate.rb

@@ -6,15 +6,29 @@
 # the same workflow `rake graph_weaver:generate` runs in an app:
 #
 #      examples/github/generate.rb
+#
+# bin/generate calls generate! too, off the cached dump, so these files are
+# regenerated by the build like every other checked-in generated file.
 require_relative "setup"
 
-GraphWeaver.graph :github do
-  schema GraphWeaver.client.schema
-  queries File.join(__dir__, "queries")
-  output File.join(__dir__, "generated")
+module GithubExample
+  # The graph, declared once for both doors: this script, which introspects
+  # GitHub, and bin/generate, which passes the dump that introspection cached.
+  def self.generate!(schema_source)
+    GraphWeaver.graph :github do
+      schema schema_source
+      queries File.join(__dir__, "queries")
+      output File.join(__dir__, "generated")
+    end
+
+    GraphWeaver.generate!
+    GraphWeaver.changed_files
+  end
 end
 
-GraphWeaver.generate!
-changed = GraphWeaver.changed_files
-changed.each { |path| puts "wrote #{path}" }
-puts "already up to date" if changed.empty?
+if $PROGRAM_NAME == __FILE__
+  GithubExample.connect!
+  changed = GithubExample.generate!(GraphWeaver.client.schema)
+  changed.each { |path| puts "wrote #{path}" }
+  puts "already up to date" if changed.empty?
+end

data/examples/github/generated/star_mutation.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.4 — do not edit.
+# Generated by GraphWeaver 0.7.7 — do not edit.
 
 module StarMutation
   extend T::Sig
@@ -117,7 +117,7 @@ module StarMutation
       "id" => GraphWeaver::Coerce.variable("id", OPERATION_NAME, id) { |v| GraphWeaver::Coerce.id(v, "ID") },
     }
 
-    from_response(dispatch(variables, client:))
+    dispatch(variables, client:) { |raw| from_response(raw) }
   end
 
   sig { params(id: String, client: T.untyped).returns(Result).checked(:never) }

data/examples/github/generated/stargazers_query.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.4 — do not edit.
+# Generated by GraphWeaver 0.7.7 — do not edit.
 
 require "time"
 
@@ -257,7 +257,7 @@ module StargazersQuery
       "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v, "Int") },
     }
 
-    from_response(dispatch(variables, client:))
+    dispatch(variables, client:) { |raw| from_response(raw) }
   end
 
   sig { params(owner: String, name: String, first: Integer, client: T.untyped).returns(Result).checked(:never) }

data/examples/github/generated/starred_query.rb

@@ -1,7 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# Generated by GraphWeaver 0.7.4 — do not edit.
+# Generated by GraphWeaver 0.7.7 — do not edit.
 
 module StarredQuery
   extend T::Sig
@@ -150,7 +150,7 @@ module StarredQuery
       "first" => GraphWeaver::Coerce.variable("first", OPERATION_NAME, first) { |v| GraphWeaver::Coerce.integer(v, "Int") },
     }
 
-    from_response(dispatch(variables, client:))
+    dispatch(variables, client:) { |raw| from_response(raw) }
   end
 
   sig { params(login: String, first: Integer, client: T.untyped).returns(Result).checked(:never) }

data/examples/github/run.rb

@@ -7,6 +7,7 @@
 #
 #      examples/github/run.rb
 require_relative "setup"
+GithubExample.connect!
 
 # the checked-in typed modules (regenerate: examples/github/generate.rb)
 Dir[File.join(__dir__, "generated", "*.rb")].sort.each { |file| require file }

data/examples/github/setup.rb

@@ -4,15 +4,23 @@
 # Shared wiring for the GitHub example: auth and the client.
 require_relative "../../lib/graph_weaver"
 
-token = ENV["GITHUB_TOKEN"] || `gh auth token 2>/dev/null`.strip
-abort "need a token: `gh auth login`, or GITHUB_TOKEN=..." if token.empty?
-
-GraphWeaver.client = GraphWeaver.new(
-  "https://api.github.com/graphql",
-  auth: token,
+module GithubExample
   # used by generate.rb (and any dynamic parse): the first introspection
   # of GitHub's large schema dumps here — gitignored, a few seconds once,
   # instant after. run.rb's checked-in generated modules never introspect,
   # so running it alone won't create this file.
-  cache: File.join(__dir__, "schema.json"),
-)
+  SCHEMA_CACHE = File.join(__dir__, "schema.json")
+
+  # Requiring this file reaches nothing, so bin/generate can regenerate from
+  # SCHEMA_CACHE with no token; needing GitHub is this call.
+  def self.connect!
+    token = ENV["GITHUB_TOKEN"] || `gh auth token 2>/dev/null`.strip
+    abort "need a token: `gh auth login`, or GITHUB_TOKEN=..." if token.empty?
+
+    GraphWeaver.client = GraphWeaver.new(
+      "https://api.github.com/graphql",
+      auth: token,
+      cache: SCHEMA_CACHE,
+    )
+  end
+end