graph_weaver 0.4.6 → 0.5.0

data/lib/graph_weaver/codegen/emit.rb

@@ -10,21 +10,6 @@ class GraphWeaver::Codegen
 
     private
 
-    # The Relay convention — an operation whose only variable is a required
-    # input object — reads better flattened: the input's fields become
-    # execute's kwargs directly, and the wrapping level is rebuilt on the
-    # wire. Multi-variable (or nullable-input) operations keep the
-    # variable-per-kwarg surface.
-    def flatten_input(variables)
-      return unless variables.size == 1
-
-      var = variables.first
-      return unless var.required && var.node.is_a?(NonNull)
-
-      input = var.node.of
-      input if input.is_a?(InputNode)
-    end
-
     def input_references(node)
       node.fields.filter_map do |field|
         child = field.node
@@ -60,185 +45,166 @@ class GraphWeaver::Codegen
       [ordered, cyclic]
     end
 
-      # Mapped-enum tables, generated enums, and input structs
-      # (dependency-ordered, forward-declared when cyclic) — inline in the
-      # module that needs them, or once in the shared inputs module.
-      def emit_variable_types(out)
-          @mapped_enums.each_value do |mapped|
-            emit_mapped_enum(mapped, out, 1)
-            out << ""
-          end
-          @variable_enums.each_value do |enum|
-            emit_enum(enum, out, 1)
-            out << ""
-          end
-          inputs, cyclic = ordered_inputs
-          if cyclic
-            # Recursive input types (Hasura bool_exp et al) reference each other,
-            # so no definition order satisfies the runtime — forward-declare every
-            # class empty, then let the full definitions below reopen with props.
-            # eval'd so srb sees only the full bodies (reopening a T::Struct to
-            # add props is a static error; adding them at runtime is fine).
-            out << "  # runtime-only forward declarations: these input types reference"
-            out << "  # each other, so the full definitions below need the constants"
-            out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
-            inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
-            out << "  RUBY"
-            out << ""
-          end
-          inputs.each do |input|
-            emit_input(input, out, 1)
-            out << ""
-          end
-        end
-
-      # In the shared-inputs workflow the variable types live once in the
-      # inputs module; the query module aliases what it uses, so
-      # AdoptQuery::AdoptionInput stays a real constant — and shared types
-      # keep ONE identity across every module that touches them.
-      # Only the shared names THIS module's emission references: variable
-      # root types (and, when flattened, the root input's field types)
-      # plus every mapped-enum table (result casting reads them too).
-      # Nested types stay un-aliased — they live in the inputs module.
-      def shared_alias_names(variables, flatten)
-        nodes = variables.map(&:node)
-        nodes += flatten.fields.map(&:node) if flatten
-
-        names = @mapped_enums.each_value.flat_map { |m| ["#{m.const_prefix}_FROM_WIRE", "#{m.const_prefix}_TO_WIRE"] }
-        nodes.each do |wrapped|
-          node = T.let(wrapped, T.untyped)
-          node = node.of while node.is_a?(NonNull) || node.is_a?(List)
-          case node
-          when EnumNode, InputNode then names << node.class_name
-          end
-        end
-        names.uniq
+    # Mapped-enum tables, generated enums, and input structs
+    # (dependency-ordered, forward-declared when cyclic) — inline in the
+    # module that needs them, unless the shared module already holds them
+    # (then the module aliases them instead; see emit_shared_aliases).
+    def emit_variable_types(out)
+      return if @types_namespace
+
+      emit_enum_types(out)
+      inputs, cyclic = ordered_inputs
+      if cyclic
+        # Recursive input types (Hasura bool_exp et al) reference each other,
+        # so no definition order satisfies the runtime — forward-declare every
+        # class empty, then let the full definitions below reopen with props.
+        # eval'd so srb sees only the full bodies (reopening a T::Struct to
+        # add props is a static error; adding them at runtime is fine).
+        out << "  # runtime-only forward declarations: these input types reference"
+        out << "  # each other, so the full definitions below need the constants"
+        out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
+        inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
+        out << "  RUBY"
+        out << ""
       end
