graph_weaver 0.7.5 → 0.7.7

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

@@ -128,8 +128,7 @@ module GraphWeaver
       # .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)
-        # already marked — a re-run, or done by hand
-        globs = linguist_globs.reject { |glob| body&.include?(glob) }
+        globs = linguist_globs.reject { |glob| marked?(body, glob) }
         return if globs.empty?
 
         lines = globs.map { |glob| "#{glob} linguist-generated" }.join("\n")
@@ -246,6 +245,25 @@ module GraphWeaver
       # 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
       # reading, and a composed supergraph changes what the next steps are:
       # the test client is the interesting one, and there's a CI gate to add.

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
@@ -158,11 +168,13 @@ class GraphWeaver::Codegen
 
     # 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.
+    # 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 GraphWeaver::Error,
+      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 " \

data/lib/graph_weaver/codegen/emit.rb

@@ -521,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.
@@ -534,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) }"
@@ -547,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

@@ -83,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
@@ -185,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

data/lib/graph_weaver/codegen/nodes.rb

@@ -293,7 +293,9 @@ class GraphWeaver::Codegen
     # #as_json. Without a fallback the table is total and a miss is a real
     # mistake, so it still raises.
     def serialize(expr, _depth)
-      return "#{const_prefix}_TO_WIRE.fetch(#{expr})" unless @fallback
+      unless @fallback
+        return "GraphWeaver::InputStruct.enum_wire(#{@graphql_name.inspect}, #{const_prefix}_TO_WIRE, #{expr})"
+      end
 
       "#{const_prefix}_TO_WIRE.fetch(#{expr}) { |member| member.serialize }"
     end
@@ -406,6 +408,23 @@ class GraphWeaver::Codegen
     def bare_type = "#{class_name}::Type"
   end
 
+  # An abstract fragment narrowing to one member hoists to that member's
+  # struct, and narrowing filters — so the match is tested at the reference,
+  # the way NarrowedNode does it, rather than inside a T::Struct.from_h that
+  # has no way to answer nil. See NarrowedNode for what `typename` being
+  # absent means.
+  class NarrowedRefNode < HoistedRefNode
+    def initialize(class_name, graphql_type = nil, typename: nil)
+      super(class_name, graphql_type)
+      @typename = typename
+    end
+
+    def cast(expr, depth)
+      match = @typename ? "#{expr}[\"__typename\"] == #{@typename.inspect}" : "!#{expr}.empty?"
+      "(#{match} ? #{super} : nil)"
+    end
+  end
+
   # An input-object variable: emitted as a module-level T::Struct whose
   # serialize produces the wire hash. Inputs never cast FROM the wire.
   # Joins the coerce protocol so execute kwargs accept plain hashes,
@@ -479,5 +498,5 @@ class GraphWeaver::Codegen
   # from inside the walk.
   private_constant :Node, :Scalar, :NonNull, :List, :ObjectNode, :EnumNode,
     :MappedEnum, :NarrowedNode, :UnionNode, :HoistedRefNode, :UnionRefNode,
-    :InputNode, :RepresentationNode
+    :NarrowedRefNode, :InputNode, :RepresentationNode
 end

data/lib/graph_weaver/codegen.rb

@@ -191,7 +191,7 @@ class GraphWeaver::Codegen
     check_shared_collisions!(hoisted)
     nodes.each do |node|
       check_shadowing!(node)
-      check_abstract_mixins!(node)
+      check_abstract_mixins!(node, hoisted: true)
     end
 
     emit_types_files(nodes).tap { report_untyped_scalars }
@@ -216,30 +216,44 @@ class GraphWeaver::Codegen
 
     fragment = fragments.fetch(name)
     type = @schema.get_type(fragment.type.name)
