graph_weaver 0.7.4 → 0.7.6

data/docs/upgrading.md

@@ -1,7 +1,8 @@
 # Upgrading
 
 [Regenerate](#regenerate-on-every-upgrade) whichever version you're on, then read
-the one section that is yours: from [0.7.3](#upgrading-from-073), from
+the one section that is yours: from [0.7.5](#upgrading-from-075), from
+[0.7.4](#upgrading-from-074), from [0.7.3](#upgrading-from-073), from
 [0.7.1](#upgrading-from-071), from [0.7.0](#upgrading-from-070) or from
 [0.6.1](#upgrading-from-061). Coming from 0.6.0 or older, the path is that
 version's own upgrade notes — read them at the tag they shipped under
@@ -23,6 +24,47 @@ That's the reminder working, not a false alarm. Generation is deterministic, so
 the diff is exactly what the new version emits differently and nothing else —
 worth reading rather than rubber-stamping.
 
+## Upgrading from 0.7.5
+
+A patch release. The regenerate is what changes behaviour — every module gains
+the per-call event — and the rest reaches an app only where it already relied
+on the old wording. Read the left column and skip what isn't yours; the
+[changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| subscribe to `execute.graph_weaver`, or read `GraphWeaver::LogSubscriber`'s line | a second event, [`operation.graph_weaver`](logging.md#instrumentation), covers one `execute` start to typed result — retries, backoff and the cast — and the request events nest inside it. **The info log line is the operation's now**: `failed GraphWeaver::CastError` where it read `ok`, present under a `graphql:` tag, one line per retried call; the per-attempt line writes at debug. A module generated by 0.7.5 emits neither until regenerated |
+| spread a shared fragment on an interface or union that selects no `... on`, or exactly one — `grep -rn 'fragment .* on' app/graphql/fragments` | it [hoists](generated_modules.md#abstract-types) into `GraphQLTypes::<Fragment>` like every other shared fragment; app code naming `YourQuery::Result::Field` moves, and `srb tc` finds each site |
+| run `rake graph_weaver:queries:check` in CI for a graph that names its own `schema` — `rake graph_weaver:graphs` lists them | it re-introspects that graph's server (the dump's url, or the client's url or schema class) where it used to check the committed file, so CI needs the same reach a single-schema app already had. The verdict names what it checked against either way |
+| keep a composed supergraph on a graph that also names a `client` | `schema:refresh` steps over it with the recompose line where 0.7.5 could have overwritten it with the API schema |
+| parse `rake graph_weaver:unused` output, or run it `STRICT=1` | a `before_action`-loaded `@result` is credited again, and the coordinate printed comes from the query, not from any word in the file |
+
+Then regenerate, and the gate:
+
+```sh
+rake graph_weaver:generate
+rake graph_weaver:verify
+```
+
+## Upgrading from 0.7.4
+
+Read the left column and skip what isn't yours; the
+[changelog](../CHANGELOG.md) says why each one moved.
+
+| applies if you… | what changed |
+|---|---|
+| spread a shared fragment as a whole field — `grep -rln '{ *\.\.\.[A-Za-z]* *}' app/graphql/queries` | on an object type it now [hoists](generated_modules.md#a-shared-fragment-is-one-type) into `GraphQLTypes` under the fragment's name, as it already did on a union. **App code naming the struct it used to produce (`PetQuery::Result::Pet`) moves to `GraphQLTypes::PetFields`** — one type instead of one per query, so a `T.type_alias { T.any(…) }` written to paper over that goes away. Regenerating and running `srb tc` finds every site |
+| register an `abstract!` mixin — `grep -rn 'extend_type' app config lib`, then check which of those modules call `abstract!` | **generation refuses** where a query doesn't select everything the mixin declares, instead of leaving it for your `srb tc`. The message names the struct, the members and the fixes: select them in that query, or select the type through one shared fragment so a single hoisted struct answers for every query |
+| keep a hand-maintained schema dump on a graph that also names a `client` — `rake graph_weaver:graphs` lists both per graph | `rake graph_weaver:schema:refresh` **rewrites that dump from the client** where it used to refuse and exit 1. If the file is the source of truth, don't run `refresh` for that graph, or drop the client from it |
+| call `Codegen#used_union_names` | it is `used_fragment_names` — the set it reports now includes hoisted object fragments |
+
+Then regenerate, and the gate:
+
+```sh
+rake graph_weaver:generate
+rake graph_weaver:verify
+```
+
 ## Upgrading from 0.7.3
 
 A patch release. One change can reach an app that never touched it — how a
@@ -207,7 +249,7 @@ only one here that shows up in production rather than in your code.
   Nothing raises: a subscriber comparing it to an Integer just stops matching. **A
   subscriber that branched on a 4xx/5xx reads `:http_status` now**, which is nil
   in-process. The whole payload is a documented contract —
-  [logging](logging.md#the-payload).
+  [logging](logging.md#the-request-payload).
 - **`respond_to?` on a result struct no longer answers true for a name that doesn't
   exist.** It used to say true for any near miss, which broke the standard
   duck-typing guard. **A branch that read the old answer now takes the other path**,

data/examples/README.md

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

data/examples/github/generate.rb

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

data/examples/github/generated/star_mutation.rb

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

data/examples/github/generated/stargazers_query.rb

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

data/examples/github/generated/starred_query.rb

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

data/examples/github/run.rb

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

data/examples/github/setup.rb

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

data/graph_weaver.gemspec

@@ -5,8 +5,6 @@ Gem::Specification.new do |s|
   # the README tagline, verbatim — the two pitches drifted apart once already,
   # so spec/gemspec_spec.rb pins them together
   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
   # 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
@@ -14,10 +12,21 @@ Gem::Specification.new do |s|
   # someone who only has the installed gem, not a checkout
   # CHANGELOG.md doesn't (259 KB, ~16% of the package) — changelog_uri below
   # points at the GitHub copy instead
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' \
-                     ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
-                     ':!:DECISIONS.md' ':!:CHANGELOG.md' ':!:Makefile' ':!:design' \
-                     ':!:research'`.split("\n") + [".yardopts"]
+  unpackaged = %w[spec sorbet bin design research CLAUDE.md PLAN.md REVIEW.md
+    NOTES.md DECISIONS.md CHANGELOG.md Makefile]
+  # git knows what is tracked; a checkout that isn't a repo — an unpacked gem,
+  # a vendored copy, a shallow CI export — has no such answer, and git's
+  # "fatal:" on stderr lands in the output of every subprocess a spec captures.
+  # So ask quietly, and walk the tree rather than ship nothing.
+  files = `git ls-files * #{unpackaged.map { |path| "':!:#{path}'" }.join(" ")} 2>/dev/null`.split("\n")
+  if files.empty?
+    files = Dir.glob("**/*", base: __dir__).reject do |path|
+      unpackaged.include?(path.split("/").first) || File.directory?(File.join(__dir__, path))
+    end
+  end
+  # ".yardopts" explicitly: neither list carries a dotfile, and rubydoc.info
+  # needs it shipped to render docstrings as markdown
+  s.files       = files + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"

data/lib/generators/graph_weaver/install_generator.rb

@@ -119,6 +119,27 @@ module GraphWeaver
         end
       end
 
+      # The same thing the header and the Exclude above say, told to GitHub:
+      # linguist-generated collapses these files in a diff ("Load diff") and
+      # drops them from the language breakdown. Display only — they stay
+      # versioned, expandable, and `git diff` here is untouched.
+      #
+      # Written even when there is no .gitattributes, unlike .rubocop.yml: a
+      # .gitattributes turns no tooling on, so there is no app this surprises.
+      def mark_generated_for_github
+        body = File.read(gitattributes) if File.exist?(gitattributes)
+        globs = linguist_globs.reject { |glob| marked?(body, glob) }
+        return if globs.empty?
+
+        lines = globs.map { |glob| "#{glob} linguist-generated" }.join("\n")
+        marks = <<~TEXT + lines + "\n"
+          # Machine-written by `rake graph_weaver:generate` — GitHub collapses it in
+          # diffs and leaves it out of the language breakdown.
+        TEXT
+
+        body ? append_to_file(GITATTRIBUTES, "\n#{marks}") : create_file(GITATTRIBUTES, marks)
+      end
+
       # The `graphql:` tags need this require, and it has to be somewhere
       # rspec actually loads. A spec/support file is not: rspec-rails ships
       # the spec/support glob commented out, so the require sat there doing
@@ -191,6 +212,7 @@ module GraphWeaver
       private
 
       RUBOCOP_CONFIG = ".rubocop.yml"
+      GITATTRIBUTES = ".gitattributes"
 
       # rails_helper first: rspec-rails writes both, and only rails_helper
       # has Rails booted by the time the require runs.
@@ -203,6 +225,8 @@ module GraphWeaver
 
       def rubocop_config = File.join(GraphWeaver.root, RUBOCOP_CONFIG)
 
+      def gitattributes = File.join(GraphWeaver.root, GITATTRIBUTES)
+
       # Parsed, not counted: a `---` can also be a line inside a block scalar.
       # A file rubocop itself can't read is left to rubocop to complain about.
       def yaml_documents(body)
@@ -213,8 +237,31 @@ module GraphWeaver
 
       # Every graph's output directory, so a multi-schema app is covered by
       # the same run — read off the graphs rather than restated here.
-      def generated_globs
-        GraphWeaver.graphs.map { |graph| File.join(graph.output, "**/*") }.uniq
+      def generated_outputs = GraphWeaver.graphs.map(&:output).uniq
+
+      def generated_globs = generated_outputs.map { |dir| File.join(dir, "**/*") }
+
+      # gitattributes patterns are gitignore-style, where `dir/**` is
+      # everything beneath dir — spelled as git reads it, not as rubocop does.
+      def linguist_globs = generated_outputs.map { |dir| File.join(dir, "**") }
+
+      # git's own spellings of the one attribute: set, unset (`-`), unspecified
+      # (`!`), or valued.
+      LINGUIST = /\A[-!]?linguist-generated(?:=|\z)/
+
+      # Already marked — a re-run, or done by hand. A .gitattributes line is
+      # `<pattern> <attribute>…`, with `#` opening a comment, and the same
+      # directory is `dir/**`, `dir/*`, `dir/` or `dir`. Searching the body as
+      # one string instead let a comment that mentions the path suppress the
+      # mark, and saw only the spelling this generator writes.
+      def marked?(body, glob)
+        dir = glob.delete_suffix("/**")
+        body.to_s.lines.any? do |line|
+          pattern, *attributes = line.split
+          next false if pattern.nil? || pattern.start_with?("#")
+
+          pattern.chomp("**").chomp("*").chomp("/") == dir && attributes.any? { |a| LINGUIST.match?(a) }
+        end
       end
 
       # This install run is the one moment the user is guaranteed to be

data/lib/graph_weaver/client.rb

@@ -190,29 +190,6 @@ class GraphWeaver::Client
     run(query, **variables).data!
   end
 
-  # Does this query validate? The string form of GraphWeaver.check_queries,
-  # answering with the same JSON-ready hashes — `message`, `line`, `column`,
-  # plus `subgraphs` where a supergraph brands them — so an empty array means
-  # it validates:
-  #
-  #      client.check_query("query { viewer { login } }")   # => []
-  #      client.check_query("query { viewer { lgoin } }")
-  #      # => [{ "message" => "Field 'lgoin' doesn't exist on type 'User'",
-  #      #      "line" => 1, "column" => 17 }]
-  #
-  # Checked against this client's own schema — what `execute` would run
-  # against — so a url client introspects on first use as it always does, and
-  # nothing re-introspects the way check_queries defaults to. An unparseable
-  # source is an entry like any other; nothing here raises for a bad query.
-  # Shared fragments are inlined from fragments: the same way every other door
-  # inlines them.
-  def check_query(source, fragments: GraphWeaver.fragments_paths)
-    GraphWeaver::Internal::QueryCheck.errors(
-      schema, source, GraphWeaver::Codegen.load_fragments(fragments),
-      GraphWeaver::Internal::QueryCheck.routing_table_for(schema_source),
-    )
-  end
-
   private
 
   # Anything already speaking the client contract — another Client,

data/lib/graph_weaver/codegen/aliases.rb

@@ -34,6 +34,13 @@ class GraphWeaver::Codegen
         rescue UnknownSegment => e
           # names nothing in the schema, so no selection would fit — offering
           # optional: as the way out would just hide the typo
+          raise e.class, qualify(node, e.message)
+        rescue HoistedSegment => e
+          # optional: still skips it, but the message doesn't offer it: the two
+          # fixes it names are the only ones that end with an accessor, and no
+          # change to the fragment would make the path fit
+          next nil if spec[:optional]
+
           raise e.class, qualify(node, e.message)
         rescue GraphWeaver::Error => e
           # a path that doesn't fit THIS query's selection: optional simply
@@ -86,7 +93,10 @@ 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
+
+    # A segment inside a struct another module owns — see refuse_hoisted!.
+    HoistedSegment = Class.new(GraphWeaver::Error)
+    private_constant :ALIAS_RESERVED, :LIST_SELECTORS, :UnknownSegment, :HoistedSegment
 
     # Walk a dotted path through this struct's selected shape, building the
     # delegator expression (`meta&.tag`, `_entities.first&.name`) and its return
@@ -119,6 +129,7 @@ class GraphWeaver::Codegen
           nilable = true
         else
           obj = object_of(cur)
+          refuse_hoisted!(node, name, hoisted_of(cur), seg)
           unless obj
             hint = if list_of(cur)
               " — use .first or .last to pick an element"
@@ -155,6 +166,21 @@ class GraphWeaver::Codegen
       ObjectNode::Alias.new(name, expr, type)
     end
 
+    # A hop landing on a hoisted shared fragment: the struct is another
+    # module's, so the path stops here. Which query hoists is a property of how
+    # that query spreads the fragment, so optional: still skips it — but
+    # selecting differently inside the fragment never makes the path fit, so
+    # the message names only the two fixes that do.
+    def refuse_hoisted!(node, name, ref, seg)
+      return unless ref
+
+      raise HoistedSegment,
+        "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is inside the shared fragment " \
+        "#{ref.class_name}, which hoists to #{@types_namespace}::#{ref.class_name} — a path can't " \
+        "read into it. Register the alias on #{ref.graphql_type}, or select a field beside the " \
+        "spread to keep the struct local"
+    end
+
     # Separate "this query didn't select it" from "no query could": a segment
     # the schema doesn't declare on the type is a mistake in the registration,
     # so it raises even for an optional alias — which otherwise turns a typo
@@ -185,7 +211,7 @@ class GraphWeaver::Codegen
     # The leaf's Sorbet type as referenced from the aliased struct. Generated
     # nested constants (structs, enums, unions) must carry the container path,
     # since the delegator's `sig` is emitted in an outer struct where a bare
-    # `Sub` wouldn't resolve; scalars, mapped enums, and hoisted union refs are
+    # `Sub` wouldn't resolve; scalars, mapped enums, and hoisted refs are
     # already top-level. `containers` is the class-name chain to the leaf.
     def qualified_alias_type(node, containers)
       node = node.of if node.is_a?(NonNull)
@@ -203,10 +229,17 @@ class GraphWeaver::Codegen
       # there from the shared enums module — either way, no container prefix
       when EnumNode then node.class_name
       when UnionNode then "#{prefix}#{node.bare_type}"
-      else node.bare_type # Scalar, MappedEnum, UnionRefNode — already top-level
+      else node.bare_type # Scalar, MappedEnum, a hoisted ref — already top-level
       end
     end
 
+    # the hoisted-fragment reference a node resolves to (through NON_NULL), or nil
+    def hoisted_of(node)
+      node = T.let(node, T.untyped)
+      node = node.of while node.is_a?(NonNull)
+      node if node.is_a?(HoistedRefNode)
+    end
+
     # the List a node wraps (through NON_NULL), or nil
     def list_of(node)
       node = T.let(node, T.untyped)

data/lib/graph_weaver/codegen/emit.rb

@@ -130,8 +130,8 @@ class GraphWeaver::Codegen
     # The shared types artifact as files: one file per type under types/, plus
     # types.rb — the manifest that requires them in the order the runtime needs
     # (see below). One rule for all three kinds, so a schema migration diffs
-    # exactly the types it touched whether they're inputs, enums or unions.
-    def emit_types_files(unions)
+    # exactly the types it touched whether they're inputs, enums or fragments.
+    def emit_types_files(fragments)
       files = {}
       # a mapped enum's constants are its wire tables, but the file is still
       # named for the GraphQL enum — one type, one file, whichever it is
@@ -142,15 +142,15 @@ class GraphWeaver::Codegen
       }
       inputs, = ordered_inputs
       structs = inputs.map { |input| type_file(files, input.class_name) { |out| emit_input(input, out, 1) } }
-      hoisted = unions.map { |union| type_file(files, union.class_name) { |out| emit_union(union, out, 1) } }
+      hoisted = fragments.map { |node| type_file(files, node.class_name) { |out| emit_nested(node, out, 1) } }
 
       out = []
       out << "# typed: strict"
       out << "# frozen_string_literal: true"
       out << ""
       out << "# Generated by GraphWeaver #{GraphWeaver::VERSION} — do not edit. Shared types for this schema —"
-      out << "# input types, enums, and unions hoisted from shared fragments — one file"
-      out << "# per type; query modules alias what they use."
+      out << "# input types, enums, and the types hoisted out of shared fragments — one"
+      out << "# file per type; query modules alias what they use."
       out << ""
       requires = @requires.uniq.sort
       if requires.any?
@@ -175,7 +175,7 @@ class GraphWeaver::Codegen
       # both spell them bare, and a T::Enum can't be forward-declared the way
       # an input struct can
       if enums.any? && (structs.any? || hoisted.any?)
-        out << "# enums first — input structs and union members spell them bare"
+        out << "# enums first — input structs and hoisted fragments spell them bare"
       end
       (enums.sort + structs.sort + hoisted.sort).each do |file|
         out << "require_relative #{file.delete_suffix(".rb").inspect}"
@@ -210,11 +210,11 @@ class GraphWeaver::Codegen
     # assembled from the generator's walked state.
     def emit_module(root, variables, representations = [], operation_name = nil)
       # Every shared type this module names: its variable root inputs, the
-      # enums it reached, and the unions it hoisted (aliased so <Name>::Type
-      # and <Name>.from_h resolve to the shared module).
+      # enums it reached, and the fragments it hoisted (aliased so <Name> and
+      # <Name>.from_h resolve to the shared module).
       aliases = if @types_namespace
         (shared_input_names(variables) + shared_enum_names +
-          @used_unions.map { |name| camelize(name) }).uniq.sort
+          @used_fragments.map { |name| camelize(name) }).uniq.sort
       else
         []
       end
@@ -338,6 +338,10 @@ class GraphWeaver::Codegen
       node.values.each do |value|
         out << "#{pad}    #{camelize(value.downcase)} = new(#{value.inspect})"
       end
+      if node.fallback?
+        out << "#{pad}    # every other wire value casts here (register_enum fallback: true)"
+        out << "#{pad}    #{node.fallback} = new(#{GraphWeaver::Internal::ENUM_FALLBACK_WIRE.inspect})"
+      end
       out << "#{pad}  end"
       out << "#{pad}end"
       return unless node.aliased?
@@ -517,10 +521,11 @@ class GraphWeaver::Codegen
           flag ? "#{var.kwarg}: (#{flag} = true; nil)" : "#{var.kwarg}: nil"
         } + ["client: nil"]
 
-      # QueryModule#dispatch reads QUERY/OPERATION_NAME/GRAPH off the module,
-      # so the gem gets to bracket every request without a line of it landing
-      # in every generated file
-      call = "dispatch(variables, client:)"
+      # QueryModule#dispatch reads QUERY/OPERATION_NAME/GRAPH off the module
+      # and closes the operation event over the cast the block does, so the
+      # gem brackets the whole call — request and cast — without a line of it
+      # landing in every generated file
+      call = "dispatch(variables, client:) { |raw| from_response(raw) }"
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # the typed result, or a raised QueryError.
@@ -530,7 +535,7 @@ class GraphWeaver::Codegen
       out << "  def self.execute(#{kwargs.join(", ")})"
       emit_variables(out, required, optional, omitted)
       out << ""
-      out << "    from_response(#{call})"
+      out << "    #{call}"
       out << "  end"
       out << ""
       out << "  sig { params(#{sig_params.join(", ")}).returns(Result).checked(:never) }"
@@ -543,7 +548,7 @@ class GraphWeaver::Codegen
         # left out is exactly what a Ruby call can't forward
         emit_variables(out, required, optional, omitted)
         out << ""
-        out << "    from_response(#{call}).data!"
+        out << "    #{call}.data!"
       end
       out << "  end"
       out << ""

data/lib/graph_weaver/codegen/enum_type.rb

@@ -22,6 +22,10 @@ class GraphWeaver::Codegen
   # value — both spellings cast, the target is what serializes. It is the
   # whole registration when there is no T::Enum to map onto, and then the
   # generated enum gets one constant for the target and none for the alias.
+  #
+  # fallback: true is the same type-less form asking for leniency instead:
+  # the generated enum gains an Other member and absorbs undeclared wire
+  # values into it (see Codegen#enum_values).
   class EnumType
     attr_reader :graphql_name, :type, :fallback, :requires
 
@@ -55,6 +59,10 @@ class GraphWeaver::Codegen
       end
     end
 
+    # register_enum("Species", fallback: true): the generated enum gains an
+    # Other member and casts every undeclared wire value to it.
+    def generated_fallback? = type.nil? && fallback == true
+
     # The wire tables for a mapped enum: [wire value => member, member => the
     # wire value that goes out]. Every spelling casts; an alias's target is the
     # one that serializes.
@@ -75,7 +83,31 @@ class GraphWeaver::Codegen
           "add them, pin with map:, or absorb with fallback:"
       end
 
-      [from_wire, to_wire(from_wire, aliases)]
+      wire = to_wire(from_wire, aliases)
+      warn_unsendable(wire)
+      [from_wire, wire]
+    end
+
+    # The other direction, which nothing said: a member no wire value maps back
+    # from. A warning, not a refusal — one app-wide T::Enum serving two APIs
+    # that each expose a subset is a real shape, and the call that carries such
+    # a member is refused by name at runtime (InputStruct.enum_wire), so no
+    # wrong answer gets through either way. Warned on the channel
+    # validate_registrations! already narrates a mismatched registration on.
+    # fallback: is exempt: standing for what the schema doesn't declare is
+    # exactly what it is for.
+    def warn_unsendable(wire)
+      unsendable = type.values - wire.keys - [fallback].compact
+      return if unsendable.empty?
+
+      # a T::Enum member inspects as #<Type::Name>
+      names = unsendable.map { |member| member.inspect[2..-2] }.join(", ")
+      them = unsendable.one? ? "it" : "them"
+      GraphWeaver::Internal::Log.log(:warn) do
+        "#{graphql_name} has no value for #{type} member(s) #{names} — a kwarg carrying " \
+          "#{them} is refused at the call; map onto a matching T::Enum, or name the drift " \
+          "member with fallback:"
+      end
     end
 
     # alias spelling => the value it is read as, checked against what the
@@ -115,19 +147,27 @@ class GraphWeaver::Codegen
 
     private
 
-    # Without a T::Enum there is nothing for map:/fallback:/requires: to
-    # describe, so alias: is the whole registration.
+    # Without a T::Enum there is nothing for map:/requires: to describe, so
+    # alias: and fallback: true are the whole registration.
     def alias_only!(map, fallback, requires)
-      if @aliases.empty?
+      if fallback && fallback != true
+        raise ArgumentError, "register_enum(#{graphql_name.inspect}, fallback: #{fallback.inspect}): the " \
+          "generated enum generates its fallback member too, so say fallback: true. To fall back onto a " \
+          "member of your own, pass the T::Enum: " \
+          "register_enum(#{graphql_name.inspect}, YourEnum, fallback: YourEnum::Unknown)"
+      end
+
+      if @aliases.empty? && !fallback
         raise ArgumentError, "register_enum(#{graphql_name.inspect}) says nothing about #{graphql_name} — " \
-          "pass the T::Enum to map it onto, or alias: { \"old\" => \"NEW\" } to read two wire values as one"
+          "pass the T::Enum to map it onto, alias: { \"old\" => \"NEW\" } to read two wire values as one, " \
+          "or fallback: true to absorb values the server adds"
       end
 
-      extra = { map:, fallback:, requires: }.compact.keys.first
+      extra = { map:, requires: }.compact.keys.first
       if extra
         raise ArgumentError,
-          "register_enum(#{graphql_name.inspect}, alias: {...}) takes no #{extra}: — that describes a T::Enum " \
-          "of your own, so pass one: register_enum(#{graphql_name.inspect}, YourEnum, alias: {...})"
+          "register_enum(#{graphql_name.inspect}) takes no #{extra}: — that describes a T::Enum of your own, " \
+          "so pass one: register_enum(#{graphql_name.inspect}, YourEnum, #{extra}: {...})"
       end
 
       @requires = []
@@ -169,7 +209,7 @@ class GraphWeaver::Codegen
         groups = ambiguous.values.map { |pairs| pairs.map(&:first) }
         more = ambiguous.size - 1
         raise GraphWeaver::Error,
-          "enum #{graphql_name}: #{groups.first.join(" and ")} both map onto the #{type} member " \
+          "enum #{graphql_name}: #{groups.first.join(" and ")} all map onto the #{type} member " \
           "#{member.serialize.to_s.inspect}#{" (and #{more} more)" unless more.zero?} — say which spelling " \
           "goes on the wire:\n  #{EnumType.alias_suggestion(graphql_name, groups, type)}"
       end
@@ -189,8 +229,9 @@ class GraphWeaver::Codegen
 
   # The enum half of one graph's registrations — see Codegen::Registry.
   class Registry
-    # Map a GraphQL enum onto an app-owned T::Enum, or fold two of its wire
-    # spellings into one value (see EnumType). The one implementation —
+    # Map a GraphQL enum onto an app-owned T::Enum, fold two of its wire
+    # spellings into one value, or absorb the ones the server hasn't told you
+    # about yet (see EnumType). The one implementation —
     # GraphWeaver.register_enum is a delegate, so the same call reaches it
     # whichever door you came in by.
     #