+      inputs.each do |input|
+        emit_input(input, out, 1)
+        out << ""
+      end
+    end
 
-      def emit_shared_aliases(out, names, namespace = @inputs_namespace)
-        return if names.empty?
-
-        names.each { |name| out << "  #{name} = #{namespace}::#{name}" }
+    # Every schema enum this walk touched, at module level: wire tables for
+    # the ones mapped onto an app enum, a T::Enum for the rest.
+    def emit_enum_types(out, indent = 1)
+      @mapped_enums.each_value do |mapped|
+        emit_mapped_enum(mapped, out, indent)
         out << ""
       end
+      @enums.each_value do |enum|
+        emit_enum(enum, out, indent)
+        out << ""
+      end
+    end
 
-      # The shared inputs artifact as files: inputs.rb (the manifest —
-      # requires, forward declarations for every struct so definition
-      # order never matters, then one require per type file) plus
-      # inputs/<type>.rb per enum/mapped-table/input struct.
-      def emit_inputs_files
-        files = {}
-        enum_files = []
-        struct_files = []
+    # In the shared workflow the types live once in the shared module and each
+    # query module aliases what it uses, so AdoptMutation::AdoptionInput stays a
+    # real constant — and a shared type keeps ONE identity across every module
+    # that touches it.
+    #
+    # Enums: every one this walk reached, since a result field and a variable
+    # both reference it by that name.
+    def shared_enum_names
+      @mapped_enums.each_value.flat_map { |m| ["#{m.const_prefix}_FROM_WIRE", "#{m.const_prefix}_TO_WIRE"] } +
+        @enums.each_value.map(&:class_name)
+    end
 
-        @mapped_enums.each do |graphql_name, mapped|
-          enum_files << inputs_file(files, graphql_name) { |out| emit_mapped_enum(mapped, out, 1) }
-        end
-        @variable_enums.each do |graphql_name, enum|
-          enum_files << inputs_file(files, graphql_name) { |out| emit_enum(enum, out, 1) }
-        end
-        inputs, = ordered_inputs
-        inputs.each do |input|
-          struct_files << inputs_file(files, input.class_name) { |out| emit_input(input, out, 1) }
-        end
+    # Inputs: only the variable root types — the names this module's own
+    # source spells. Nested input types stay un-aliased; they live in the
+    # shared module.
+    def shared_input_names(variables)
+      variables.map(&:node).filter_map { |wrapped|
+        node = T.let(wrapped, T.untyped)
+        node = node.of while node.is_a?(NonNull) || node.is_a?(List)
+        node.class_name if node.is_a?(InputNode)
+      }.uniq
+    end
 
-        manifest = []
-        manifest << "# typed: strict"
-        manifest << "# frozen_string_literal: true"
-        manifest << ""
-        manifest << "# Generated by GraphWeaver — do not edit. Shared variable types for"
-        manifest << "# this schema, one file per type; query modules alias what they use."
-        manifest << ""
-        requires = @requires.uniq.sort
-        if requires.any?
-          requires.each { |req| manifest << "require #{req.inspect}" }
-          manifest << ""
-        end
-        manifest << "module #{@module_name}; end"
-        manifest << ""
-        enum_files.sort.each { |file| manifest << "require_relative #{file.delete_suffix(".rb").inspect}" }
-        if inputs.any?
-          manifest << ""
-          manifest << "# runtime-only forward declarations: input types reference each"
-          manifest << "# other across files, so every constant must exist before any"
-          manifest << "# definition loads (srb sees only the full bodies)"
-          manifest << "module #{@module_name}"
-          manifest << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
-          inputs.each { |input| manifest << "    class #{input.class_name} < T::Struct; end" }
-          manifest << "  RUBY"
-          manifest << "end"
-          manifest << ""
-          struct_files.sort.each { |file| manifest << "require_relative #{file.delete_suffix(".rb").inspect}" }
-        end
+    def emit_shared_aliases(out, names, namespace)
+      return if names.empty?
 