-    return object_node(type, fragment.selections, class_name) if type.kind.object?
-
-    members = union_members(type, fragment.selections)
-    UnionNode.new(class_name, members, catch_all_member(type, fragment.selections, members))
+    selections = fragment.selections
+    return object_node(type, selections, class_name) if type.kind.object?
+
+    # the abstract shape is the fragment's own selections' to decide, exactly
+    # as it would be at a field spelling them inline — see abstract_shape
+    case (shape = abstract_shape(type, selections))
+    when :abstract_level then object_node(type, selections, class_name)
+    when :dispatch
+      members = union_members(type, selections)
+      UnionNode.new(class_name, members, catch_all_member(type, selections, members))
+    else
+      narrowing_tag!(shape, type, selections)
+      object_node(shape, selections, class_name)
+    end
   end
   private :hoisted_fragment
 
   # Schema type names are unique, so an input and an enum can never land on the
   # same name — but a hoisted type is named for its FRAGMENT, which the schema
-  # knows nothing about. One shared module means one namespace, so a fragment
-  # named after a type it doesn't describe has to refuse rather than overwrite.
+  # knows nothing about: two fragments camelize onto one name as readily as one
+  # lands on a type's. One shared module means one namespace, so either
+  # collision refuses rather than overwrites. Sorted, so which query file was
+  # walked first doesn't decide which fragment is named as the incumbent.
   def check_shared_collisions!(names)
     taken = {}
     @enums.each { |graphql_name, node| taken[node.class_name] = "the schema enum #{graphql_name}" }
     @mapped_enums.each_key { |graphql_name| taken[camelize(graphql_name)] = "the schema enum #{graphql_name}" }
     @variable_inputs.each { |graphql_name, node| taken[node.class_name] = "the input type #{graphql_name}" }
 
-    names.each do |name|
+    names.uniq.sort.each do |name|
       class_name = camelize(name)
-      claim = taken[class_name] or next
+      if (claim = taken[class_name])
+        raise GraphWeaver::Error,
+          "shared fragment #{name.inspect} hoists to #{@name}::#{class_name}, " \
+          "where #{claim} already generates — rename the fragment"
+      end
 
-      raise GraphWeaver::Error,
-        "shared fragment #{name.inspect} hoists to #{@name}::#{class_name}, " \
-        "where #{claim} already generates — rename the fragment"
+      taken[class_name] = "the shared fragment #{name.inspect}"
     end
   end
   private :check_shared_collisions!
@@ -924,24 +938,37 @@ class GraphWeaver::Codegen
   end
   private_constant :AbstractField
 
-  # Which of four shapes an abstract-typed field generates. The selection
-  # decides, not the schema: what it narrows to, and how it was spread.
+  # An abstract-typed field. Hoisting is asked FIRST, as it is for an object
+  # field: a whole field spread as one shared fragment is one shared type
+  # whatever shape that fragment has, and which shape it has must not be what
+  # decides — adding a second `... on` to a fragment would otherwise move every
+  # consumer's constant.
   def abstract_field(field)
-    conditions = concrete_conditions(field.core, field.selections)
-    shared = abstract_level_fields(field.core, field.selections)
-
-    if conditions.empty?
-      abstract_level_struct(field)
-    elsif conditions.size == 1 && shared.empty? &&
-        (member = @schema.get_type(conditions.first)).kind.name == "OBJECT"
-      narrowed_struct(field, member)
-    elsif (frag = hoistable_spread(field.core, field.selections))
-      hoisted_ref(field.type, frag)
-    else
-      dispatch_union(field)
+    if (frag = hoistable_spread(field.core, field.selections))
+      return hoisted_ref(field.type, frag)
+    end
+
+    case (shape = abstract_shape(field.core, field.selections))
+    when :abstract_level then abstract_level_struct(field)
+    when :dispatch then dispatch_union(field)
+    else narrowed_struct(field, shape)
     end
   end
 
+  # Which of three shapes an abstract selection generates, decided by the
+  # selection rather than the schema: :abstract_level when it names no concrete
+  # type, the one object member when it narrows to exactly that and nothing
+  # else, :dispatch otherwise. Both the hoisted type and every reference to it
+  # ask this, so the two can't disagree about what was built.
+  def abstract_shape(core, selections)
+    conditions = concrete_conditions(core, selections)
+    return :abstract_level if conditions.empty?
+    return :dispatch unless conditions.size == 1 && abstract_level_fields(core, selections).empty?
+
+    member = @schema.get_type(conditions.first)
+    member.kind.name == "OBJECT" ? member : :dispatch
+  end
+
   # Every member carries the abstract-level fields, so one struct answers for
   # all of them and there is nothing to dispatch on — for a union, the only
   # selection that can get here is __typename.
