graph_weaver 0.5.0 → 0.6.0

data/docs/upgrading.md

@@ -1,18 +1,199 @@
-# Upgrading to 0.5.0
+# Upgrading
 
-0.5.0 is one large breaking release. Almost all of it is caught mechanically —
-the work is running three commands and following what they tell you.
+## Regenerate on every upgrade
+
+**Any release can change what codegen emits.** Patch releases included — most of
+them are fixes to a generated type, and a fix to a type is a change to the bytes.
+0.5.1 was a patch and moved three of them.
+
+So `rake graph_weaver:generate` is part of upgrading the gem, every time, and
+`rake graph_weaver:verify` is the detector: it fails when the checked-in Ruby
+isn't what this version would write. Nothing beyond that is promised — there is
+no "generated output is stable within a minor" rule to lean on. What each release
+changed, and whether it needs a regenerate, is in the changelog.
+
+A generated file's header names the release that wrote it, so the first `verify`
+after an upgrade reports the tree as stale whether or not codegen actually
+moved. That's the reminder working, not a false alarm.
+
+Generation is deterministic, so the diff is exactly what the new version emits
+differently and nothing else — worth reading rather than rubber-stamping.
+
+## Upgrading from 0.5.1
+
+Much smaller than 0.5.0, and mostly mechanical. Three commands find most of it:
+
+```sh
+rake graph_weaver:generate   # 1. what codegen emits moved in several places
+srb tc                       # 2. kwargs that got narrower are call-site errors
+bundle exec rspec            # 3. every deleted knob raises where it's still set
+```
+
+The rest of this section is what those three don't catch.
+
+### Loose input coerces, so `coerce:` and `auto_coerce` are gone
+
+`execute(first: params[:first])` converts the String to an `Integer` — for every
+variable and every input-object field, with nothing to switch on. The old way of
+buying that was `GraphWeaver.auto_coerce` or `register_scalar(…, coerce: true)`,
+and both paid for it by **widening the emitted kwarg**, which switched off the
+static check at every call site. Delete them:
+
+```ruby
+GraphWeaver.auto_coerce = true                             # gone
+GraphWeaver.register_scalar("Money", Money, coerce: true)  # drop the coerce:
+```
+
+Behavior is unchanged; the kwarg is not. It is now typed exactly as the schema
+types it, so a call site passing a **literal** of the wrong type is a new
+`srb tc` error — which is the point, since a literal is one you can just spell
+right:
+
+```ruby
+StargazersQuery.execute(first: "10")            # srb tc error now
+StargazersQuery.execute(first: params[:first])  # fine, and "10" becomes 10
+```
+
+`cast:` is what a loose value converts through, so a custom scalar needs nothing
+beyond the registration it already has. Bad input raises
+`GraphWeaver::InputError` naming the variable, the operation and the value.
+
+Two conversions got **stricter** at the same time, and either can bite an app
+that was passing. A numeric string is now read as a wire format rather than as
+Ruby source, so `"010"` is ten rather than eight and `"0x1f"` and `"1_0"` are
+refused. And a `Boolean` refuses a String outright — every rule for `"0"` and
+`"off"` is somebody's convention, so convert at the call site.
+
+### `nil` sends `null`
+
+A variable passed `nil` now sends an explicit `null`; one left out is still left
+out. That's what lets a mutation clear a field — and it changes what a kwarg fed
+a possibly-missing value means:
+
+```ruby
+UpdateProfile.execute!(bio: params[:bio])   # a missing param used to omit; now it clears the bio
+```
+
+**Grep for kwargs fed straight from `params` or an optional attribute**, and
+pass the keyword only when you mean it:
+
+```ruby
+UpdateProfile.execute!(**(params[:bio] ? { bio: params[:bio] } : {}))
+```
+
+Non-null variables are unaffected: they can't carry `null`, so `nil` there still
+omits and the schema default applies. Input objects get the distinction only
+where a Hash can express it — `coerce({nickname: nil})` sends null, `coerce({})`
+omits, and a struct built with `.new` can't tell the two apart, so `nil` there
+still means omit.
+
+### Renames
+
+| before | after |
+|---|---|
+| `Retry.new(tries: n)`, `retries: { tries: n }` | `retries: n - 1` — one word everywhere, counting the attempts *after* the first, so `retries: 0` is one attempt and `GraphWeaver.new(url, retries: 3)` is four |
+| `GraphWeaver.new(url, retries: { retries: 5, retry_codes: […] })` | `GraphWeaver.new(url, retries: 5, retry_codes: […])` — the other retry options sit beside the count; the Hash form read as a key nested in itself |
+| `Retry.new(t, on: […])` | `Retry.new(t, retry_on: […])` |
+| `Retry.new(t, base: 0.5, max: 30)` | `Retry.new(t, base_delay: 0.5, max_delay: 30)` — beside a count, `max: 30` read as a second, larger attempt count |
+| `Codegen.generate(module_name:)` | `name:` — the spelling `GraphWeaver.parse` already used; `module_name:` now raises, naming its replacement |
+| `Testing.config.null_chance = 0.3` | `graphql_fake(null_chance: 0.3)`, on the example that wants it |
+| `Testing.config.mode = :literal` | `graphql_fake(values: :literal)`, likewise |
+| `Testing::MODES` | `Testing::VALUE_STYLES` |
+| `SchemaLoader.stale?(path)` | `SchemaLoader.diff(path).empty?` — and `diff` also names what moved |
+
+The two `Testing.config` deletions are the ones worth a sentence. A suite-wide
+`null_chance` answers a per-example question, so it nils an unrelated field one
+run in ten, on a seed the failure doesn't name; move it onto the examples that
+are *about* an empty state. (`config.default_mode` and the `graphql: :fake` tag
+are untouched — the per-fake `mode:` became `values:` so the two can't be
+confused for each other.) Every retry misspelling raises rather than being
+ignored: the Hash form names its flat replacement, and a retry option passed
+without `retries:` says so.
+
+### The internals moved behind `Internal`
+
+The public surface is now what the docs name, what generated code calls, and the
+`execute` slot; everything else sits under `GraphWeaver::Internal` or went
+`private`, and a spec diffs the two so the next accidental promotion fails CI.
+Nothing documented moved — skip this section unless `srb tc` or a
+`NoMethodError` says otherwise.
+
+What a suite might plausibly have reached for: the federation query planner and
+its IR (`Internal::Planner`), the fake-value engine (`Internal::Values`), the
+selection walk (`Internal::Selection` — so `FakeClient` no longer answers
+`each_field` or `gather`), the cassette matching rules (`Internal::RequestKey`),
+subgraph detection (was `Testing::Subgraphs`), `GraphWeaver.log` /
+`.instrument` / `.filter_variables` (`Internal::Log` — `logger=`,
+`instrumenter=` and `filter_parameters=` are unchanged), and
+`Transport.operation_name` / `.mutation?` / `.log_tag`, which left the class you
+subclass for `Internal::Wire`.
+
+Two smaller edges. `SchemaDiff::Change`, `Cassette::Check`, `Coverage::Result`
+and `InputStruct::Field` are `Data` now rather than `Struct`, so they hand out
+no writers — read one, build a new one to change a field. And generated modules
+keep their own plumbing to themselves: `DEFAULT_CLIENT`, `FIELDS` and `ONE_OF`
+are emitted `private_constant`, so **regenerate**.
+
+### Behavior that changed under you
+
+- **A mutation is no longer retried.** A timeout doesn't say whether the server
+  applied it, and a second `charge` is worse than a failed one. Pass
+  `retry_mutations: true` for an API whose mutations are idempotent.
+- **A registration this schema can't match warns instead of failing
+  generation.** One registry serves a whole federated graph, so a name the
+  schema in hand doesn't declare may belong to the subgraph next door — see
+  [federation](federation.md#generating-for-a-federated-graph). Your typo is now
+  in the list `rake graph_weaver:generate` prints after the files, so read it.
+- **`verify_generated!` fails when it finds no query documents.** A mistyped
+  `queries_paths` used to leave a CI gate green forever.
+- **The local router refuses a `@fromContext` argument** rather than fetching
+  the field with it unset. Federation 2.8's `@context` machinery was on the
+  routing table's known list, so the argument was read and dropped. Per query,
+  like `@interfaceObject`: a subtree one subgraph answers whole still runs.
+- **A `#trace` assertion may see one entry fewer.** Two `@requires` field sets
+  crossing into the same subgraph on the same `@key` now ride one entity fetch,
+  the way Apollo's do.
+- **Fabricating a custom scalar registered as a class of your own needs a pin
+  for the type** — `Testing.config.overrides = { "Money" => "12.00" }`, or the
+  same key on one example's `graphql_fake`. Without one, `FakeClient` and
+  cassette anonymization refuse rather than feeding your cast a `"Money-1"`
+  placeholder. Scalars registered as `Time`, `Date`, `Integer`, `Float`,
+  `String` or `T::Boolean` need nothing.
+- **Re-run `rake graph_weaver:cassettes:anonymize`** on any committed cassette
+  holding a registered custom scalar: the anonymizer used to write a value the
+  generated codec couldn't read back.
+- **Generation refuses four more things**, each naming its fix — a
+  `register_scalar` whose Ruby type nothing can build out of JSON (`BigDecimal`,
+  classically: give it a `cast:`), a result key that would shadow a constant the
+  file uses, an enum value that camelizes to nothing, and a narrowed fragment
+  whose `__typename` sits behind `@skip`/`@include`.
+
+## Upgrading to 0.5.0
+
+0.5.0 is one large breaking release. Almost all of it is caught mechanically,
+in this order:
 
 ```sh
-rake graph_weaver:generate   # 1. regenerate; the emitted call shape changed
-srb tc                       # 2. every call site that moved is now a type error
-rake graph_weaver:verify     # 3. fails until the tree is regenerated
+# 1. rename the path settings first — generate won't load without them
+#    (queries_path -> queries_paths, generated_path -> generated_paths,
+#     fragments_path -> fragments_paths; see "Path settings are lists" below)
+
+bundle exec tapioca gem graph_weaver   # 2. regenerate the RBI
+rake graph_weaver:generate             # 3. the emitted call shape changed
+srb tc                                 # 4. every call site that moved is an error
+rake graph_weaver:verify               # 5. fails until the tree is regenerated
 ```
 
-Generated code is `# typed: strict`, so step 2 finds the call sites for you.
-The rest of this page is what a typechecker can't see.
+**Step 2 is not optional.** Against the 0.4.6 RBI, `srb tc` reports errors
+pointing into your `generated/` directory — `QueryModule`, `client_for`,
+`check_envelope!` — which read as though codegen emitted broken Ruby. It
+didn't; sorbet is checking new generated code against the old gem's types.
+Regenerate the RBI and what remains is only your own call sites.
+
+Generated code is `# typed: strict`, so step 4 finds those for you. The rest of
+this page is what a typechecker can't see.
 
-## `execute` means one thing now
+### `execute` means one thing now
 
 Every client answers the same call — `execute(query, variables:, operation_name:)`,
 returning the raw response hash. `Client` used to spell something else under
@@ -30,7 +211,9 @@ GraphWeaver.run(source, query, **vars)       # after
 ```
 
 **This one is worth grepping for.** `Client#execute` still exists, so a stale
-call fails at runtime rather than at typecheck: `rg '\.execute!?\(' --type ruby`
+call fails at runtime rather than at typecheck — as do `GraphWeaver.execute`
+and `GraphWeaver.reset_scalars!`, which are simply gone and will not be flagged
+until the RBI is regenerated (step 2): `rg '\.execute!?\(' --type ruby`
 and check each hit is passing `variables:` rather than loose kwargs.
 
 A generated module takes its per-call client as a **keyword**:
@@ -42,7 +225,7 @@ PersonQuery.execute(client: some_client, id: "1")  # after
 
 `GraphWeaver.resolve_transport` is gone; nothing needs unwrapping any more.
 
-## Path settings are lists
+### Path settings are lists
 
 `queries_paths`, `generated_paths`, `fragments_paths` — every entry is read.
 Assigning a String still works, so the change is the name:
@@ -54,9 +237,10 @@ GraphWeaver.queries_paths = "app/graphql/queries"   # after
 
 `schema_path` stays singular: one run reads one schema.
 
-## One reset
+### One reset
 
-`GraphWeaver.reset_registrations!` is the clean slate between tests. The four
+`GraphWeaver.reset_registrations!` is the clean slate between tests, or between
+generations for different schemas. The four
 narrow ones moved to where they live:
 
 ```ruby
@@ -65,23 +249,59 @@ GraphWeaver::Codegen.reset_scalars!   # after   (also reset_enums!, clear_scalar
                                       #          reset_type_helpers!)
 ```
 
-## Smaller renames
+### Generated names come from the response key, not the type
+
+Nested structs used to be named for the GraphQL *type* they were cast from;
+they are now named for the **response key that selects them**, camelized, and
+the constant path reads like the query. The typechecker finds the call sites in
+a `# typed: true` file (an unresolved constant is an `srb tc` error); in a
+`# typed: false` file it is `uninitialized constant` at runtime, so grep for
+`::Result::` there.
+
+| selection | before (type) | after (key) |
+|---|---|---|
+| `person { pets { name } }` | `PersonQuery::Result::Person::Pet` | `PersonQuery::Result::Person::Pets` |
+| `payrollRisk { score }` | `…::Result::RiskAssessment` | `…::Result::PayrollRisk` |
+| `_entities(…) { ... on Product { … } }` | `…::Result::Product` | `…::Result::Entities::Product` |
+
+The key is used verbatim — no pluralization, so a list field `pets` is `Pets`.
+To pick the name yourself, alias the field: `pet: pets { name }` generates
+`Pet`. Union and interface members keep their type-condition names, nested in
+the container the field names. The payoff is that adding, removing or
+reordering an unrelated selection can never rename a struct you reference.
+
+**Enums moved out of the result tree.** Every schema enum a query touches is one
+Ruby type in the shared module, `GraphQLTypes::Species`, so a value read from
+one query hands straight into another's variable. A query module aliases the
+enums its *variables* use (`AddPetMutation::Species` still works); an enum
+reached only through a result is no longer nested under the struct that
+carries it — `SearchQuery::Result::Search::Species` is `GraphQLTypes::Species`.
+
+### Smaller renames
 
 | before | after |
 |---|---|
-| `response.ok?` | `response.success?` |
 | `Testing.config.auto_fake = true` | `Testing.config.default_mode = :fake` |
-| `register_scalar(…, coerce: :to_s)` | `coerce: true`, or a `cast:`/`serialize:` pair |
 | a mutation's `…Query` module | `…Mutation` |
+| `graphql: :none` (rspec tag) | `graphql: false` |
+
+**The shared types module was three, and is now one.** `GraphQLInputs`,
+`GraphQLEnums` and `GraphQLUnions` are all `GraphQLTypes`, and the files move
+with them — `generated/inputs/` becomes `generated/types/`. The three settings
+that named them (`inputs_module=`, `enums_module=`, `unions_module=`) are one
+`types_module=`. Regenerating writes the new tree; delete the old directory,
+which pruning leaves behind empty.
 
-`Testing::LiveSchema` is gone. If your client points at a different API than the
-schema class your specs run in-process, name it once:
+If your specs run one schema class in-process while your client points at a
+different API, name it — per example, since a federated suite runs more than
+one:
 
 ```ruby
-GraphWeaver::Testing.config.schema = MySchema
+graphql_in_process(MySchema)                     # in the example
+GraphWeaver::Testing.config.schema = MySchema    # or once, for the whole suite
 ```
 
-## Registering from Rails
+### Registering from Rails
 
 A registration naming one of your own constants belongs in a `to_prepare` block
 — the same place the in-process client goes, and for the same reason:
@@ -95,9 +315,10 @@ end
 ```
 
 Generation depends on `:environment`, which runs `to_prepare` too, so the
-registration is in place before it emits.
+registration is in place before it emits — and at boot the generated files
+load from a `to_prepare` block of their own, after yours.
 
-## If you use the federation router
+### If you use the federation router
 
 Detection only sees *loaded* schema classes, and Rails does not eager load for
 rake or in the default test environment. Both are one line:

data/graph_weaver.gemspec

@@ -7,13 +7,27 @@ Gem::Specification.new do |s|
   s.description = "Your .graphql files, compiled into Sorbet types — and the fakes to test them."
   # ".yardopts" explicitly: `git ls-files *` skips dotfiles, and
   # rubydoc.info needs it shipped to render docstrings as markdown
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples'`.split("\n") + [".yardopts"]
+  # CLAUDE.md/PLAN.md/REVIEW.md/NOTES.md/DECISIONS.md are written for whoever
+  # works on the gem, not whoever installs it — and REVIEW.md carries examples
+  # from before the API it describes was rewritten
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples' \
+                     ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
+                     ':!:DECISIONS.md' ':!:Makefile' ':!:design'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
-  s.summary     = "GraphWeaver"
+  # rubygems.org shows summary as the headline, description below it
+  s.summary     = "A typed GraphQL client for Ruby"
   s.version     = GraphWeaver::VERSION
 
+  s.metadata = {
+    "bug_tracker_uri" => "#{s.homepage}/issues",
+    "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{s.homepage}/tree/main/docs",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => s.homepage,
+  }
+
   s.required_ruby_version = ">= 3.3"
 
   # 2.6.7 fills defaulted directive arguments when building from SDL

data/lib/generators/graph_weaver/install_generator.rb

@@ -31,17 +31,14 @@ module GraphWeaver
       argument :source, type: :string, banner: "SOURCE",
         desc: "what you'd pass to GraphWeaver.new: an endpoint url, a graphql-ruby schema class, or a schema dump path"
 
+      # the default is SchemaLoader's, not one restated here — an --auth the
+      # generator omits from the dump is one the schema tasks then can't find
       class_option :auth, type: :string,
-        desc: "name of the ENV var holding the auth token (url only) — default GRAPHWEAVER_AUTH"
+        desc: "name of the ENV var holding the auth token (url only) — " \
+          "default #{GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV}"
       class_option :schema, type: :boolean, default: true,
         desc: "write the schema dump codegen reads"
 
-      # a Ruby constant path names a schema class; anything that is neither
-      # this nor a url is taken as a path to a dump
-      CONSTANT = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
-
-      DEFAULT_AUTH = "GRAPHWEAVER_AUTH"
-
       # Before anything is written: a mistyped source or a flag that doesn't
       # apply to it is a mistake in the command just typed, so say so there
       # rather than at boot, three files later.
@@ -59,8 +56,11 @@ module GraphWeaver
         create_file "config/initializers/graph_weaver.rb", initializer
       end
 
+      # fragments too: the editor config below globs it, and a shared fragment
+      # then has an obvious home rather than being invented later
       def create_layout
         create_file File.join(GraphWeaver.queries_paths.first, ".keep"), ""
+        create_file File.join(GraphWeaver.fragments_paths.first, ".keep"), ""
         create_file File.join(GraphWeaver.generated_paths.first, ".keep"), ""
       end
 
@@ -88,10 +88,18 @@ module GraphWeaver
       rescue StandardError => e
         # the files above are the valuable part — don't lose them to a bad
         # token or an unreachable host
+        @schema_failed = true
         say_status :failed, "#{e.message} — retry with `#{refresh_command}`", :red
       end
 
       def next_steps
+        # generation reads the dump, so without one the step below can't run —
+        # say that next to it rather than leaving the red line above to be
+        # scrolled past. A re-run that already has a dump is not blocked.
+        if @schema_failed && !GraphWeaver::SchemaLoader.locate_path
+          say "\nThere's no schema dump yet, so `rake graph_weaver:generate` has nothing to read."
+        end
+
         say <<~TEXT
 
           Write a query in #{GraphWeaver.queries_paths.first}, then:
@@ -140,14 +148,16 @@ module GraphWeaver
           end
       end
 
-      # Which of GraphWeaver.new's source forms this is — the url test is
-      # its own, so the generator and the client can't disagree about what
-      # counts as one.
+      # Which of GraphWeaver.new's source forms this is. Neither test is its
+      # own — a url is whatever the client calls one, a constant path whatever
+      # codegen will spell — so the generator can't disagree with either about
+      # what it just wrote an initializer for. Anything that is neither is
+      # taken as a path to a dump.
       def form
         @form ||=
           if source.match?(GraphWeaver::Client::URL)
             :url
-          elsif source.match?(CONSTANT)
+          elsif source.match?(GraphWeaver::Codegen::CONSTANT_NAME)
             :schema_class
           else
             :path
@@ -174,10 +184,14 @@ module GraphWeaver
       # writes the conventional one.
       def schema_path = (form == :path) ? source : GraphWeaver.schema_path
 
-      def auth_var = options[:auth] || DEFAULT_AUTH
+      def auth_var = options[:auth] || GraphWeaver::SchemaLoader::DEFAULT_AUTH_ENV
 
+      # The command just typed, retyped. One rule for every source form, and
+      # the only one that always works: the files already written come back
+      # "identical", and --auth rides along — where schema:refresh has no flag
+      # for it, and with no dump written has no url to read either.
       def refresh_command
-        (form == :url) ? "rake graph_weaver:schema:refresh" : "rails g graph_weaver:install #{source}"
+        "rails g graph_weaver:install #{source}#{" --auth #{options[:auth]}" if options[:auth]}"
       end
 
       def initializer
@@ -243,15 +257,16 @@ module GraphWeaver
       end
 
       # fragments are in documents: too — without them an editor reports
-      # `Unknown fragment` on any query that spreads a shared one
+      # `Unknown fragment` on any query that spreads a shared one. The glob is
+      # codegen's, so the editor validates exactly the files codegen reads.
       def editor_config
         <<~YAML
           # Autocomplete and validation for .graphql files in VS Code / RubyMine.
           # https://github.com/dpep/graph_weaver/blob/main/docs/editors.md
           schema: #{schema_path}
           documents:
-            - #{GraphWeaver.queries_paths.first}/**/*.{graphql,gql}
-            - #{GraphWeaver.fragments_paths.first}/**/*.{graphql,gql}
+            - #{File.join(GraphWeaver.queries_paths.first, GraphWeaver::Codegen::DOCUMENT_GLOB)}
+            - #{File.join(GraphWeaver.fragments_paths.first, GraphWeaver::Codegen::DOCUMENT_GLOB)}
         YAML
       end
     end

data/lib/graph_weaver/client.rb

@@ -36,17 +36,32 @@ class GraphWeaver::Client
 
   URL = %r{\Ahttps?://}i
 
-  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil,
-    open_timeout: nil, read_timeout: nil, context: nil, &middleware)
+  # refused from two branches — a url source, and a schema source with
+  # nothing to hand a context to — so the two can't word it differently
+  CONTEXT_IN_PROCESS = "context: applies to a schema class executing in-process"
+
+  # the whole rule, said wherever a retry option is refused
+  RETRY_RULE = "retries: is how many attempts follow the first; the other retry options sit beside it"
+  private_constant :CONTEXT_IN_PROCESS, :RETRY_RULE
+
+  def initialize(source, auth: nil, headers: {}, transport: nil, cache: nil, ttl: nil,
+    open_timeout: nil, read_timeout: nil, context: nil,
+    retries: false, backoff: nil, base_delay: nil, max_delay: nil, jitter: nil, retry_on: nil,
+    retry_if: nil, retry_codes: nil, retry_mutations: nil, sleeper: nil, &middleware)
     check_source!(source)
 
+    # Retry's options, spelled the same and passed straight through; nil
+    # is "not given", so their defaults stay in Retry alone
+    retry_options = { backoff:, base_delay:, max_delay:, jitter:, retry_on:, retry_if:,
+                      retry_codes:, retry_mutations:, sleeper: }.compact
+
     if source.is_a?(String) && source.match?(URL)
-      raise ArgumentError, "context: applies to a schema class executing in-process" if context
+      raise ArgumentError, CONTEXT_IN_PROCESS if context
 
       built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, &middleware)