-        files["inputs.rb"] = manifest.join("\n") + "\n"
-        files
-      end
+      names.each { |name| out << "  #{name} = #{namespace}::#{name}" }
+      out << ""
+    end
 
-      # The shared unions artifact as a single file: every hoisted union as a
-      # <module_name>::<Name> module. Unions don't cross-reference (each is a
-      # self-contained fragment), so there's no need for per-type files or the
-      # forward declarations recursive input types require.
-      def emit_unions_file(unions)
-        out = []
-        out << "# typed: strict"
-        out << "# frozen_string_literal: true"
-        out << ""
-        out << "# Generated by GraphWeaver — do not edit. Shared union types for this"
-        out << "# schema (named fragments on union fields); query modules alias what they use."
+    # 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)
+      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
+      enums = @mapped_enums.map { |name, mapped|
+        type_file(files, camelize(name)) { |out| emit_mapped_enum(mapped, out, 1) }
+      } + @enums.each_value.map { |enum|
+        type_file(files, enum.class_name) { |out| emit_enum(enum, out, 1) }
+      }
+      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) } }
+
+      out = []
+      out << "# typed: strict"
+      out << "# frozen_string_literal: true"
+      out << ""
+      out << "# Generated by GraphWeaver — 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 << ""
+      requires = @requires.uniq.sort
+      if requires.any?
+        requires.each { |req| out << "require #{req.inspect}" }
         out << ""
-        requires = @requires.uniq.sort
-        if requires.any?
-          requires.each { |req| out << "require #{req.inspect}" }
-          out << ""
-        end
+      end
+      out << "module #{@module_name}; end"
+      out << ""
+      if inputs.any?
+        out << "# runtime-only forward declarations: input types reference each other"
+        out << "# across files, so every constant must exist before any definition loads"
+        out << "# (srb sees only the full bodies)"
         out << "module #{@module_name}"
-        out << "  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
-        # a member selecting a mapped enum (register_enum) reads its module-level
-        # <NAME>_FROM_WIRE table — emit those here so from_h resolves them, the
-        # same way emit_variable_types does for the query module
-        @mapped_enums.each_value do |mapped|
-          emit_mapped_enum(mapped, out, 1)
-          out << ""
-        end
-        unions.each do |union|
-          emit_union(union, out, 1)
-          out << ""
-        end
-        out.pop if out.last == ""
+        out << "  eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)"
+        inputs.each { |input| out << "    class #{input.class_name} < T::Struct; end" }
+        out << "  RUBY"
         out << "end"
-
-        { "unions.rb" => out.join("\n") + "\n" }
+        out << ""
+      end
+      # enums first: an input struct's props and a union member's selections
+      # 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"
+      end
+      (enums.sort + structs.sort + hoisted.sort).each do |file|
+        out << "require_relative #{file.delete_suffix(".rb").inspect}"
       end
 
-      # one type per file, wrapped in the namespace so bare sibling
-      # references resolve lexically
-      def inputs_file(files, name)
-        out = []
-        out << "# typed: strict"
-        out << "# frozen_string_literal: true"
-        out << ""
-        out << "# Generated by GraphWeaver — do not edit."
-        out << ""
-        out << "module #{@module_name}"
-        yield(out)
-        out << "end"
+      files["types.rb"] = out.join("\n") + "\n"
+      files
+    end
 
-        file = "inputs/#{GraphWeaver::Inflect.underscore(name)}.rb"
-        files[file] = out.join("\n") + "\n"
-        file
-      end
+    # one type per file, wrapped in the shared module so bare sibling
+    # references resolve lexically
+    def type_file(files, name)
+      out = []
+      out << "# typed: strict"
+      out << "# frozen_string_literal: true"
+      out << ""
+      out << "# Generated by GraphWeaver — do not edit."
+      out << ""
+      out << "module #{@module_name}"
+      yield(out)
+      out << "end"
 