@@ -951,34 +978,47 @@ class GraphWeaver::Codegen
   end
 
   # Narrowing to the one member a `... on X` names filters: the field is nil
-  # whenever the runtime type doesn't match. With `__typename` selected the
-  # match is read off the tag; without one there is nothing to read but
-  # emptiness, and a fragment whose every field hides behind @skip/@include
-  # would make a real match indistinguishable from a miss ({} either way) —
-  # refuse rather than guess.
+  # whenever the runtime type doesn't match.
   def narrowed_struct(field, member)
-    tag = member.graphql_name if dispatchable_typename?(field.core, field.selections)
-    unless tag || unconditional_field?(member, field.selections)
-      raise GraphWeaver::Error,
-        "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
-        "@skip/@include (or a `__typename` to match on) — an all-conditional selection " \
-        "makes a match indistinguishable from nil"
-    end
-
+    tag = narrowing_tag!(member, field.core, field.selections)
     name = pick_name(field.key, field.taken)
     nilable_type_ref(field.type) { NarrowedNode.new(object_node(member, field.selections, name), typename: tag) }
   end
 
+  # What a narrowed selection matches on: the member's name when `__typename`
+  # is selected, else nil for "the object came back empty". A fragment whose
+  # every field hides behind @skip/@include leaves nothing to read either way
+  # ({} on a match and on a miss alike) — refuse rather than guess.
+  def narrowing_tag!(member, core, selections)
+    return member.graphql_name if dispatchable_typename?(core, selections)
+    return if unconditional_field?(member, selections)
+
+    raise GraphWeaver::Error,
+      "narrowed `... on #{member.graphql_name}` needs at least one field not under " \
+      "@skip/@include (or a `__typename` to match on) — an all-conditional selection " \
+      "makes a match indistinguishable from nil"
+  end
+
   # A whole field spread as one named shared fragment points at the type
   # hoisted into the shared types module, so the same shape across queries is
-  # one Ruby type — for a union, one exhaustive `case ... T.absurd`.
+  # one Ruby type. Which node stands in for it follows the shape hoisted_fragment
+  # built: a dispatch module for a union, a struct otherwise — and a narrowed
+  # one still filters, so the match is read here rather than inside a struct
+  # whose from_h cannot answer nil.
   def hoisted_ref(field_type, frag)
     @used_fragments << frag unless @used_fragments.include?(frag)
-    # an abstract type hoists to a dispatch module, an object type to a struct
     core = field_type.unwrap
-    node_class = core.kind.object? ? HoistedRefNode : UnionRefNode
-    ref = node_class.new(camelize(frag), core.graphql_name)
-    type_ref(field_type) { ref }
+    name = camelize(frag)
+    return type_ref(field_type) { HoistedRefNode.new(name, core.graphql_name) } if core.kind.object?
+
+    selections = @fragments.fetch(frag).selections
+    case (shape = abstract_shape(core, selections))
+    when :abstract_level then type_ref(field_type) { HoistedRefNode.new(name, core.graphql_name) }
+    when :dispatch then type_ref(field_type) { UnionRefNode.new(name, core.graphql_name) }
+    else
+      tag = narrowing_tag!(shape, core, selections)
+      nilable_type_ref(field_type) { NarrowedRefNode.new(name, core.graphql_name, typename: tag) }
+    end
   end
 
   # One member struct per type the selection names, chosen at runtime off
@@ -1500,7 +1540,7 @@ class GraphWeaver::Codegen
       constant, group = collisions.first
       more = collisions.size - 1
       raise GraphWeaver::Error,
