graph_weaver 0.7.4 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f631eac2f0c9bbd78b50cfe1b7a0178911a8939cc697d57328bc63b3b60cd0d7
-  data.tar.gz: 771837c86ab744d47de6b1f58e990575ee7618d9cb362e871614f6aeebcded18
+  metadata.gz: 3a68eaeb8cd0f3139cc9e50b88d98a50e04acd0c2c94c7825233f04405d30c42
+  data.tar.gz: '08df5051075500cb81c710cd65705f387dec16bc29a626e2b8069bbf5c61b3a1'
 SHA512:
-  metadata.gz: 8f24e3485d8ff839de3a9fd626b2c0038c0617c322b6249742aa90eae3552073d3cbf3335de430364072bfa990304689a7e9ad3db652ae527d46ac711573a276
-  data.tar.gz: a484029fbbdd141af8be0586d8a830e2439f13fdbbc1b9f4826840f289af3e000a81457749657e5573cd67c4ae2017aa2929bfb34a300e9777669b9265c22eb5
+  metadata.gz: ee7b2971697409f7180e31d40569fd44108404c0f1d811b259bec6e000f7cf82142e7640de164510d1dbd253916392c6cc866619ee2d37e35e610b1ed0be9741
+  data.tar.gz: 9d219008a1db9bc353ef3b033b9c39f64657e58d1d2548fb074fc1a60973052e4abd0c1950d93622ad1cfc0414e7ca1219d9c770e32e445cedba287636f58a73

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.4)
+    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.4)
+  graph_weaver (0.7.6)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5

data/README.md

@@ -146,6 +146,7 @@ when you've skipped it.
 - **[Against a real API](docs/real_world.md)** — introspecting a live endpoint, GitHub end to end
 - **[Logging](docs/logging.md)** — point `GraphWeaver.logger` at any Logger
 - **[Upgrading](docs/upgrading.md)** — regenerate on every bump, and what each release moved
+- **[Migrating](docs/migrating.md)** — coming off graphql-client or a hand-rolled client, commit by commit
 - **[Alternatives](docs/alternatives.md)** — graphql-client, graphlient, artemis, hand-rolled: what each is good at, and where this one loses
 
 ----

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 |
@@ -172,7 +173,10 @@ A nested filter reports the innermost input type, so the error points at the inp
 that actually held the bad field; passing something that is neither — a bare
 `String` where the input goes — reports the same way. A call site that *spells* the
 wrong type is caught earlier and better, by `srb tc`