-      @transport = wrap_retries(built, retries)
+      @transport = wrap_retries(built, retries, retry_options)
     else
-      if auth || middleware || retries || open_timeout || read_timeout
+      if auth || middleware || retries || open_timeout || read_timeout || !retry_options.empty?
         raise ArgumentError, "auth:/retries:/timeouts/middleware apply to a url — got a schema source"
       end
       if transport.is_a?(Symbol)
@@ -65,7 +80,7 @@ class GraphWeaver::Client
       if context && !(source.is_a?(Module) && transport.nil?)
         # nothing would ever read it — a dump has no resolvers, and an
         # explicit transport carries its own
-        raise ArgumentError, "context: applies to a schema class executing in-process"
+        raise ArgumentError, CONTEXT_IN_PROCESS
       end
 
       # InProcess adds context:, logging and branded errors to the bare
@@ -76,6 +91,7 @@ class GraphWeaver::Client
 
     @cache = cache
     @ttl = ttl
+    @schema_lock = Mutex.new
   end
 
   # The transport queries run through: a url-built transport, an
@@ -85,15 +101,21 @@ class GraphWeaver::Client
   attr_reader :transport
 
   # transport, when this client must be able to execute
-  def transport!
+  private def transport!
     transport or raise GraphWeaver::Error,
       "this client has no transport (built from a schema dump) — pass a url or transport:"
   end
 
   # The schema, introspecting through the transport on first use (cached
   # per the client's cache:/ttl:) unless one was given up front.
