graph_weaver 0.4.6 → 0.5.0

data/docs/generated_modules.md

@@ -8,25 +8,63 @@ This is the production path — checked in, reviewed, statically checked
 (assembled step by step in the [getting started](getting_started.md), including
 [what Sorbet does and doesn't require](getting_started.md#sorbet-with-or-without)).
 For consoles and dev there's [dynamic mode](#dynamic-mode); for one-off
-scripts, `client.execute!` skips modules entirely.
+scripts, `client.run!` skips modules entirely.
 
 ## Generating
 
 The workflow that keeps generated code honest: queries live as `.graphql`
 files (the source of truth), generation writes the Ruby, and verification
 fails when the two drift. The conventional layout (configurable via
-`GraphWeaver.queries_path` / `generated_path` / `schema_path`):
+`GraphWeaver.queries_paths` / `generated_paths` / `schema_path`):
 
 ```text
 app/graphql/
   schema.json        # introspection dump (or schema.graphql SDL)
-  queries/           # *.graphql — hand-written, reviewed
+  queries/           # *.graphql / *.gql, nested — hand-written, reviewed
+  fragments/         # shared fragments, spread by name from any query
   generated/
-    inputs.rb        # manifest: requires + forward declarations
-    inputs/          # one file per shared type (input structs, enums)
+    types.rb         # manifest: requires + forward declarations, in load order
+    types/           # one file per shared type
     *_query.rb       # one module per query — generated, checked in, never edited
+    *_mutation.rb    # ...and per mutation
 ```
 
+**A type shared across query modules lives in `GraphQLTypes` and is aliased
+in.** Input types, schema enums, and unions hoisted from shared fragments are
+all one kind of thing — a type that would otherwise be copied into every query
+that touches it — so they live in one module, one file each, and a query module
+that uses any of them opens with `require_relative "types"`. Rename the constant
+(`GraphWeaver.types_module=`, or `generate!(types_module:)`) when one app
+generates against two schemas, in the same initializer that already gives each
+its own paths.
+
+One module is one namespace, so a shared fragment whose name is already a schema
+type in that module is refused at generation, naming both.
+
+**Naming.** A module is named after its **file**, suffixed with the operation
+the file defines — `person.graphql` → `PersonQuery` in `person_query.rb`,
+`save_list_entry.graphql` → `SaveListEntryMutation` in
+`save_list_entry_mutation.rb`. The operation name written *inside* the file
+never names the module (it goes on the wire as `operationName`); leave it off
+and the module's name is written into the document instead. The same rule
+runs at all three doors: `generate!`, `GraphWeaver.parse(path)`, and
+`client.load_queries!`.
+
+Subdirectories are yours to organize with — `queries/admin/pets.graphql` is
+found, but the module name still comes from the file name alone, so it is
+`PetsQuery` in `pets_query.rb`. Two files with the same base name are refused at
+generation, naming both, rather than one silently overwriting the other; so is a
+file holding two operations, since one file can't name two modules.
+
+Change a file's `query` to `mutation` and its constant changes with it; the
+next `generate!` prunes the old file, and `verify` fails until you regenerate.
+
+Parsing a raw query *string* has no file to name it after, so it uses the
+operation name (`query GetPerson` → `GetPerson`); dynamic `parse` falls back to
+`Query` for an anonymous one (its constants are container-scoped, so collisions
+are impossible) while `Codegen.generate` insists on a deliberate name. Pass
+`module_name:`/`name:` to override any of this.
+
 The schema dump is step 0 — codegen reads it, never a live endpoint.
 `cache: true` on a url client writes it on first introspection
 (`GraphWeaver.new(url, cache: true).schema` in a console bootstraps it);
@@ -36,14 +74,13 @@ Rake tasks (self-registering in Rails; elsewhere add
 `require "graph_weaver/tasks"` to your Rakefile):
 
 ```sh
-rake graph_weaver:generate    # queries_path -> generated_path
+rake graph_weaver:generate    # queries_paths -> generated_paths.first
 rake graph_weaver:verify      # fail if anything is stale — run in CI
 ```
 
-Scalar/enum/type registrations are baked into generated source, so they
-must run before the tasks do. In Rails they will — the tasks depend on
-`:environment`, which runs your initializers. Outside Rails, require the
-file that does your registrations from the Rakefile yourself.
+Scalar/enum/type registrations are baked into generated source, so they must run
+first. In Rails they do — the tasks depend on `:environment`. Outside Rails,
+require the file that does your registrations from the Rakefile yourself.
 
 Or call the same APIs directly:
 
@@ -53,57 +90,71 @@ GraphWeaver.generate!(schema:)            # write the modules
 GraphWeaver.verify_generated!(schema:)    # the freshness guard, one line in a spec
 ```
 
-In Rails, loading is automatic — the Railtie requires every file under
-`generated_path` at boot, after your initializers (so registrations run
-first). Elsewhere it's explicit, factory_bot-style:
+**Generation prunes.** Rename or delete a `.graphql` and the module it used
+to produce is deleted on the next `generate!`; `verify` flags it as stale
+until you regenerate. Only files carrying GraphWeaver's `# Generated by
+GraphWeaver — do not edit.` header are ever deleted, so hand-written files
+in the output directory are safe.
+
+In Rails, loading is automatic — the Railtie requires every generated file at
+boot, after your initializers (so registrations run first). Elsewhere it's
+explicit, factory_bot-style:
 
 ```ruby
-GraphWeaver.load_generated!   # require every file under generated_path
+GraphWeaver.load_generated!   # require every file under generated_paths
 ```
 
-The conventional paths are lists (entries may be globs — the default
-includes `app/graphql/*/generated`, so per-schema layouts load too).
-Append extra locations (a test-only schema, an engine's queries) and
-every loader walks them all:
+Every directory setting is a list — `queries_paths`, `generated_paths`,
+`fragments_paths` — and every entry is read (entries may be globs; the
+generated default includes `app/graphql/*/generated`, so per-schema layouts
+load too). Append a test-only schema or an engine's queries and every reader
+walks them all:
 
 ```ruby
 # e.g. in spec/support/graph_weaver.rb
-GraphWeaver.generated_paths << "spec/support/graphql/generated"
-GraphWeaver.queries_paths << "spec/support/graphql/queries"
+GraphWeaver.generated_paths << "spec/graphql/generated"
 ```
 
-The singular accessors (`generated_path` etc.) read and replace the
-first entry — the default target for `generate!` and the rake tasks.
+Assigning a String wraps it, so pointing at one directory stays a one-liner.
+`generate!` writes into the first `generated_paths` entry — one run, one output
+directory. `schema_path` is the one singular setting: a run reads one schema,
+so a list would name a dump nothing ever opens.
 
 (Plain requires, not Zeitwerk: Zeitwerk would expect
 `Generated::PersonQuery` from `generated/person_query.rb`, and generated
 code only changes on regeneration — restart, like a schema migration.)
 
-Regenerate when: a query changes, the schema changes (a
-[`schema_stale?`](errors.md) error in production is the late signal — refresh
-the schema dump and regenerate), a scalar registration changes, or GraphWeaver
-itself upgrades (emission may differ across versions; `verify_generated!`
-catches it).
-
-Introspected dumps record their source url, so drift is checkable ahead
-of the late signal: `rake graph_weaver:schema:verify` re-introspects the
-recorded url and fails when the server has moved;
-`rake graph_weaver:schema:refresh` rewrites the dump
-(`GRAPHWEAVER_AUTH` supplies a token for private APIs). Don't confuse
-the two verifies: `graph_weaver:verify` asks "is the generated code
-fresh?" — local, every CI run; `graph_weaver:schema:verify` asks "has the
-*server* drifted from the dump?" — network, needs the recorded url, run
-on a schedule.
+Regenerate when: a query changes, the schema changes, a scalar registration
+changes, or GraphWeaver itself upgrades (emission may differ across versions;
+`verify_generated!` catches it). The rake tasks that spot a schema change for
+you — `schema:diff`, `schema:refresh`, `queries:check` — are in
+[getting started](getting_started.md#5-verify-in-ci); a
+[`schema_stale?`](errors.md) error in production is the late signal.
 
 In development, skip the build entirely — `client.load_queries!` parses
 every query file into modules with the same names generation would use
 (see [dynamic mode](#dynamic-mode)).
 
+### Generation is deterministic
+
+The same schema and the same queries produce **byte-identical files** — on any
+machine, in any order, however many times you run it. Everything with a
+non-obvious order (schema members, enum values, requires, hoisted names) is
+sorted, and a spec asserts it both across calls and against the checked-in
+fixtures.
+
+Lean on it: regenerating a file you didn't change produces no diff, so a
+`graph_weaver:generate` in a PR shows exactly what moved, `verify_generated!`
+never fails spuriously, and a generated file is worth reviewing line by line.
+(A GraphWeaver upgrade may legitimately change emission — that's a version
+bump, and the changelog says when to regenerate.)
+
 ## Anatomy
 
 ```ruby
 module PersonQuery
   QUERY = "..."                  # the operation, verbatim
+  OPERATION_NAME = "PersonQuery"  # its name — the module's, when the file's is anonymous
 
   class Result < T::Struct       # the response shape, exactly as selected
     class Person < T::Struct
@@ -116,9 +167,9 @@ module PersonQuery
     const :person, T.nilable(Person)
   end
 
-  def self.client ...            # default client (see below)
-  def self.execute(client = nil, id:)   # -> GraphWeaver::Response[Result]
-  def self.execute!(client = nil, id:)  # -> Result, or raises QueryError
+  extend GraphWeaver::QueryModule # client / client= (see below)
+  def self.execute(id:, client: nil)    # -> GraphWeaver::Response[Result]
+  def self.execute!(id:, client: nil)   # -> Result, or raises QueryError
 
   def self.from_response(response)      # deserialize a raw hash -> Response[Result]
   def self.from_response!(response)     # -> Result, or raises QueryError
@@ -132,6 +183,14 @@ end
   `GraphWeaver::QueryError`.
 - `from_response` / `from_response!` are the **network-free half** of the
   pair — same envelope, but from a response hash you already have (see below).
+- `OPERATION_NAME` rides along on every request as the spec's
+  `operationName`, so Apollo Studio, Hasura and your APM key traces, rate
+  limits and slow-query reports on the operation instead of lumping every
+  request together. **You don't have to name your operations**: an anonymous
+  document is named after the module in the emitted `QUERY` *and* in
+  `OPERATION_NAME` — both, since a server rejects an `operationName` its
+  document doesn't declare. A document that names its own operation is left
+  exactly as written.
 
 ## Deserializing a response from another client
 
@@ -151,9 +210,8 @@ person   = response.data!.person            # typed, no network
 person   = PersonQuery.from_response!(raw).person
 ```
 
-`from_response` builds the exact same `GraphWeaver::Response[Result]` envelope
-`execute` does — in fact `execute` *is* `from_response(transport.execute(...))`.
-Errors and extensions are preserved; `#data!` / `from_response!` raise
+`execute` *is* `from_response(client.execute(...))`, so the envelope is
+identical: errors and extensions preserved, `#data!` / `from_response!` raising
 `QueryError` on top-level errors.
 
 The one requirement: pass the response **verbatim** — a hash (or anything with
@@ -170,67 +228,43 @@ mutation($name: String!, $species: Species!, $note: String) { ... }
 ```
 
 ```ruby
-AddPetQuery.execute!(name: "Rex", species: AddPetQuery::Species::Dog)
+AddPetMutation.execute!(name: "Rex", species: AddPetMutation::Species::Dog)
 ```
 
 - required vs optional falls out of nullability and defaults: nullable or
   defaulted variables become optional kwargs (nil is omitted from the wire,
   so server-side defaults apply)
-- enum variables generate module-level `T::Enum`s and accept the enum or
-  its wire value (`species: Species::Dog` or `species: "DOG"`)
+- enum variables accept the enum or its wire value (`species: Species::Dog`
+  or `species: "DOG"`)
 - custom scalars serialize through the [scalar registry](scalars.md)
 
-**Input objects**: when an operation's only variable is a required input
-object (the Relay convention), the input's fields flatten straight into
-`execute`'s kwargs — no wrapper at the call site:
+One kwarg per declared variable, always — so adding a variable to a query
+adds a kwarg and leaves every existing call site alone. Two names are refused at
+generation, `$client` and `$variables`: the generated `execute` body already
+owns them, and `def self.execute(client:, client: nil)` doesn't even parse.
+Rename the variable in the query.
+
+**Input objects** take the generated `T::Struct` or a plain hash — `.coerce`
+normalizes underscored Symbol/String keys, enums accept wire values, nested
+inputs accept hashes, and an unknown key raises with a spellchecked hint rather
+than silently dropping:
 
 ```graphql
 mutation($input: AdoptionInput!) { adopt(input: $input) { ... } }
 ```
 
 ```ruby
-AdoptQuery.execute!(name: "Rex", species: "DOG", nickname: "Rexy")
-```
-
-The wrapping level is rebuilt on the wire, and each field type-checks
-exactly like a variable would. Operations with more than one variable (or
-a nullable input) keep the variable-per-kwarg surface — there the input
-kwarg accepts the generated `T::Struct` or a plain hash (`.coerce`
-normalizes underscored Symbol/String keys; enums accept wire values;
-nested inputs accept hashes; unknown keys raise with a spellchecked
-hint rather than silently dropping):
+AdoptMutation.execute!(input: { name: "Rex", species: "DOG", nickname: "Rexy" })
 
-```ruby
-AdoptQuery.execute!(input: { name: "Rex", species: "DOG" }, detail: true)
+# the struct form is the one srb tc checks field by field
+AdoptMutation.execute!(input: AdoptMutation::AdoptionInput.new(name: "Rex", species: Species::Dog))
 ```
 
-In the generate! workflow, input types (and the enums they use) are
-emitted **once per schema** — one file per type under
-`generated/inputs/`, with `inputs.rb` as the manifest. The module is
-named from the output path: the conventional layout gets
-`GraphQLInputs`, while a multi-schema layout names each schema's module
-after its directory (`app/graphql/github/generated` → `GithubInputs`).
-Override the module name globally with `GraphWeaver.inputs_module=` or per run
-with `generate!(inputs_module:)`. Per-type files keep schema drift
-reviewable: a migration diffs exactly the types it touched, and types
-the schema drops are pruned on regeneration (`verify` flags strays).
-Query modules alias what they touch,
-so `AdoptQuery::AdoptionInput` still works and shared types keep one
-identity across modules — three filtered Hasura queries cost one ~11k-line
-inputs file plus ~90 lines each, instead of ~35k lines of duplicates.
-Deeply nested types live unaliased in the shared module
-(`GraphQLInputs::PetFilter`). Dynamic `parse` stays self-contained.
-
-The structs themselves are module-level (`AdoptQuery::AdoptionInput`):
-typed consts plus a compact per-field `FIELDS` table that the
-`GraphWeaver::InputStruct` runtime drives — `serialize` (aliased `to_h`)
-produces the wire hash with nil optionals omitted, `coerce` builds from
-plain hashes. The conversions ship in the generated file as data
-(lambdas in the table), so a Hasura `bool_exp` pulling hundreds of input
-types stays ~2 lines per field instead of unrolled methods. Nested inputs work (dependencies emit
-first), including recursive ones — Hasura's self-referential `bool_exp`
-filters generate cleanly (`_and:`/`_not:` fields typed as the struct
-itself), so variable-driven filtering works:
+A struct is typed consts plus a compact per-field `FIELDS` table the
+`GraphWeaver::InputStruct` runtime drives — `serialize` (aliased `to_h`) builds
+the wire hash with nil optionals omitted, `coerce` builds from a plain hash.
+Nested inputs work, including recursive ones — a self-referential filter
+generates cleanly, with `_and:`/`_not:` typed as the struct itself:
 
 ```ruby
 where = mod::PokemonBoolExp.coerce(
@@ -239,25 +273,42 @@ where = mod::PokemonBoolExp.coerce(
 mod.execute!(where:)
 ```
 
+In the `generate!` workflow input types are emitted **once per schema**, one
+file per type under `generated/types/` with `types.rb` as the manifest. Query
+modules alias what they touch, so `AdoptMutation::AdoptionInput` still works and
+a shared type keeps one identity across modules. A query module aliases only its
+*variable root* types, so a deeply nested one is reached as
+`GraphQLTypes::<Type>`. Per-type files keep drift reviewable: a schema migration
+diffs exactly the types it touched, and types the schema drops are pruned on
+regeneration (`verify` flags strays). Dynamic `parse` stays self-contained.
+
+## Enums: one GraphQL enum, one Ruby type
+
+Every schema enum a query touches — as a variable, in a result, or both —
+becomes exactly one Ruby type in the shared module, named for the enum
+(`GraphQLTypes::Species`), and every query module aliases it:
+
+```ruby
+species = SearchQuery.execute!(term: "Shelby").search.first.species
+AddPetMutation.execute!(name: "Rex", species:)     # same class, no conversion
+```
+
+So a value read out of one query hands straight back into another's variable,
+`case`/`T.absurd` is exhaustive across your app, and the class a field gets
+doesn't depend on what else the query happened to reference.
+
+`register_enum` replaces the generated `T::Enum` with your own app enum — see
+[scalars.md](scalars.md#enums-map-onto-your-own-tenum). Dynamic `parse` emits
+the enums into the query module itself; there's no cross-query set to share
+against, but one enum is still one class within that module.
+
 ## Selections
 
 - **Fragments** — inline fragments and named spreads flatten into the
   selection; type conditions match exact names or interfaces/unions the type
   belongs to.
-- **Unions and interfaces** — when the selection *varies by concrete
-  type*, each abstract site emits a module: one member struct per
-  possible type, `Type = T.type_alias { T.any(...) }`, and a `from_h`
-  dispatching on `__typename` — which generation therefore *requires* in
-  the selection (the wire response carries no type tag unless you ask).
-  Two narrower shapes skip the dispatch (and the `__typename`) entirely:
-  interface-level fields only → one shared struct; a single `... on X`
-  condition and nothing else → `X`'s struct, always nilable — a
-  non-matching runtime type comes back as `nil`, so narrowing doubles as
-  filtering. When a whole union field is selected as one named *shared*
-  fragment (`{ ...FeedItemFields }`), that type is hoisted once into the
-  `GraphQLUnions` module and each query aliases it — so the same union is one
-  Ruby type family across queries, not a fresh dispatch module per query. Like
-  shared inputs, it's a `generate!`-directory concern; dynamic `parse` inlines.
+- **Unions and interfaces** — one struct per type condition the selection
+  names, plus a catch-all `Other`. Detail [below](#abstract-types).
 - **`@skip` / `@include`** — a directive-conditional field may be absent from
   the response regardless of schema nullability, so its generated type is
   always nilable.
@@ -270,6 +321,38 @@ mode) the struct raises a NoMethodError naming the prop that does exist —
 `use 'name_with_owner'` for the exact wire name, `did you mean ...?` for
 a near-miss typo in either casing.
 
+### Abstract types
+
+An abstract field emits **one struct per type condition the selection names**,
+plus a catch-all `Other`, wrapped in a module with
+`Type = T.type_alias { T.any(...) }` and a `from_h` that dispatches on
+`__typename`. Generation therefore *requires* `__typename` in such a selection,
+unaliased and unconditional — the wire response carries no type tag unless you
+ask, and `from_h` reads it on every response.
+
+Size follows the query, not the schema: two `... on` conditions against GitHub's
+`Node` — an interface with a few hundred implementations — emit three structs,
+not a few hundred. Anything the query didn't name — a member you have no
+fragment on, or one the schema grew *after* you generated — deserializes into
+`Other`, carrying what the abstract type itself guarantees (an interface's
+selected interface-level fields; for a union, `__typename`). Adding a union
+member upstream is a non-breaking change, and it stays one here.
+
+Two selections have nothing to dispatch between, so they skip the module and
+become the struct directly: **no conditions at all** (interface-level fields
+only) → one shared struct; **exactly one condition** → that type's struct,
+always nilable, since a non-matching runtime type comes back as `nil` — so
+narrowing doubles as filtering. Narrowing reads the match off `__typename` when
+the selection carries it and off "the object came back empty" when it doesn't,
+which is why an all-`@skip`/`@include` narrowed fragment without a `__typename`
+is refused: a match would be indistinguishable from a miss.
+
+When a whole union field is selected as one named *shared* fragment
+(`{ ...FeedItemFields }`), that type is hoisted once into `GraphQLTypes` — named
+for the fragment — and each query aliases it, so the same union is one Ruby type
+family across queries, not a fresh dispatch module per query. Like shared
+inputs, it's a `generate!`-directory concern; dynamic `parse` inlines.
+
 ### Consuming a union — dispatch on the class, not `__typename`
 
 `from_h` already reads `__typename` off the wire and builds the right member
@@ -277,62 +360,194 @@ struct, so what you hold is a real `Book` or `Disc`, not a tag. Branch on the
 class and let Sorbet do the rest:
 
 ```ruby
-items.each do |item|          # item : T.any(Result::Item::Book, Result::Item::Disc)
+items.each do |item|          # item : T.any(Result::Item::Book, Result::Item::Disc, Result::Item::Other)
   case item
   when Result::Item::Book then item.title     # narrowed to Book — .title is available
   when Result::Item::Disc then item.runtime   # narrowed to Disc — .runtime is available
+  when Result::Item::Other then item.__typename # something this query names no fields on
   else T.absurd(item)
   end
 end
 ```
 
-Two things a `case item.__typename` on the string can't give you. `when Book`
+Two things a `case` on the `__typename` string can't give you. `when Book`
 *narrows*: inside the branch `item` is statically a `Book`, so its fields
-typecheck (a `Disc` field would be a compile error) — a string value narrows
-nothing. And after every member, the `T.any` is exhausted, so `T.absurd` asserts
-the `else` is unreachable: add a member to the union, regenerate, and the
-`T.absurd` stops compiling until you handle it. Dispatching on the string tag
-gets you neither — mistakes and schema growth fall through to a runtime raise.
-
-`__typename` is still there as a plain `String` if you want the raw tag, but you
-rarely need it to dispatch. Its one real use is the case the class can't cover:
-two *differently-selected* occurrences of the same union are distinct type
-families (`Result::Item::Book` is not `Result::FeaturedItem::Book`), so a `case`
-written for one won't span the other. To hold "the same union" as one type
-across queries, select it through a shared fragment
-([shared unions](#selections)); if all you have is the bare tag, `__typename` is
-the common denominator (but an unchecked one).
-
-## Naming
-
-Module names derive from the operation name (`query GetPerson` → `GetPerson`);
-`GraphWeaver.parse` on a `.graphql` file derives from the file name
-(`person.graphql` → `PersonQuery`). Pass `module_name:`/`name:` to override.
-`Codegen.generate` requires a deliberate name for anonymous operations; dynamic
-`parse` defaults to `Query` (its constants are container-scoped, so collisions
-are impossible).
-
-Nested struct names come from GraphQL type names, disambiguated one level by
-field name on collision.
+typecheck and a `Disc` field is a compile error. And after every branch the
+`T.any` is exhausted, so `T.absurd` asserts the `else` is unreachable —
+**write a fragment for another member, regenerate, and the `T.absurd` stops
+compiling until you handle it.**
+
+Exhaustive over the members *this query asked about*, plus `Other` —
+deliberately not "every type in the schema", which is what keeps a `case` you
+wrote today compiling when upstream adds a member. To make the compiler force
+your hand on a new one, name it in the query.
+
+`__typename` is still there as a plain `String`, with one use the class can't
+cover: two *differently-selected* occurrences of the same union are distinct
+type families (`Result::Item::Book` is not `Result::FeaturedItem::Book`), so a
+`case` written for one won't span the other. Select the union through a shared
+fragment to hold it as one type across queries ([above](#abstract-types)); if
+all you have is the bare tag, `__typename` is the common denominator, unchecked.
+
+## Naming nested types
+
+Module names come from the file ([above](#generating)). **Every nested type is
+named for the response key that selects it**, camelized
+(`stargazers` → `Stargazers`, `nameWithOwner` → `NameWithOwner`, `_entities` →
+`Entities`). Structs nest the way the selection does, so the constant path
+reads like the query:
+
+```graphql
+query { repository { stargazers { edges { node { login } } } } }
+```
+
+```ruby
+StargazersQuery::Result::Repository::Stargazers::Edges::Node
+```
+
+The name is a function of that field's own position and nothing else, which is
+the property that matters when generated code is checked in and referenced from
+app code: **adding, removing, or reordering an unrelated selection can never
+rename a struct you already use.**
+[`spec/naming_spec.rb`](../spec/naming_spec.rb) asserts each of those three
+edits leaves the name alone.
+
+The key is used verbatim — no pluralization heuristics, so a list field `pets`
+generates `Pets`, not `Pet`. To choose the name yourself, alias the field in the
+query: `pet: pets { name }` generates `Pet` (and a `.pet` accessor).
+
+Two kinds of name don't come from a key, both equally position-determined:
+
+- **Union and interface members** are named for the type condition that
+  produces them (`... on Book` → `Book`) inside the container named for the
+  field, plus the catch-all `Other`. A union hoisted out of a shared fragment
+  is named for the fragment.
+- Where several fields share one collapsed union type (identical selections),
+  it takes the first of their keys alphabetically; and a name that would shadow
+  the struct it nests in (`pet { pet { ... } }`) takes a numeric suffix
+  (`Pet2`), since a bare `Pet` inside `class Pet` would resolve to the child.
+
+## Type helpers
+
+Derived values (display names, emoji, predicates) belong next to the data but
+not *in* it — rewriting wire values on the way in destroys the raw truth.
+Register a plain module and every struct generated from that GraphQL type
+includes it, whatever query it appears in:
+
+```ruby
+module PetHelpers
+  def adult? = birthday && birthday < Date.today << 24
+  def display_name = adult? ? "#{name} 🦴" : "#{name} 🐶"
+end
+
+GraphWeaver.extend_type("Pet", PetHelpers)
+
+pet.display_name   # => "Shelby 🦴"
+pet.name           # => "Shelby" — the wire value stays honest
+```
+
+The methods live on the struct, so they see its wire fields at runtime and
+fakes/cassettes get the behavior automatically; registrations are additive
+(repeated ones stack). For quick decoration, build the mixin inline — the block
+is `module_eval`'d into a fresh module auto-named under
+`GraphWeaver::TypeHelpers`:
+
+```ruby
+GraphWeaver.extend_type("Pet") do
+  def display_name = "#{name} 🐶"
+end
+```
+
+**Neither form is statically checked**, for the same reason: `srb tc` checks a
+mixin's method bodies in the module's own scope, not the including struct's, so
+a helper reading a wire field (`name`, `birthday`) fails with "method does not
+exist on the module" — and the block form has no source on disk for `srb tc` to
+read at all. Write such a helper at `# typed: false`, or reach the field through
+`T.unsafe(self)`.
+
+### Flat accessors with `alias:`
+
+The one derivation the generator can type for you is a plain projection — a
+selected field, possibly nested, exposed under a flat accessor. `alias:` emits a
+sig'd delegator *into the struct body*, where the field is in scope, so it's
+fully checked (the thing a mixin can't be):
+
+```ruby
+GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
+
+# generated on the Widget struct:
+#   sig { returns(T.nilable(String)) }
+#   def tag = meta&.tag
+```
+
+Forms:
+
+```ruby
+alias: { tag: "meta.tag" }              # explicit accessor name
+alias: "meta.tag"                       # accessor named after the last segment (`tag`)
+alias: ["meta.tag", "meta.color"]       # several at once
+alias: { label: "name", tag: "meta.tag" }
+```
+
+The path is the **Ruby** accessor chain, so its segments are snake_case props
+(`name_with_owner.tag`), not wire names. It's typed from the selection: any
+nullable hop makes the accessor nilable and inserts `&.`; the leaf can be a
+scalar, enum, or nested struct. It's validated against each query at generation —
+an unselected or misspelled segment (`did you mean 'tag'?`), a selector on a
+non-list, or a name that collides with a real field all fail with a pointed
+error. Registrations stack, like the mixin forms.
+
+A segment can also be `first` or `last` to pick one element out of a list hop —
+always nilable, since the list may be empty. This is what turns an
+`_entities`-style "array that logically holds one thing" into a clean accessor:
+
+```ruby
+GraphWeaver.extend_type("Query", alias: { entity: "_entities.first" }, optional: true)
+
+#   sig { returns(T.nilable(Widget)) }        # concrete, when the selection is one `... on Widget`
+#   def entity = _entities&.first             # (a multi-fragment selection types it as the union)
+```
+
+`optional: true` makes the aliases *lenient*: a query whose selection doesn't fit
+the path just omits the accessor instead of failing generation. Reach for it when
+the alias lives on a universal type like `Query` — where a strict alias would
+force *every* query to select the path — or when it only fits some selections.
+It excuses a field the query didn't select, not a segment the schema doesn't
+have: a typo or a wire-cased name (`findPets` for `find_pets`) still raises,
+since no selection could ever satisfy it.
+
+For anything beyond a passthrough projection — real logic, still typed — reopen
+the generated struct in your own file and add sig'd methods; Sorbet merges the
+bodies.
+
+Every form above, and every error it raises, is a named example in
+[`spec/aliases_spec.rb`](../spec/aliases_spec.rb).
 
 ## Clients
 
-A client is anything with `execute(query, variables:)` whose result `to_h`s
-into `{"data" => ..., "errors" => ...}`. Resolution: per call → per module →
-baked constant → `GraphWeaver.client` — the
-canonical list lives in [transports](transports.md#client-resolution).
+A client is anything with `execute(query, variables:, operation_name:)` whose result `to_h`s
+into `{"data" => ..., "errors" => ...}` — a `GraphWeaver::Client`, a transport,
+a `Retry`, a live schema class, a fake. Resolution: per call (`client:`) → per
+module → baked constant → `GraphWeaver.client` — the canonical list lives in
+[transports](transports.md#client-resolution).
 
 Generate *without* a baked constant when you want modules to follow the
 app default (`GraphWeaver.client =` in an initializer) — that's also what
-lets [testing's auto_fake](testing.md) swap in a fake per example.
+lets [testing's `graphql:` tag](testing.md) swap in a client per example.
+
+`client`/`client=` live in the gem (`GraphWeaver::QueryModule`, extended by
+every generated module). A baked constant is emitted as `DEFAULT_CLIENT`,
+resolved on first use so a module can load before the initializer that builds
+its client.
 
 ## Dynamic mode
 
 `GraphWeaver.parse` generates + evals in one step (no build artifact, evaled
 into an anonymous container — no global constants leak). Same runtime
 semantics; invisible to `srb tc`, so prefer the build step where static
-checking matters. `GraphWeaver.execute(schema:, query:, variables: {})` is
-the one-shot form.
+checking matters. `GraphWeaver.run(source, query, **variables)` — or
+`client.run` — is the one-shot form: parse and execute in one call, no module
+kept.
 
 Generated source is eval'd, so inputs are validated: module names must be
 constant names, and query heredocs can't be terminated early. Still: queries