-([why](generated_modules.md#variables-become-typed-kwargs)).
+([why](generated_modules.md#variables-become-typed-kwargs)). And once a boundary
+of your own between that call site and `execute` carries a sig, sorbet-runtime
+checks the value there first: the caller sees a plain `TypeError`, and none of
+the structured, translatable detail below ever reaches it.
 
 The one-shot `GraphWeaver.run` / `run!` mirror `execute` / `execute!`.
 
@@ -216,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))
@@ -464,7 +471,7 @@ than leaving you sorbet's words:
 | what came back | what the message adds |
 |---|---|
 | an `ID` the server sent unquoted | GraphQL serializes `ID` as a JSON string, so this is the server out of spec — plus how to take it anyway (`register_scalar("ID", "T.untyped")`) |
-| an enum value the generated enum doesn't hold | the values it does hold, and that drift is the likely cause: regenerate, or `register_enum(fallback:)` to absorb them |
+| an enum value the generated enum doesn't hold | the values it does hold, and that drift is the likely cause: regenerate, or `register_enum("Species", fallback: true)` to absorb them into `Other` |
 | a field the server nulled **with a reason** | the server's own explanation, rather than only sorbet's nil complaint |
 
 Simulate one in tests with

data/docs/generated_modules.md

@@ -61,6 +61,18 @@ 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.
 
+Code that takes *any* generated module — a persisted-query manifest, a
+transport of your own — types it as `GraphWeaver::QueryModule` and reads the
+same two through `query_string` and `operation_name`, which carry sigs. That is
+the spelling rubocop-sorbet allows: `mod.const_get(:QUERY)` on a `Module` is
+`Sorbet/ConstantsFromStrings`, and the `T.unsafe` that gets around it is
+`Sorbet/ForbidTUnsafe`.
+
+```ruby
+sig { params(mod: GraphWeaver::QueryModule).returns(String) }
+def manifest_line(mod) = "#{mod.operation_name}: #{mod.query_string.bytesize} bytes"
+```
+
 A `Result` is an **ordinary Ruby object**: value `==` (with `eql?` and `hash`,
 so a result works as a hash key), `deconstruct_keys` for pattern matching,
 `#to_h`, and `#to_json`/`#as_json`. All of them go the whole way down a nested
@@ -167,10 +179,11 @@ query: `pet: pets { name }` generates `Pet` (and a `.pet` accessor).
 
 **Union and interface members** are the one name that doesn't come from a key:
 they take 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; and several fields sharing
-one collapsed union type take the first of their keys alphabetically. Still
-position-determined, all of it.
+the container named for the field, plus the catch-all `Other`; a type
+[hoisted](#a-shared-fragment-is-one-type) out of a shared fragment is named for
+the fragment; and several fields sharing one collapsed union type take the first
+of their keys alphabetically. Still position-determined, all of it — a fragment
+name is a source fact like a result key.
 
 Two collisions are handled rather than left to surprise you. A name that would
 shadow the struct it nests in (`pet { pet { ... } }`) takes a numeric suffix
@@ -321,6 +334,12 @@ Both spellings then cast to `Status::LegacyMode`, only the target gets a
 constant, and a variable sends the target — see
 [scalars.md](scalars.md#two-spellings-one-value).
 
+A value the *server* adds after you generate is drift, and casting it raises by
+default. `register_enum("Species", fallback: true)` gives the generated enum one
+extra member, `Other`, that every undeclared wire value casts to — the same
+catch-all an abstract type's dispatch always carries. A variable can't send it;
+see [scalars.md](scalars.md#values-the-server-hasnt-told-you-about-yet).
+
 `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,
@@ -369,6 +388,46 @@ schema's spelling in both directions, so the query, the request, the response,
 and `#as_json`/`#to_json` are untouched and `render json: result` never leaks a
 trailing underscore.
 
+### A shared fragment is one type
+
+**A whole field selected as exactly one named shared fragment is one type in
+`GraphQLTypes`, named for the fragment, which each query aliases.** Object or
+abstract, same sentence:
+
+```graphql
+# app/graphql/fragments/pet_fields.graphql
+fragment PetFields on Pet { name species birthday }
+
+# two queries, one Ruby type
+query Roster  { pets           { ...PetFields } }
+query Shelter { shelter { pets { ...PetFields } } }
+```
+
+```ruby
+GraphQLTypes::PetFields                       # the struct, generated once
+RosterQuery::PetFields                        # the alias each query opens with
+sig { params(pet: GraphQLTypes::PetFields).returns(String) }  # nameable by your app
+```
+
+That is what makes the fragment the unit of reuse on *both* sides of the wire: a
+presenter, a serializer or a policy can name its argument's type, and a union
+spread this way gives one exhaustive `case … T.absurd` everywhere instead of a
+fresh dispatch module per query.
+
+It is opt-in by how you write the query, and only the exact shape hoists —
+`{ ...PetFields id }`, `{ ...PetFields ...Vaccinations }`, a spread carrying
+`@skip`/`@include`, a fragment the query file defines itself, and a fragment
+written on some other type than the field's all stay a position-named struct
+where they are. A spread *inside* a hoisted fragment is inlined into it rather
+than hoisted again. Like shared inputs, it's a `generate!`-directory concern;
+dynamic `parse` inlines everything.
+
+Registrations follow the type, not the position, so `extend_type("Pet", …)`
+mixins and `alias:` accessors land on the hoisted struct exactly as they would
+on a local one. An `alias:` path on the *parent* may end on the hoisted struct
+(`alias: { first_pet: "pets.first" }`) but not read through it — the struct
+belongs to another module — and says so at generation.
+
 ### Abstract types
 
 An abstract field emits **one struct per type condition the selection names**,
@@ -402,11 +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.
 
-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.
+A whole abstract field selected as one named *shared* fragment
+(`{ ...FeedItemFields }`) is [hoisted](#a-shared-fragment-is-one-type) into
+`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`
 
@@ -438,8 +498,9 @@ you handle it.** It is exhaustive over the members *this query asked about*, plu
 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.
+to hold it as one type across queries
+([above](#a-shared-fragment-is-one-type)); if all you have is the bare tag,
+`__typename` is the common denominator, unchecked.
 
 ## Type helpers
 
@@ -503,6 +564,22 @@ the one thing you couldn't add by hand: a `const` has no sig to put it in.
 `T.unsafe(self).name` also silences it, at the cost of checking nothing. Either
 beats `# typed: false` for a helper you want checked.
 
+**An `abstract!` mixin has a precondition: every query must select what it
+declares.** The mixin goes into *every* struct generated from the type, so a
+query selecting a subset has nothing to satisfy the rest, and generation refuses
+— naming the struct, the mixin, the members, and the two ways out: select them
+in that query, or select the type through one
+[shared fragment](#a-shared-fragment-is-one-type), which hoists a single struct
+for every query to share. The second is usually the answer: a shape several
+queries lean on is a fragment.
+
+One sig a mixin cannot write is one over a *generated* type — `sig {
+abstract.returns(GraphQLTypes::Species) }` raises `NameError` at generation,
+because registrations load before the enum that generation is about to write.
+The field's sig has to be `T.untyped` there. The struct's own `const` still
+carries the real type, so a call site reading `pet.species` is checked; only the
+mixin's view of it isn't.
+
 ### Flat accessors with `alias:`
 
 The one derivation the generator can type for you is a plain projection — a
@@ -528,7 +605,8 @@ 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
+(`name_with_owner.tag`), not wire names. It may end on a
+[hoisted](#a-shared-fragment-is-one-type) struct but not read through one. 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
@@ -597,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
@@ -679,8 +757,8 @@ it goes. The schema dump is step 0: codegen reads it, never a live endpoint, and
 generating without one fails pointing at exactly that.
 
 **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
+Input types, schema enums, and the types 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
@@ -716,6 +794,43 @@ spot a *schema* change for you — `schema:diff`, `schema:refresh`, `queries:che
 — are in [getting started](getting_started.md#5-verify-in-ci); a
 [`schema_stale?`](errors.md) error in production is the late signal.
 
+### Make your tooling treat generated/ as generated
+
+Three readers, three tellings — and `rails g graph_weaver:install` writes the
+two that live in files:
+
+- **You.** Every generated file opens with `# Generated by GraphWeaver
+  <version> — do not edit.`
+- **Rubocop.** The output directory goes into `AllCops: Exclude:` — machine-written
+  code isn't yours to style, and plain `rubocop` otherwise fires
+  `Style/Documentation` on every struct and `Metrics/*` on every `from_h`.
+- **GitHub.** `linguist-generated` collapses these files in a pull-request diff
+  (shown as "Load diff") and drops them from the repository's language
+  breakdown. It is display-only: they stay versioned, expandable, and `git diff`
+  here is unchanged.
+
+An app that didn't run the installer adds the two by hand:
+
+```yaml
+# .rubocop.yml — inherit_mode keeps rubocop's own Exclude defaults
+AllCops:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "app/graphql/generated/**/*"
+```
+
+```text
+# .gitattributes — gitignore-style, so `dir/**` is everything beneath it
+app/graphql/generated/** linguist-generated
+```
+
+`git check-attr linguist-generated app/graphql/generated/types.rb` answers `set`
+when the pattern is right. One line per graph in a multi-schema app, and
+[linguist's overrides](https://github.com/github-linguist/linguist/blob/main/docs/overrides.md)
+has the other attributes it reads.
+
 ### Loading what it wrote
 
 In Rails, loading is automatic — the Railtie requires every generated file at
@@ -735,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

@@ -6,6 +6,8 @@ Follow it once when you add the gem to an app. Rails is assumed;
 [not Rails?](#not-rails) covers the differences. Exploring an API from a console
 instead? Start with [dynamic mode](real_world.md) — no build step. No Sorbet in
 your app? None needed — [Sorbet, with or without](#sorbet-with-or-without).
+Already have a GraphQL client? [Migrating](migrating.md) is the order to move
+off it in.
 
 ## 1. Install
 
@@ -96,6 +98,11 @@ What it wrote:
   marked "do not edit," so the output directory is added to `AllCops: Exclude:`.
   An `AllCops:` you already have is left alone (a second one would replace it,
   not merge); the generator prints the line to add.
+- **`.gitattributes`** — `app/graphql/generated/** linguist-generated`, which is
+  how GitHub is told the same thing: it collapses those files in a pull-request
+  diff and leaves them out of the repository's language breakdown. Display only,
+  so they stay versioned and expandable
+  ([the three tellings](generated_modules.md#make-your-tooling-treat-generated-as-generated)).
 
 Rake needs no wiring: in Rails the `graph_weaver:*` tasks register themselves and
 depend on `:environment`, so your initializer runs first. The generated modules
@@ -165,10 +172,11 @@ Fragment files hold only fragments (no operations), and names are unique across
 them. Point elsewhere with `GraphWeaver.fragments_paths` (an appendable list,
 default `app/graphql/fragments`).
 
-One payoff: when a shared fragment *is* the whole selection on a union field,
-its type is hoisted once into `GraphQLTypes` and every query that spreads it
-gets the same Ruby type — so one exhaustive `case … T.absurd` works everywhere.
-See [abstract types](generated_modules.md#abstract-types).
+One payoff: when a shared fragment *is* the whole selection on a field, its type
+is hoisted once into `GraphQLTypes` under the fragment's name and every query
+that spreads it gets the same Ruby type — so a presenter can take a
+`GraphQLTypes::PersonFields`, and a union's `case … T.absurd` works everywhere.
+See [hoisting](generated_modules.md#a-shared-fragment-is-one-type).
 
 ## 4. Test against fakes
 
@@ -216,9 +224,10 @@ Five questions, five tasks — the last only on a federated graph:
 Every one of them exits non-zero on a finding, so the gate is a chain.
 `verify` compares the committed generated files against what the current schema
 + queries + registrations would produce, so it belongs in every CI build.
-`schema:diff` asks whatever the dump came from — a recorded source url (with
-`GRAPHWEAVER_AUTH` for private APIs), or your own schema class when the app
-[serves the schema itself](#your-apps-own-schema-in-process) — and
+`schema:diff` asks whatever the dump came from — the source url the dump
+recorded (with `GRAPHWEAVER_AUTH` for private APIs), your own schema class when
+the app [serves the schema itself](#your-apps-own-schema-in-process), else the
+client this graph's modules already post to — and
 `rake graph_weaver:schema:refresh` is the repair either way. On an app with more
 than one schema, `rake graph_weaver:graphs` lists which graphs are configured,
 where each generates, and what each registers.
@@ -283,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
-recorded url (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
@@ -294,6 +305,12 @@ app/graphql/queries/person.graphql
 1 invalid query
 ```
 
+A dump that records no url has nothing to re-read, and so does a graph that
+names its own schema: both are checked as they stand on disk. That is `verify`'s
+question rather than this one's, so the passing verdict names the file instead of
+claiming a check against the server ([a dump you already
+have](#a-schema-dump-you-already-have)).
+
 `GraphWeaver.check_queries` returns the same findings as data — a hash of file
 to `message`/`line`/`column`, empty when everything validates — so you can wire
 it into a spec, a Slack ping, an issue. Pass it `schema:` a *loaded* schema (not
@@ -331,15 +348,20 @@ app/graphql/queries/products.graphql: Products.sku — selected, never read (Cat
 Each line names the query file, the selection to go and delete, and the
 generated prop behind it. It reads the generated structs for the props a query
 produced, then sweeps your `.rb`, `.rake`, `.builder`, `.erb`, `.slim`, `.haml`
-and `.jbuilder` for every name they could be read by — `.sku`, `sku:`, `:sku`,
-`"sku"`. `PATHS=app,lib` narrows the sweep (a `PATHS=` naming a directory that
-isn't there is refused rather than swept as nothing); anything under a directory
+and `.jbuilder` — plus Ruby carrying no extension, which is any name under
+`bin/` or `exe/` and a ruby shebang anywhere else — for every name they could be
+read by: `.sku`, `sku:`, `:sku`, `"sku"`. `PATHS=app,lib` narrows the sweep (a
+`PATHS=` naming a directory that isn't there is refused rather than swept as
+nothing); anything under a directory
 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
@@ -416,6 +438,34 @@ Sets `GraphWeaver.schema_path` to that file rather than writing a second copy,
 and introspects nothing. A dump has no resolvers, so it can't execute — set
 `GraphWeaver.client` to whatever serves the API.
 
+**A dump you brought from elsewhere has no provenance**: it doesn't record the
+server it was introspected from, which is exactly what migrating off
+graphql-client leaves you ([migrating](migrating.md)). `rake
+graph_weaver:schema:refresh` adopts it — with no url on the file it introspects
+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.
+
+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 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
 
 The five steps above describe one graph — a schema, its queries, its output. An
@@ -468,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
@@ -484,8 +535,10 @@ 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. (`URL=` is for the app that has one
-dump and no graphs.)
+`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 —
 `graphql_fake(graph: :poke, "pokemon_v2_pokemon.name" => "pikachu")`. See
@@ -527,6 +580,106 @@ per-struct `extend T::Sig` in generated files is redundant — rubocop's
 time and skips the `extend`; override with `GraphWeaver.extend_t_sig =
 true`/`false`.
 
+### The types stop where your sigs do
+
+That typo is caught where the struct comes back. Hand the struct to one method
+without a sig and it is `T.untyped` from there on — the same typo, one layer in,
+is silent — and a sig on the method that produced it is no help either:
+
+```ruby
+# typed: true
+class PersonDirectory
+  extend T::Sig
+
+  sig { returns(T.nilable(PersonQuery::Result::Person)) }
+  def person = PersonQuery.execute!(id: "1").person
+end
+
+class Profile
+  def initialize(person)   # no sig, so @person is untyped
+    @person = person
+  end
+
+  def title = @person.nmae   # "No errors! Great job."
+end
+
+class Page
+  def initialize(directory)   # nor is the sig above any help here
+    @directory = directory
+  end
+
+  def title = @directory.person&.nmae   # also clean
+end
+```
+
+Every hop has to be sig'd: the method that produces the struct, any wrapper it
+passes through, and the constructor that stored the collaborator. Two shapes
+cover most of an app.
+
+A wrapper that only passes a block through keeps the block's type with
+`type_parameters`:
+
+```ruby
+# a rescue wrapper that keeps the block's type
+sig do
+  type_parameters(:T).params(blk: T.proc.returns(T.type_parameter(:T)))
+   .returns(T.type_parameter(:T))
+end
+def people(&blk) = yield
+```
+
+A service boundary spells the struct it hands out, and whoever holds that
+service types the ivar:
+
+```ruby
+class Page
+  extend T::Sig
+
+  sig { params(directory: PersonDirectory).void }
+  def initialize(directory)
+    @directory = directory   # the sig is what types this ivar
+  end
+
+  sig { returns(T.nilable(String)) }
+  def title = @directory.person&.nmae   # now srb tc has it
+end
+```
+
+That is sigs on half a dozen service methods and a couple of constructors before
+the first typo in a layered app is caught. Budget it as its own piece of work
+rather than as part of generating the types — and if it isn't work you're going
+to do, the runtime half still holds: a bad field is a `NoMethodError` the first
+time the line runs.
+
+### Give a struct a short name where you name one
+
+A generated struct's constant path spells out the query that produced it, which
+is what makes it stable — and long. Where your own code names one in a sig, alias
+it once, in the class that hands it out:
+
+```ruby
+# before
+sig { params(code: String).returns(T.nilable(Countries::CountryProfileQuery::Result::Country)) }
+
+# after
+class Directory
+  Country = Countries::CountryProfileQuery::Result::Country
+
+  sig { params(code: String).returns(T.nilable(Country)) }
+end
+```
+
+Use a plain constant, not `T.type_alias`: the constant works in a sig *and* as a
+value (`Country.from_h`), and in a `# typed: strict` file it needs no `T.let`
+around it. Reach for `T.type_alias` only where a constant can't express the type
+— a union of two queries' structs.
+
+That takes the worst sig in one migrated app from 116 characters to 72, and the
+callers get the short name too: a presenter takes a `Directory::Country` and
+stops knowing which `.graphql` file produced it. It is also what makes the sig
+chain above affordable, since a sig usually goes unwritten because the line is
+too long to want to write.
+
 ## Not Rails?
 
 There's no generator, but what it writes is short — a few lines wherever your
@@ -541,6 +694,15 @@ 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
+building it lazily to dodge that earns `Dynamic constant references are
+unsupported` from `srb tc`. One line of ordering settles both.
+
 ```sh
 mkdir -p app/graphql/queries app/graphql/generated
 rake graph_weaver:schema:refresh URL=https://api.example.com/graphql