graph_weaver 0.7.5 → 0.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53034719b6dcd597d098091606e08b6f4a33a15a89826374cf6b14df841aa0fc
-  data.tar.gz: cb64c3e12070f522a44353066aaac80ea7faf9df7d8a564a1abfcd053584049b
+  metadata.gz: a7b665c1263db52f315217a6298ff638d963b926e44f94c16dc2972de4140320
+  data.tar.gz: a9712a11f712adfa8846b180b1e22874f63d57fd00514d311b9cb0e60c9f6ebf
 SHA512:
-  metadata.gz: 6b320bc47a5839ef8561f44ac12b78eba36cc8b33078397f2818db59ce1268fef5f3b6b4aa347ef1e21443c9e213dd1ea6c5a297d14d8fa5c651ff8bcacd3052
-  data.tar.gz: 35abfec468ca9f50327c7f6a33a7f881884c004daf294019dd0a27c12498c010ec4383404a86d7015ed74616d114978e62e081703acffbcba58b9b3abad69add
+  metadata.gz: 693fa12dd8117988b35adcf7f88234b382bae9a8d82307a23ce7ffa3f2837c1304a529155dedab414691b13c3d982314cb70c8d5587660f0766988c7defc0f83
+  data.tar.gz: 2933a687d3c85faa3d514e6daddd5fe9ea62ee6e48f146e847f492a63e91b6c43c6986964f52f1fa458f1f6a60b92038058357e21062e966c47c8fef0a0235c4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.7.5)
+    graph_weaver (0.7.7)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -62,7 +62,7 @@ GEM
     erubi (1.13.1)
     faker (3.8.0)
       i18n (>= 1.8.11, < 2)
-    faraday (2.14.3)
+    faraday (2.14.4)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -94,7 +94,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.21.2)
+    json (3.0.2)
     logger (1.7.0)
     loofah (2.25.2)
       crass (~> 1.0.2)
@@ -124,7 +124,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.4-x86_64-linux-gnu)
       racc (~> 1.4)
-    parallel (2.1.0)
+    parallel (2.2.0)
     parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
@@ -159,10 +159,10 @@ GEM
       tsort (>= 0.2)
       zeitwerk (~> 2.6)
     rake (13.4.2)
-    rbi (0.3.14)
+    rbi (0.4.3)
       prism (~> 1.0)
       rbs (>= 4.0.1)
-    rbs (4.0.3)
+    rbs (4.2.0)
       logger
       prism (>= 1.6.0)
       tsort
@@ -175,7 +175,7 @@ GEM
     regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
-    require-hooks (0.4.0)
+    require-hooks (0.5.1)
     rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -190,35 +190,35 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubydex (0.2.7-aarch64-linux)
-    rubydex (0.2.7-arm64-darwin)
-    rubydex (0.2.7-x86_64-darwin)
-    rubydex (0.2.7-x86_64-linux)
+    rubydex (0.4.1-aarch64-linux)
+    rubydex (0.4.1-arm64-darwin)
+    rubydex (0.4.1-x86_64-darwin)
+    rubydex (0.4.1-x86_64-linux)
     securerandom (0.4.1)
     simplecov (1.3.0)
-    sorbet (0.6.13498)
-      sorbet-static (= 0.6.13498)
-    sorbet-runtime (0.6.13498)
-    sorbet-static (0.6.13498-aarch64-linux)
-    sorbet-static (0.6.13498-universal-darwin)
-    sorbet-static (0.6.13498-x86_64-linux)
-    sorbet-static-and-runtime (0.6.13498)
-      sorbet (= 0.6.13498)
-      sorbet-runtime (= 0.6.13498)
-    spoom (1.8.3)
+    sorbet (0.6.13506)
+      sorbet-static (= 0.6.13506)
+    sorbet-runtime (0.6.13506)
+    sorbet-static (0.6.13506-aarch64-linux)
+    sorbet-static (0.6.13506-universal-darwin)
+    sorbet-static (0.6.13506-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13506)
+      sorbet (= 0.6.13506)
+      sorbet-runtime (= 0.6.13506)
+    spoom (1.8.7)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
-      rbi (>= 0.3.14)
+      rbi (>= 0.4.2)
       rbs (>= 4.0.0.dev.5)
       rexml (>= 3.2.6)
       sorbet-static-and-runtime (>= 0.5.10187)
       thor (>= 0.19.2)