+  #
+  # Locked because a cold Puma process serves its first requests
+  # concurrently: a bare ||= there is one full introspection round trip per
+  # in-flight thread, each of them also writing the cache file.
   def schema
-    @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+    @schema_lock.synchronize do
+      @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+    end
   end
 
   # The client contract, same as every transport: a query and its
@@ -146,6 +168,11 @@ class GraphWeaver::Client
   def build_transport(url, auth:, headers:, kind:, open_timeout: nil, read_timeout: nil, &middleware)
     headers = headers.dup
     if auth
+      unless auth.is_a?(String)
+        raise ArgumentError, "auth: takes a token string, got #{auth.class} — other headers go in " \
+          "headers:, and a token that rotates goes in the Faraday middleware block"
+      end
+
       headers["Authorization"] ||= auth.include?(" ") ? auth : "Bearer #{auth}"
     end
 
@@ -159,7 +186,7 @@ class GraphWeaver::Client
         GraphWeaver::Transport::HTTP.new(url, headers:, **timeouts)
       end
 
-    GraphWeaver.log(:info) { "transport: #{transport.class} -> #{url}" }
+    GraphWeaver::Internal::Log.log(:info) { "transport: #{transport.class} -> #{url}" }
     transport
   end
 
@@ -194,13 +221,23 @@ class GraphWeaver::Client
     GraphWeaver::Transport::Faraday.new(url, headers:, **timeouts, &middleware)
   end
 