-    # The whole generated file: header, requires, the QUERY heredoc,
-    # enum tables, input structs (dependency-ordered, forward-declared
-    # when cyclic), the Result tree, and execute — assembled from the
-    # generator's walked state.
-    def emit_module(root, variables)
-      flatten = flatten_input(variables)
-      aliases = @inputs_namespace ? shared_alias_names(variables, flatten) : []
-      # hoisted unions the result tree references, aliased so <Name>::Type and
-      # <Name>.from_h resolve to the shared module
-      union_aliases = @used_unions.map { |name| camelize(name) }.uniq.sort
+      file = "types/#{GraphWeaver::Inflect.underscore(name)}.rb"
+      files[file] = out.join("\n") + "\n"
+      file
+    end
+
+    # The whole generated file: header, requires, the QUERY heredoc and
+    # its OPERATION_NAME, enum tables, input structs (dependency-ordered,
+    # forward-declared when cyclic), the Result tree, and execute —
+    # 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).
+      aliases = if @types_namespace
+        (shared_input_names(variables) + shared_enum_names +
+          @used_unions.map { |name| camelize(name) }).uniq.sort
+      else
+        []
+      end
 
       out = []
       out << "# typed: strict"
@@ -251,14 +217,10 @@ class GraphWeaver::Codegen
         requires.each { |req| out << "require #{req.inspect}" }
         out << ""
       end
+      # the aliases below need the shared module loaded (same directory by the
+      # generate! convention)
       if aliases.any?
-        # the aliases below need the shared module loaded (same directory
-        # by the generate! convention)
-        out << "require_relative \"inputs\""
-        out << ""
-      end
-      if union_aliases.any?
-        out << "require_relative \"unions\""
+        out << "require_relative \"types\""
         out << ""
       end
       out << "module #{@module_name}"
@@ -272,20 +234,71 @@ class GraphWeaver::Codegen
       @query.each_line { |line| out << "    #{line}".rstrip }
       out << "  #{delimiter}"
       out << ""
-      if @inputs_namespace
-        emit_shared_aliases(out, aliases)
-      else
-        emit_variable_types(out)
-      end
-      emit_shared_aliases(out, union_aliases, @unions_namespace)
+      out << "  # sent as the request's operationName — what an APM keys traces on"
+      out << "  OPERATION_NAME = T.let(#{operation_name.inspect}, T.nilable(String))"
+      out << ""
+      emit_shared_aliases(out, aliases, @types_namespace)
+      emit_variable_types(out)
+      emit_representations(out, representations)
       emit_nested(root, out, 1)
       out << ""
-      emit_execute(out, variables, flatten:)
+      emit_execute(out, variables)
       out << "end"
 
       out.join("\n") + "\n"
     end
 