-    tapioca (0.19.2)
+    tapioca (0.20.0)
       benchmark
       bundler (>= 2.2.25)
       netrc (>= 0.11.0)
       parallel (>= 1.21.0)
-      rbi (>= 0.3.7)
+      rbi (>= 0.4.1)
       require-hooks (>= 0.2.2)
       rubydex (>= 0.1.0.beta10)
       sorbet-static-and-runtime (>= 0.6.12698)
@@ -292,20 +292,20 @@ CHECKSUMS
   erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   faker (3.8.0) sha256=c147b308df73a90f27a4fc84f18d4c22ef0ad9c2a64b2b61c86fd0ca71753efc
-  faraday (2.14.3) sha256=1882247e6766615c8220b4392bf1d27f6ebb63d8e28267587cef1fb0bf37f278
+  faraday (2.14.4) sha256=9bb4408c44621b0dbaaaa39e5dbfc4dbe58cc6751b6eb94d16ae9e1f2f2fab6e
   faraday-net_http (3.4.4) sha256=0e78af151747ed1b00f33e25973b4bc220d7f16c00c39676817c8b12331eb588
   fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
   google-protobuf (4.35.1-aarch64-linux-gnu) sha256=50ca44d0eeff3f8475e630a1accdd974256f3510694d574e2c9d6119ea8bc9e1
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.7.5)
+  graph_weaver (0.7.7)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
-  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  json (3.0.2) sha256=8e6d7e7b11384c21230430cef90b71f14849a34a1f4452796670f7c981bd19df
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   loofah (2.25.2) sha256=2007f746959ac65552456e04b433e83deb22759ab38c838b4445c70e43425918
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
@@ -317,7 +317,7 @@ CHECKSUMS
   nokogiri (1.19.4-arm64-darwin) sha256=a46db9853286e6597b36ebc6953817d15acf3a299583eb3f89fdc6f91dd63527
   nokogiri (1.19.4-x86_64-darwin) sha256=7fd17057d3e1f00e9954a74b3cd76595d3d4a5ef233b7ed9599047c204f70551
   nokogiri (1.19.4-x86_64-linux-gnu) sha256=379fae440b28915e3f19d752ce2dcf8465ed2b2fbefd2a7ca0dd497bc981a06a
-  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parallel (2.2.0) sha256=e1059c5fd7b649558a0aec38a769f06a42942bdb40503d005a59c352fe011cd8
   parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
@@ -332,33 +332,33 @@ CHECKSUMS
   rails-html-sanitizer (1.7.1) sha256=e797a7c9b01e567307e317c576b49ab4168017e63eea4dba9ce3cb587e2f22c2
   railties (8.1.3.1) sha256=2388a232579a00cefea4487de66c8553c3408c1300abdc6cf1799d86ffb04487
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
-  rbi (0.3.14) sha256=932ed904adbb5ca645c285c8b36da1b7ff6321ec1870d187d6325248cb637658
-  rbs (4.0.3) sha256=5a7bf70e2628549d9a1f44eae447b2cfe55968a9c60cfff52693a4bdcc020e14
+  rbi (0.4.3) sha256=cc090ae62c3246412b992954f54077d6046c9b04f1537a4d24bfae8714503eac
+  rbs (4.2.0) sha256=51f7b886dcc05bc09e10b901daa6a81829f6adc03101d6ca9ea4aac6103e0674
   rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
   redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  require-hooks (0.4.0) sha256=005f4c6435b4edae73e358cdbaba48370a4121f9ce893d5d2a3c66fce855677d
+  require-hooks (0.5.1) sha256=49a6b14518b91c5b8006d0644ef257af0ca033df23625bd4e314a8c5282191d9
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
   rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
   rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
   rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
   rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
   rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