-  # retries: is off by default — true for Retry defaults, or a
-  # Hash of its options
-  def wrap_retries(transport, retries)
+  # retries: is off by default — a count, or true for Retry's default
+  # count. Without it nothing wraps the transport, so a retry option on
+  # its own would quietly do nothing.
+  def wrap_retries(transport, retries, options)
     case retries
-    when true then GraphWeaver::Retry.new(transport)
-    when false, nil then transport
-    else GraphWeaver::Retry.new(transport, **retries)
+    when Integer then GraphWeaver::Retry.new(transport, retries:, **options)
+    when true then GraphWeaver::Retry.new(transport, **options)
+    when false, nil
+      raise ArgumentError, "#{options.keys.first}: needs retries: — #{RETRY_RULE}" if options.any?
+
+      transport
+    when Hash
+      # it used to take a Hash of Retry options, which read as a key nested in itself
+      flat = retries.map { |key, value| "#{key}: #{value.inspect}" }.join(", ")
+      raise ArgumentError, "retries: no longer takes a Hash — pass GraphWeaver.new(url, #{flat})"
+    else
+      raise ArgumentError, "#{RETRY_RULE} — got #{retries.inspect}"
     end
   end
 end

data/lib/graph_weaver/codegen/aliases.rb

@@ -51,14 +51,19 @@ class GraphWeaver::Codegen
     # since a module and the type it queries can share a name (module Query
     # on type Query would otherwise stutter).
     def qualify(node, message)