+    # Typed constructors for the entity references an
+    # `_entities(representations:)` query takes — one per entity the query's
+    # selection reaches, its kwargs the type's @key fields. A single-key
+    # entity types them required, so an incomplete representation is a
+    # Sorbet error rather than a round trip; alternative keys and nested key
+    # sets are what GraphWeaver::Representation.build checks at runtime.
+    def emit_representations(out, nodes)
+      return if nodes.empty?
+
+      out << "  # Entity references for _entities(representations:) — one builder"
+      out << "  # per entity this query can resolve, typed from its @key fields."
+      out << "  module Representations"
+      out << "    extend T::Sig" if GraphWeaver.extend_t_sig?
+
+      nodes.each do |node|
+        out << ""
+        out << "    # #{node.graphql_type} #{node.key_fields.map { |set| "@key(fields: #{set.inspect})" }.join(" ")}"
+        sig = node.params.map { |param| "#{param.kwarg}: #{param.type}" }.join(", ")
+        out << "    sig { params(#{sig}).returns(T::Hash[String, T.untyped]) }"
+        kwargs = node.params.map { |param| param.required ? "#{param.kwarg}:" : "#{param.kwarg}: nil" }.join(", ")
+        out << "    def self.#{node.method_name}(#{kwargs})"
+        out << "      GraphWeaver::Representation.build(#{node.graphql_type.inspect}, {"
+        node.params.each { |param| out << "        #{param.wire.inspect} => #{param.value}," }
+        out << "      }, #{node.key_sets.inspect})"
+        out << "    end"
+      end
+
+      # Builders are query-driven, so an entity the `_entities` selection
+      # doesn't name has none — a bare NoMethodError there points at nothing.
+      out << ""
+      out << "    BUILDERS = T.let(#{nodes.map(&:method_name).sort.inspect}.freeze, T::Array[String])"
+      out << "    private_constant :BUILDERS"
+      out << ""
+      out << "    sig { params(name: Symbol, args: T.untyped, block: T.untyped).returns(T.noreturn) }"
+      out << "    def self.method_missing(name, *args, &block)"
+      out << '      type = GraphWeaver::Inflect.camelize(name.to_s)'
+      out << '      raise NoMethodError, "no representation builder for #{type} (this query builds: ' \
+        '#{BUILDERS.join(", ")}) — if #{type} is an entity of this subgraph, name it in the ' \
+        '_entities selection (`... on #{type} { __typename }`) and regenerate"'
+      out << "    end"
+
+      out << "  end"
+      out << ""
+    end
+
+    # Is this node defined once at module level rather than inside the struct
+    # that references it? (Variable enums — see the ENUM branch of object_node.)
+    def module_level?(node)
+      @enums.value?(node)
+    end
+
     def emit_nested(node, out, indent)
       case node
       when UnionNode then emit_union(node, out, indent)
@@ -334,7 +347,11 @@ class GraphWeaver::Codegen
 
       # uniq by object identity: deduped sibling unions share one node, so the
       # shared type is emitted once (both fields' consts already reference it).
-      node.fields.filter_map { |field| field.node.nested }.uniq.each do |child|
+      # A variable enum a result field reuses is already defined at module
+      # level (or aliased from the shared inputs module) — redefining it here
+      # would shadow the shared type back apart.
+      children = node.fields.filter_map { |field| field.node.nested }.uniq
+      children.reject { |child| module_level?(child) }.each do |child|
         emit_nested(child, out, indent + 1)
         out << ""
       end
@@ -351,9 +368,9 @@ class GraphWeaver::Codegen
         out << "#{pad}      #{field.prop}: #{field_cast(field)},"
       end
       out << "#{pad}    )"
-      out << "#{pad}  rescue GraphWeaver::TypeError"
-      out << "#{pad}    raise # already wrapped by a nested struct — keep the innermost context"
-      out << "#{pad}  rescue TypeError, ArgumentError, KeyError => e"
+      out << "#{pad}  rescue GraphWeaver::Error"
+      out << "#{pad}    raise # already branded by a nested struct — keep the innermost context"
+      out << "#{pad}  rescue StandardError => e" # a scalar's cast may raise anything
       out << "#{pad}    raise GraphWeaver::TypeError.new(struct: self, error: e)"
       out << "#{pad}  end"
 
@@ -373,95 +390,93 @@ class GraphWeaver::Codegen
       out << "#{pad}module #{node.class_name}"
       out << "#{pad}  extend T::Sig" << "" if GraphWeaver.extend_t_sig?
 
-      node.members.each_value do |member|
+      structs = node.members.values + [node.catch_all].compact
+      structs.each do |member|
         emit_object(member, out, indent + 1)
         out << ""
       end
 
-      member_names = node.members.values.map(&:class_name)
+      member_names = structs.map(&:class_name)
       type_alias = member_names.size == 1 ? member_names.first : "T.any(#{member_names.join(", ")})"
       out << "#{pad}  Type = T.type_alias { #{type_alias} }"
       out << ""
       out << "#{pad}  sig { params(data: T::Hash[String, T.untyped]).returns(Type) }"
       out << "#{pad}  def self.from_h(data)"
-      out << "#{pad}    case (typename = data.fetch(\"__typename\"))"
+      if node.catch_all
+        out << "#{pad}    case data.fetch(\"__typename\")"
+      else
+        out << "#{pad}    case (typename = data.fetch(\"__typename\"))"
+      end
       node.members.each do |graphql_name, member|
         out << "#{pad}    when #{graphql_name.inspect} then #{member.class_name}.from_h(data)"
       end
-      out << "#{pad}    else raise GraphWeaver::TypeError.new(struct: self, message: \"unexpected __typename: \#{typename}\")"
+      if node.catch_all
+        out << "#{pad}    # a member this query names no fields on — including one the"
+        out << "#{pad}    # schema grew since generation"
+        out << "#{pad}    else #{node.catch_all.class_name}.from_h(data)"
+      else
+        out << "#{pad}    else raise GraphWeaver::TypeError.new(struct: self, message: \"unexpected __typename: \#{typename}\")"
+      end
       out << "#{pad}    end"
       out << "#{pad}  end"
       out << "#{pad}end"
     end
 
-    def emit_execute(out, variables, flatten: nil)
-      out << "  @client = T.let(nil, T.untyped)"
-      out << ""
-      out << "  class << self"
-      out << "    extend T::Sig" << "" if GraphWeaver.extend_t_sig?
-      out << "    sig { params(client: T.untyped).void }"
-      out << "    attr_writer :client"
-      out << ""
-      out << "    # default client (a GraphWeaver::Client or any transport) for"
-      out << "    # execute: per-module override, else the app default"
-      out << "    sig { returns(T.untyped) }"
-      out << "    def client"
-      out << "      @client || #{@client_const || "GraphWeaver.client!"}"
-      out << "    end"
-      out << "  end"
+    def emit_execute(out, variables)
+      # client/client= carry no per-query types, so they live in the gem
+      out << "  # client / client= — see GraphWeaver::QueryModule"
+      out << "  extend GraphWeaver::QueryModule"
+      if @client_const
+        out << ""
+        out << "  # the baked default client, resolved on first use"
+        out << "  DEFAULT_CLIENT = T.let(-> { #{@client_const} }, T.proc.returns(T.untyped))"
+      end
       out << ""
 
-      # the kwarg surface: the input's fields when flattened, else one
-      # kwarg per declared variable — typed identically either way. The
-      # per-call client override rides as an optional POSITIONAL arg, so
-      # variables keep the entire kwarg namespace (nothing is reserved).
-      params = flatten ? flatten.fields.partition(&:required).flatten : variables
-
-      sig_params = ["client: T.untyped"]
-      sig_params += params.map do |param|
-        bare = param.node.coerce? ? param.node.coerce_input_type : param.node.bare_type
-        kwarg_type = param.required || bare == "T.untyped" ? bare : "T.nilable(#{bare})"
-        "#{kwarg_name(param)}: #{kwarg_type}"
+      # The kwarg surface: one kwarg per declared variable, always — so the
+      # call sites a query already has don't change shape when it grows one.
+      # The per-call client override is a kwarg like the rest; a GraphQL
+      # variable can't claim the name (RESERVED_KWARGS).
+      #
+      # Required kwargs first, then optional ones (client: last, since it
+      # always has a default): Method#parameters reports them in that order
+      # whatever the source says, and sorbet-runtime checks the sig against it.
+      required, optional = variables.partition(&:required)
+      ordered = required + optional
+
+      sig_params = ordered.map do |var|
+        bare = var.node.coerce? ? var.node.coerce_input_type : var.node.bare_type
+        kwarg_type = var.required || bare == "T.untyped" ? bare : "T.nilable(#{bare})"
+        "#{var.kwarg}: #{kwarg_type}"
       end
+      sig_params << "client: T.untyped"
 
-      kwargs = ["client = nil"]
-      kwargs += params.map { |param| param.required ? "#{kwarg_name(param)}:" : "#{kwarg_name(param)}: nil" }
+      kwargs = required.map { |var| "#{var.kwarg}:" } +
+        optional.map { |var| "#{var.kwarg}: nil" } + ["client: nil"]
 
       # execute returns the full envelope; execute! is the strict shortcut for
       # `execute(...).data!` — the typed result, or a raised QueryError.
       # kwargs forward via hash shorthand (key == value)
-      forward = (["client"] + params.map { |param| "#{kwarg_name(param)}:" }).join(", ")
+      forward = (ordered.map { |var| "#{var.kwarg}:" } + ["client:"]).join(", ")
 
-      if flatten
-        out << "  # $#{variables.first.wire}'s fields, flattened into kwargs (single input-object variable)"
-      end
       out << "  sig { params(#{sig_params.join(", ")}).returns(GraphWeaver::Response[Result]) }"
       out << "  def self.execute(#{kwargs.join(", ")})"
 
-      if flatten
-        fields = flatten.fields.map { |field| "#{field.prop}:" }.join(", ")
-        out << "    variables = {"
-        out << "      #{variables.first.wire.inspect} => #{flatten.class_name}.coerce({ #{fields} }).serialize,"
-        out << "    }"
+      if required.empty?
+        out << "    variables = {}"
       else
-        required, optional = variables.partition(&:required)
-        if required.empty?
-          out << "    variables = {}"
-        else
-          out << "    variables = {"
-          required.each do |var|
-            out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
-          end
-          out << "    }"
-        end
-        optional.each do |var|
-          out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
+        out << "    variables = {"
+        required.each do |var|
+          out << "      #{var.wire.inspect} => #{variable_serialize(var)},"
         end
+        out << "    }"
+      end
+      optional.each do |var|
+        out << "    variables[#{var.wire.inspect}] = #{variable_serialize(var)} unless #{var.kwarg}.nil?"
       end
 
       out << ""
-      out << "    transport = GraphWeaver.resolve_transport(client || self.client)"
-      out << "    from_response(transport.execute(QUERY, variables: variables))"
+      out << "    from_response(client_for(client).execute(QUERY, variables:, operation_name: OPERATION_NAME))"
       out << "  end"
       out << ""
       out << "  sig { params(#{sig_params.join(", ")}).returns(Result) }"
@@ -484,7 +499,7 @@ class GraphWeaver::Codegen
       out << "  # \"errors\" => ..., \"extensions\" => ...} with wire-cased string keys."
       out << "  sig { params(response: T.untyped).returns(GraphWeaver::Response[Result]) }"
       out << "  def self.from_response(response)"
-      out << "    raw = response.to_h"
+      out << "    raw = GraphWeaver.check_envelope!(response.to_h, Result)"
       out << "    GraphWeaver::Response[Result].new("
       out << "      data: (Result.from_h(raw[\"data\"]) if raw[\"data\"]),"
       out << "      errors: (raw[\"errors\"] || []).map { |e| GraphWeaver::GraphQLError.from_h(e) },"
@@ -499,12 +514,6 @@ class GraphWeaver::Codegen
       out << "  end"
     end
 
-    # a kwarg surface entry is a VarDef (.kwarg) or, when flattened, an
-    # InputNode::Field (.prop)
-    def kwarg_name(param)
-      param.respond_to?(:kwarg) ? param.kwarg : param.prop
-    end
-
     def variable_serialize(var)
       value = var.node.coerce? ? var.node.coerce(var.kwarg) : var.kwarg
       var.node.serialize_identity? ? value : var.node.serialize(value, 1)
@@ -533,6 +542,11 @@ class GraphWeaver::Codegen
       out << "#{pad}  include GraphWeaver::InputStruct"
       out << "#{pad}  extend GraphWeaver::InputStruct::ClassMethods"
       out << ""
+      if node.one_of
+        out << "#{pad}  # @oneOf: every field is nullable, so exactly-one is checked at runtime"
+        out << "#{pad}  ONE_OF = T.let(true, T::Boolean)"
+        out << ""
+      end
       node.fields.each do |field|
         default = field.required ? "" : ", default: nil"
         out << "#{pad}  const :#{field.prop}, #{field.node.prop_type}#{default}"