-  rubydex (0.2.7-aarch64-linux) sha256=9a016039f7e94e55cd812e073d310de7effcce4cac560edd1185e1ce6b5b4eb0
-  rubydex (0.2.7-arm64-darwin) sha256=f0d28bbf4153568be79b671642424750053e0bea971b60ddf5cec19bf4563990
-  rubydex (0.2.7-x86_64-darwin) sha256=b002b259d118ac69de44470eff1597143318402c45630c47371f9542631447dc
-  rubydex (0.2.7-x86_64-linux) sha256=dacfade9fa42ce4469618da6dac07e69d5f3ac6a313b4caced5234c8f052419a
+  rubydex (0.4.1-aarch64-linux) sha256=abc1c9eb22479f60dd015fa81373163c5a71f2700b76bced1282631686bd6271
+  rubydex (0.4.1-arm64-darwin) sha256=d23720253876d88fb98954e5d3a1ef9696a269697acf50e3ab53cdfbb2b66b96
+  rubydex (0.4.1-x86_64-darwin) sha256=a9681db5bc9be6a62f226d96d6889b6b600d0b09e7576391702aafd29912145b
+  rubydex (0.4.1-x86_64-linux) sha256=4e2c8398c9fc585485b54edd28f5ecf76b5a02255e177b6f8402e9d2afffd51b
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
   simplecov (1.3.0) sha256=d9886307863c1ead47657dcbed869bfffd82318808b09014d8f0ff77dcfe7492
-  sorbet (0.6.13498) sha256=cb5279f6a9dbfc8d526bc9fb71d05020afb8043c40708e4aff2244ba329ce224
-  sorbet-runtime (0.6.13498) sha256=2da4627f9341a1fc6e4148cc891989b7b108106c206c46ca69940e10a21e9133
-  sorbet-static (0.6.13498-aarch64-linux) sha256=cbee732c49379d38029f295b45edaeb5757ab180d308d8383dc79f03fd4991be
-  sorbet-static (0.6.13498-universal-darwin) sha256=4cc97aa0da3dd175b8278e1617954d6dd9ba1f5aeb62981f21616b9ec791fb75
-  sorbet-static (0.6.13498-x86_64-linux) sha256=75d02e8af7d6c1081d4693e2ebefe679760327f1304377519970784faf9f913d
-  sorbet-static-and-runtime (0.6.13498) sha256=5f5686869dceae893b4171b05e3db159fe12f1aadf04aa8c2bf9dfa3edc0d902
-  spoom (1.8.3) sha256=32871fa189bbfa49cf557a50f819f23cc9a6ceefd0346caa7a6adc193becd5dd
-  tapioca (0.19.2) sha256=938731b07811aee8d23871b1aee8861d464fbaf2cfffbf79a62b0c869a5120ec
+  sorbet (0.6.13506) sha256=b6fd9f9ab2563c709b9308437cb40754e190667fddfe841723a7dda430978cd6
+  sorbet-runtime (0.6.13506) sha256=94a7ff795cf2a67818a954883c0301de0b7222a9f732b24ab30ea5253e7568f6
+  sorbet-static (0.6.13506-aarch64-linux) sha256=04405070206de265a87e6544454092cd4c7b275415dccf76a4ab41649819ae9f
+  sorbet-static (0.6.13506-universal-darwin) sha256=744918a125841c84d0804410bfda068a6dc8182285ba50ddb1e8ce5955b24700
+  sorbet-static (0.6.13506-x86_64-linux) sha256=b57d36d1db374e10109bbd5af3bec0edf6f94f3e86dbffe69199763909ad2c91
+  sorbet-static-and-runtime (0.6.13506) sha256=12c6abbc1d988267452c97e4cff75c563a480e3e8b7a1a633e2f714856e5c313
+  spoom (1.8.7) sha256=81960502cdf23aa991f015988aa5dd43325e23ae4318b8e00d541299cbdb70f6
+  tapioca (0.20.0) sha256=b375ed7bf51d2c86c09543eafedd0de85513634187c0f7a062615af8bb9347a0
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b

data/docs/errors.md