-      return message if @module_name.nil? || @module_name == node.graphql_type
+      return message if @name.nil? || @name == node.graphql_type
 
-      "#{@module_name}: #{message}"
+      "#{@name}: #{message}"
     end
 
+    # An alias emits a plain instance method, so it is held to the same bar
+    # as a wire field's prop: a name the struct already answers to would be
+    # silently overridden, and `hash` or `inspect` breaks the object rather
+    # than the file.
     def check_alias_name!(node, name)
       taken = node.fields.any? { |f| f.prop == name } ||
-        ALIAS_RESERVED.include?(name) || RUBY_KEYWORDS.include?(name)
+        STRUCT_METHODS.include?(name) || ALIAS_RESERVED.include?(name) ||
+        RUBY_KEYWORDS.include?(name)
       return unless taken
 
       raise GraphWeaver::Error,
@@ -70,9 +75,10 @@ class GraphWeaver::Codegen
       GraphWeaver::Codegen.type_registry[graphql_name]&.dig(:aliases) || {}
     end
 
-    # methods every generated struct already answers to; Ruby keywords are
-    # checked alongside (RUBY_KEYWORDS is defined by the class this mixes into)
-    ALIAS_RESERVED = %w[from_h serialize to_h].to_set.freeze
+    # The CLASS methods a generated struct defines; STRUCT_METHODS covers the
+    # instance side, and both are checked with RUBY_KEYWORDS alongside (all
+    # three are defined by the class this mixes into).
+    ALIAS_RESERVED = %w[from_h].to_set.freeze
     # list selectors — pick one element out of a list-typed hop, always nilable
     # (the list may be empty). Everything else is a field prop.
     LIST_SELECTORS = %w[first last].freeze