-        "enum #{core.graphql_name} values #{group.join(" and ")} both become the constant #{constant}" \
+        "enum #{core.graphql_name} values #{group.join(" and ")} all become the constant #{constant}" \
         "#{" (and #{more} more colliding pair#{"s" if more > 1})" unless more.zero?} — if each pair is one " \
         "value, say which spelling goes on the wire:\n  " \
         "#{EnumType.alias_suggestion(core.graphql_name, collisions.values)}\n" \
@@ -1549,19 +1589,23 @@ class GraphWeaver::Codegen
   # query selecting a subset generated fine and failed in the app's own
   # `srb tc`, two tools from the query that fell short. Walked from the root the
   # way shadowing is, so the refusal can name the struct by its path.
-  def check_abstract_mixins!(node, path = [])
+  def check_abstract_mixins!(node, path = [], hoisted: false)
     case node
     when UnionNode
       inner = path + [node.class_name]
-      (node.members.each_value.to_a + [node.catch_all]).each { |member| check_abstract_mixins!(member, inner) }
+      (node.members.each_value.to_a + [node.catch_all]).each do |member|
+        check_abstract_mixins!(member, inner, hoisted:)
+      end
     when ObjectNode
       inner = path + [node.class_name]
-      refuse_unsatisfiable_mixin!(node, inner)
-      node.fields.each { |field| check_abstract_mixins!(field.node.nested, inner) if field.node.nested }
+      refuse_unsatisfiable_mixin!(node, inner, hoisted:)
+      node.fields.each do |field|
+        check_abstract_mixins!(field.node.nested, inner, hoisted:) if field.node.nested
+      end
     end
   end
 
-  def refuse_unsatisfiable_mixin!(node, path)
+  def refuse_unsatisfiable_mixin!(node, path, hoisted:)
     return if node.overrides.empty?
 
     mixins = @registry.type_registry.dig(node.graphql_type, :mixins) || []
@@ -1577,13 +1621,21 @@ class GraphWeaver::Codegen
     mixin = mixins.find { |m|
       T::AbstractUtils.declared_abstract_methods_for(m).any? { |method| missing.include?(method.name.to_s) }
     }
+    them = missing.one? ? "it" : "them"
+    # the second door is "hoist it", which a struct built inside the shared
+    # types module has already been through
+    fix = if hoisted
+      "Select #{them} in the fragment."
+    else
+      "Select #{them} here, or select #{node.graphql_type} through one shared " \
+        "fragment (`{ ...Frag }`), which hoists one struct for every query to share."
+    end
+
     raise GraphWeaver::Error,
       "#{[@name, *path].join("::")} includes #{mixin.name}, which declares " \
       "#{GraphWeaver::Internal::Util.sample(missing.map(&:inspect))} abstract — this selection does " \
-      "not provide #{missing.one? ? "it" : "them"}, and every struct generated from " \
-      "#{node.graphql_type} includes the mixin, so `srb tc` fails on this one. Select " \
-      "#{missing.one? ? "it" : "them"} here, or select #{node.graphql_type} through one shared " \
-      "fragment (`{ ...Frag }`), which hoists one struct for every query to share."
+      "not provide #{them}, and every struct generated from " \
+      "#{node.graphql_type} includes the mixin, so `srb tc` fails on this one. #{fix}"
   end
   private :check_abstract_mixins!, :refuse_unsatisfiable_mixin!
 

data/lib/graph_weaver/graph.rb

@@ -93,8 +93,19 @@ module GraphWeaver
     # constant; this is the one knob that settles both.
     def namespace = @namespace
 
+    # The shared types module. Inside a namespace the default is plain `Types`,
+    # so `namespace:` alone leaves a tree Zeitwerk names correctly — types.rb
+    # holds it, and Zeitwerk reads that file as `<Namespace>::Types`. At the top
+    # level it stays GraphQLTypes, where a bare ::Types would collide with
+    # graphql-ruby's own Types:: convention.
+    NESTED_TYPES_MODULE = "Types"
+    private_constant :NESTED_TYPES_MODULE
+
     def types_module
-      @types_module || (namespace ? "#{namespace}::#{GraphWeaver.types_module}" : GraphWeaver.types_module)
+      return @types_module if @types_module
+      return GraphWeaver.types_module unless namespace
+
+      "#{namespace}::#{GraphWeaver.types_module(NESTED_TYPES_MODULE)}"
     end
 
     # The graphql-ruby schema, however it was named: a class, a Client, a path
@@ -152,15 +163,48 @@ module GraphWeaver
       # read a source off, so the source is where its modules already post.
       # That is what bootstraps a second graph's dump: URL= names one
       # endpoint, and each graph has its own.
-      url = path ? GraphWeaver::SchemaLoader.provenance(path)&.dig("url") : (client_url if named_dump_path)
-      url || live_schema
+      source = path ? GraphWeaver::SchemaLoader.provenance(path)&.dig("url") : (client_source if named_dump_path)
+      source || live_schema
+    end
+
+    # The server behind this graph, however it is named: the url the dump
+    # recorded, else the graphql-ruby class this process runs, else whatever
+    # this graph's client reaches. nil when there is nothing to ask — a dump
+    # with no provenance, and no client with a server behind it.
+    #
+    # The one source rule the three schema tasks share: `schema:refresh`
+    # rewrites the dump from it, `schema:diff` says how far it has moved, and
+    # `queries:check` validates the queries against it.
+    def source = dump_source || client_source
+
+    # The server this graph's client reaches, as something to ask: the url it
+    # posts to, else the graphql-ruby class it runs in-process. A client that
+    # runs one names a server as surely as a client that posts to one — and
+    # reading only the url is what let `source_transport` reach a schema class
+    # that `source` said wasn't there.
+    def client_source
+      client_url || GraphWeaver::Internal::Util.live_schema(client || GraphWeaver.client)
+    end
+    private :client_source
+
+    # How to reach that source. A schema class answers introspection itself. A
+    # url the dump recorded goes through SchemaLoader, which authenticates from
+    # the auth_env the dump named. A url that came from the graph's client is
+    # that client's own transport — headers, auth and all.
+    def source_transport
+      found = source
+      return found if found.is_a?(Module)
+      return GraphWeaver::SchemaLoader.source_transport(dump_path) if dump_source
+
+      target = client || GraphWeaver.client
+      target.respond_to?(:transport) ? target.transport : target
     end
 
     # The url this graph's modules post to, or nil — the graph's own client,
-    # else the app default, which is where its modules go too. What
-    # `schema:refresh` bootstraps a missing dump from, and what `rake
+    # else the app default, which is where its modules go too. What `rake
     # graph_weaver:graphs` reports; a client with no url (a schema class
-    # running in-process) has none to report.
+    # running in-process) has none to report, and `client_source` is the
+    # question that covers both.
     def client_url
       target = client || GraphWeaver.client
       target = (target.transport if target.respond_to?(:transport)) || target
@@ -248,6 +292,7 @@ module GraphWeaver
       def self.build(name, &block)
         builder = new(name)
         builder.instance_eval(&block)
+        refuse_callable_client!(name, builder.settings[:client])
         graph = GraphWeaver::Graph.new(name:, registrations: builder.registrations, **builder.settings)
         # the block's registrations are applied at generation; run them once
         # here so a bad one is a mistake in the block, said where it is written
@@ -265,6 +310,22 @@ module GraphWeaver
           "Declare graph #{name.inspect} from one.", e.backtrace
       end
 
+      # `schema` takes a callable — that is how an initializer names a class
+      # Zeitwerk hasn't loaded — and the same page says so, which makes one
+      # here an easy mistake. It was accepted, and surfaced much later as
+      # `undefined method 'execute' for an instance of Proc` under a rake
+      # backtrace. A client needs no lambda: the string form names the
+      # constant and is resolved when a module calls it.
+      def self.refuse_callable_client!(name, client)
+        return unless client.respond_to?(:call) && !client.respond_to?(:execute)
+
+        raise ArgumentError, "client in graph #{name.inspect} takes the object your modules " \
+          "call, and a callable doesn't answer #execute — name the object (client " \
+          "GraphWeaver.new(\"https://api.example.com/graphql\")), or its constant (client " \
+          "\"Billing::Schema\"), which is resolved when a module calls it and so needs no lambda"
+      end
+      private_class_method :refuse_callable_client!
+
       def initialize(name)
         @name = name
         @settings = {}

data/lib/graph_weaver/in_process.rb

@@ -55,7 +55,7 @@ class GraphWeaver::InProcess
     payload = { url: nil, schema: schema_label, operation: operation_name, client: self.class,
                 kind: GraphWeaver::Internal::Wire.kind(query) }
 
-    GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
+    GraphWeaver::Internal::Log.instrument_request(payload) do
       perform(query, variables, operation_name)
     end
   end