@@ -106,6 +106,7 @@ subclass says where it failed:
 | `InputError` | the variables wouldn't build into the generated input structs — unknown/typo'd key, missing required field, out-of-range enum, wrong-typed field, wrong number of @oneOf fields — `#kind`, `#path`, `#coordinate`, `#value`, `#details`, `#field`, `#struct` |
 | `QueryValidationError` | build time: the query didn't validate against the schema |
 | `Codegen::Aliases::UnknownSegment` | build time: an [`alias:`](generated_modules.md#flat-accessors-with-alias) path names a field no type here has — a typo, so `optional: true` won't skip it |
+| `Codegen::Aliases::HoistedSegment` | build time: an [`alias:`](generated_modules.md#flat-accessors-with-alias) path reads *into* a struct [hoisted](generated_modules.md#a-shared-fragment-is-one-type) from a shared fragment — `optional: true` skips it, but only at the cost of the accessor for every query that spreads the fragment |
 | `ConfigurationError` | setup judged against your schema — which Ruby schema serves which subgraph (`Testing::Router`, `federation:diff`) |
 | `Testing::Unplannable` | the local test router won't plan this operation — `#category`, `#detail` |
 | `Testing::MissingRecording` | a [cassette](cassettes.md) holds no entry for this request — the message prints the variables, and the ones it did record |
@@ -219,9 +220,12 @@ a form keyed on `e.field` finds the same slot for a refusal raised before the
 request left and for one the server sent back.
 
 The **prop** (`issued_on`) is what you type in Ruby — `.new`, `.coerce`, the kwargs
-of `execute` — and it is `#message`, the developer's line, that names it. In a
-Rails form the field names are the props, so underscore on the way in — and give
-the nil case a home, because **`#field` is `nil` whenever nothing named a slot**:
+of `execute` — and it is `#message`, the developer's line, that names it, with the
+schema's spelling beside it where the two differ (`issued_on (issuedOn): expected
+a String`): the prop is what you fix, and the wire name is what you grep the
+`.graphql` for. In a Rails form the field names are the props, so underscore on
+the way in — and give the nil case a home, because **`#field` is `nil` whenever
+nothing named a slot**:
 
 ```ruby
 form.errors.add(e.field&.underscore || :base, render_input_error(e))

data/docs/generated_modules.md

@@ -142,7 +142,9 @@ file, and `verify` fails until you regenerate.
 **A graph's `namespace:` nests what it generates**, and is the answer when two
 schemas in one app each have a `person.graphql`: `namespace: "Billing"` makes
 that one `Billing::PersonQuery` in the same `person_query.rb`, and its shared
-types module `Billing::GraphQLTypes`. Nothing else about the rule changes. See
+types module `Billing::Types` (plain `Types` inside a namespace, where nothing
+collides with graphql-ruby's own `Types::`; `GraphQLTypes` without one). Nothing
+else about the rule changes. See
 [getting started](getting_started.md#more-than-one-schema).
 
 Parsing a raw query *string* has no file to name it after, so it uses the
@@ -461,10 +463,12 @@ off `__typename` when the selection carries one unaliased and unguarded, and off
 narrowed fragment, or one whose `__typename` is itself guarded, is refused: a
 match would be indistinguishable from a miss.
 
-A whole union field selected as one named *shared* fragment
+A whole abstract field selected as one named *shared* fragment
 (`{ ...FeedItemFields }`) is [hoisted](#a-shared-fragment-is-one-type) into
-`GraphQLTypes` like any other, so the same union is one Ruby type family across
-queries rather than a fresh dispatch module per query.
+`GraphQLTypes` like any other, in whichever of the three shapes above the
+fragment has — a dispatch module, one struct, or a nilable narrowed struct. So
+which shape it is never decides whether consuming queries share a type, and
+adding a second `... on` to a shared fragment doesn't move their constant.
 
 ### Consuming a union — dispatch on the class, not `__typename`
 
@@ -673,7 +677,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
@@ -831,10 +835,8 @@ has the other attributes it reads.
 
 ### Loading what it wrote
 
-In Rails, loading is automatic — the Railtie requires every generated file at
-the end of boot, after your initializers and after any registrations of your own
-in a `to_prepare` block, and again after each development reload. Elsewhere it's
-explicit, factory_bot-style:
+In Rails, loading is automatic — [one rule](#the-rule-in-rails) decides whether
+Zeitwerk does it or the Railtie does. Elsewhere it's explicit, factory_bot-style:
 `GraphWeaver.load_generated!` requires every file under `generated_paths`.
 
 **Outside Rails, four things have to agree**, and nothing wires them together for
@@ -848,8 +850,10 @@ you — a script that generates its own modules sets all four:
    other [client](#clients) to reach for.
 
 Miss (3) and the script gets a `NameError` for its own module; miss (4) and it
-gets `PersonQuery: client must respond to #execute(query, variables:), got
-NilClass` from a module that otherwise looks fine.
+gets `no client configured — set GraphWeaver.client= or pass a client` from a
+module that otherwise looks fine. Set the slot to something that can't execute
+and the module names the contract instead: `PersonQuery: client must respond to
+#execute(query, variables:, operation_name:), got Hash`.
 
 Every directory setting is a list — `queries_paths`, `generated_paths`,
 `fragments_paths` — and every entry is read (entries may be globs; the generated
@@ -861,11 +865,57 @@ list would name a dump nothing ever opens. A relative path resolves against
 `GraphWeaver.root` — `Rails.root` in a Rails app, the working directory otherwise
 — so where you started the process doesn't change which files it reads.
 
-Plain requires, not Zeitwerk: Zeitwerk would expect `Generated::PersonQuery` from
-`generated/person_query.rb`. In development a query edit regenerates and reloads
-before the next request; everywhere else generated code changes only on
-regeneration — restart, like a schema migration, or call
-`GraphWeaver.reload_generated!` after regenerating in another terminal.
+#### The rule in Rails
+
+**A generated tree Zeitwerk would name correctly is left to Zeitwerk; any other
+is hidden from it and required at boot.**
+
+The conventional layout is the second one: `generated/person_query.rb` defines
+`::PersonQuery` where Zeitwerk reads `Generated::PersonQuery` off the path. So
+the Railtie hides that directory from the autoloader and requires every file at
+the end of boot — after your initializers and after any `to_prepare`
+registrations of your own, and again after each development reload.
+
+A tree is named correctly when the graph's [`namespace`](getting_started.md#more-than-one-schema)
+is the constant its output path spells:
+
+```ruby
+GraphWeaver.graph :reports do
+  output    "app/graphql/queries/reports/generated"
+  namespace "Queries::Reports::Generated"
+end
+```
+
+`report_query.rb` then defines `Queries::Reports::Generated::ReportQuery`, which
+is exactly what Zeitwerk expects there — your own `inflect`/`acronym` rules
+included, since graph_weaver asks the loader rather than guessing. Nothing is
+hidden and nothing is required: the modules autoload on first reference and
+reload with the rest of the app, and **no part of the parent namespace chain is
+defined until a query is used**. Leave `types_module` unset for it — the shared
+manifest is `types.rb`, which Zeitwerk reads as `<Namespace>::Types`, and `Types`
+is what a namespaced graph already calls it.
+
+The Railtie says which side each graph fell on, one line apiece at debug, naming
+the constant that disagreed:
+
+```
+graph :reports's output app/graphql/queries/reports/generated is hidden from
+Zeitwerk and required at boot — types.rb defines …::GraphQLTypes, Zeitwerk
+expects …::Types
+```
+
+**The settings have two lifetimes.** `schema`, `queries`, `output` and
+`namespace` matter only when `generate`/`verify` runs. `extend_type`,
+`register_scalar` and `register_enum` are needed wherever generated code *loads*
+— which under autoloading is the first request that uses a query, long after
+boot. So generation settings can live wherever generation happens, and
+registrations belong in `config/initializers` or a `to_prepare` block, where
+every boot runs them.
+
+In development a query edit regenerates and reloads before the next request;
+everywhere else generated code changes only on regeneration — restart, like a
+schema migration, or call `GraphWeaver.reload_generated!` after regenerating in
+another terminal.
 
 ## Dynamic mode
 

data/docs/getting_started.md

@@ -292,9 +292,11 @@ omits it. Any drift exits non-zero — whether a change matters is yours to judg
 (`#breaking`, `#compatible`, `#to_h`, `#empty?`).
 
 `queries:check` answers the question that matters when the schema *has* moved:
-**which of your queries no longer validate, and why.** It re-introspects the url
-the dump records (without rewriting the dump) and validates every `.graphql` file
-against the schema as it is right now, naming each error's line and column:
+**which of your queries no longer validate, and why.** It re-introspects
+whatever is behind each graph's dump (without rewriting the dump) — the same
+source `schema:refresh` rewrites from and `schema:diff` compares against — and
+validates every `.graphql` file against the schema as it is right now, naming
+each error's line and column:
 
 ```
 app/graphql/queries/person.graphql
@@ -355,8 +357,11 @@ named `generated`, plus `vendor`, `node_modules`, `tmp` and `log`, is skipped,
 as is any file defining a graphql-ruby **type** — a `field :sku` there is your
 *server* offering a field, not this app reading one back. A module handed whole
 to a serializer (`render json:`, `to_h`, `as_json`, a local and all) counts every
-prop as read, and the report quotes the line it followed. Nothing is edited and
-the exit is 0; `STRICT=1` exits 1 when anything is unread.
+prop as read, and the report quotes the line it followed — a plain local stands
+for the module only inside the method it was assigned in, so a same-named block
+param in the next method credits nothing, while an `@ivar` crosses that boundary
+the way a `before_action` does. Nothing is edited and the exit is 0;
+`STRICT=1` exits 1 when anything is unread.
 
 **It is a lint, not a proof**, and the task's own footer says so. It matches
 names as text, so a prop called `name` counts as read the moment anything says
@@ -441,18 +446,25 @@ the client the graph names, rewrites the dump, and records the source, so every
 later refresh and `schema:diff` re-read the right server. `URL=` names the
 endpoint instead, if you'd rather say it once than configure the client first.
 
-Do it early. Until the dump records a source, `queries:check` has nothing to
-re-introspect, so it validates against the committed file — a real check, but
-`verify`'s question rather than this one's — and the verdict says which:
+Until there is something behind the dump to re-read — the url it records, the
+server the graph's client posts to, or the graphql-ruby class that client runs
+in-process — `queries:check` validates against the committed file: a real check,
+but `verify`'s question rather than this one's, and the verdict says which:
 
 ```
 every query validates against db/schema.graphql as committed — not the server (rake graph_weaver:schema:diff asks whether the server moved)
 ```
 
-A dump with no recorded url and no client behind it *is* the schema — a
-hand-maintained SDL nothing serves. `schema:refresh` leaves that one alone
-(`records no source url and the graph names no client — left as checked in`) and
-refreshes the rest, rather than taking the whole task down with it.
+A dump with none of those behind it *is* the schema — a hand-maintained SDL
+nothing serves. All three tasks say so in one sentence:
+
+```
+db/schema.graphql records no source url and the graph names no server behind it — no client posting to one, and no graphql-ruby schema class in this process — so the file is the schema and nothing here can re-read it
+```
+
+`schema:refresh` steps over that graph and refreshes the rest; `schema:diff`
+still exits 1, because a gate that passes on having compared nothing is worse
+than one that says so.
 
 ## More than one schema
 
@@ -484,7 +496,7 @@ plus `register_scalar`, `register_enum` and `extend_type`).
 | `output` | one directory — where this graph's generated Ruby is written |
 | `client` | what this graph's modules execute against — a client, or the name of the constant holding one |
 | `namespace` | a constant, or its name — what every constant this graph generates nests under |
-| `types_module` | a constant name for the shared types module (default: `GraphQLTypes`, under `namespace`) |
+| `types_module` | a constant name for the shared types module (default: `Types` under a `namespace`, `GraphQLTypes` without one) |
 
 **Declaring graph two means declaring graph one.** A declared graph *replaces*
 the implicit one the top-level settings describe, so the moment any graph is
@@ -506,15 +518,19 @@ 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
 global, so two schemas that both have a `person.graphql` would otherwise fight
 over one name; without a namespace the collision is refused at generation,
-naming both files. **The block's registrations reach that graph alone**, laid
+naming both files. **A namespace that is the constant the output path spells is
+also what makes the tree autoloadable** — graph_weaver then leaves it to Zeitwerk
+instead of hiding it and requiring it at boot
+([loading](generated_modules.md#the-rule-in-rails)). **The block's registrations reach that graph alone**, laid
 over the top-level ones — so `Money` is checked against the schema it was
 registered for, and against no other.
 
@@ -522,8 +538,9 @@ An app that is a pure client of someone else's GraphQL owns no schema class, so
 every graph's `schema` is a dump. Give each the file you want and a `client`
 that can fetch it: `rake graph_weaver:schema:refresh` introspects each graph's
 client into its own dump, recording the url so every later `schema:refresh` and
-`schema:diff` re-reads the right server. A graph with neither a recorded url nor
-a client is left as checked in and the rest still refresh. (`URL=` is for the
+`schema:diff` re-reads the right server. Every graph is its own job — one with
+no server behind its dump is left as checked in, one whose server is down is
+reported under its own heading, and the rest still refresh. (`URL=` is for the
 app that has one dump and no graphs.)
 
 In specs, `graph:` is how an example says which graph a helper stands in for —
@@ -680,6 +697,9 @@ GraphWeaver.client = GraphWeaver.new(
 GraphWeaver.load_generated!   # no Railtie to require the generated files
 ```
 
+**A public API needs no `auth:`** — leave the line out. It is in the example
+because most endpoints want a token, not because the constructor asks for one.
+
 **`load_generated!` goes before your own requires** when anything your app loads
 names a generated constant as it loads — a `STATUS_LABELS` table keyed on
 `GraphQLTypes::ShipmentStatus` raises `uninitialized constant` otherwise, and