@@ -80,6 +86,7 @@ class GraphWeaver::Codegen
     # ever satisfy it, so it's a typo (or a wire-cased name), not a path that
     # doesn't fit this query. optional: skips the latter, never this.
     UnknownSegment = Class.new(GraphWeaver::Error)
+    private_constant :ALIAS_RESERVED, :LIST_SELECTORS, :UnknownSegment
 
     # Walk a dotted path through this struct's selected shape, building the
     # delegator expression (`meta&.tag`, `_entities.first&.name`) and its return
@@ -131,7 +138,7 @@ class GraphWeaver::Codegen
           unless field
             check_segment_exists!(node, name, obj, seg)
             props = obj.fields.map(&:prop)
-            suggestion = GraphWeaver.did_you_mean(props, seg)
+            suggestion = GraphWeaver::Internal::Util.did_you_mean(props, seg)
             hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
             raise GraphWeaver::Error,
               "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
@@ -163,7 +170,7 @@ class GraphWeaver::Codegen
       hint = if prop != seg && known.include?(prop)
         # paths are the Ruby prop chain, not the GraphQL one — the classic miss
         " — GraphQL fields generate snake_case props; use '#{prop}'"
-      elsif (suggestion = GraphWeaver.did_you_mean(known, prop))
+      elsif (suggestion = GraphWeaver::Internal::Util.did_you_mean(known, prop))
         " — did you mean '#{suggestion}'?"
       else
         " (has: #{known.sort.join(", ")})"