graph_weaver 0.7.3 → 0.7.5

data/lib/graph_weaver/codegen/enum_type.rb

@@ -2,8 +2,8 @@
 # frozen_string_literal: true
 
 class GraphWeaver::Codegen
-  # How one GraphQL enum maps onto an app-owned T::Enum, so generated
-  # code speaks YOUR enum instead of generating one per module:
+  # What a register_enum said about one GraphQL enum: the app-owned T::Enum
+  # its values map onto, and which wire spellings are the same value.
   #
   #      class PetKind < T::Enum
   #        enums { Cat = new("cat"); Dog = new("dog") }
@@ -17,11 +17,27 @@ class GraphWeaver::Codegen
   # value the schema declares must resolve — generation fails naming the
   # gaps — unless fallback: names a member to absorb unknown values
   # (forward-compat for servers that add members; inputs stay strict).
+  #
+  # alias: { "legacy_mode" => "LEGACY_MODE" } says two wire values are one
+  # 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
 
-    def initialize(graphql_name, type, map: nil, fallback: nil, requires: nil)
+    def initialize(graphql_name, type, map: nil, fallback: nil, requires: nil, aliases: nil)
       @graphql_name = graphql_name.to_s
+      @aliases = normalize_aliases!(aliases)
+      @type = type
+      @map = map || {}
+      @fallback = fallback
+
+      return alias_only!(map, fallback, requires) if type.nil?
+
       # A name, not the class, is what you write when the constant won't
       # resolve yet — which in Rails means a config/initializers file, since
       # autoloading is set up after those run. Say where it does resolve.
@@ -36,9 +52,6 @@ class GraphWeaver::Codegen
         raise ArgumentError, "type: must be a named constant (anonymous classes can't appear in generated source)"
       end
 
-      @type = type
-      @map = map || {}
-      @fallback = fallback
       @requires = GraphWeaver::Codegen.normalize_requires!(requires, load: true)
 
       if fallback && !type.values.include?(fallback)
@@ -46,28 +59,140 @@ class GraphWeaver::Codegen
       end
     end
 
-    # wire value => member for every value the schema declares; raises
-    # naming the unmappable ones (unless fallback: absorbs them)
-    def mapping_for(wire_values)
-      mapping = {}
+    # 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.
+    def tables_for(wire_values)
+      aliases = aliases_for(wire_values)
+      from_wire = {}
       missing = []
 
       wire_values.each do |wire|
-        member = @map[wire] || infer(wire)
-        member ? mapping[wire] = member : missing << wire
+        canonical = aliases.fetch(wire, wire)
+        member = @map[canonical] || infer(canonical)
+        member ? from_wire[wire] = member : missing << canonical
       end
 
       if missing.any? && !fallback
         raise GraphWeaver::Error,
-          "#{type} has no member for #{graphql_name} value(s) #{missing.join(", ")} — " \
+          "#{type} has no member for #{graphql_name} value(s) #{missing.uniq.join(", ")} — " \
           "add them, pin with map:, or absorb with fallback:"
       end
 
-      mapping
+      [from_wire, to_wire(from_wire, aliases)]
+    end
+
+    # alias spelling => the value it is read as, checked against what the
+    # schema declares — an alias for or onto a value that isn't there is a
+    # registration this schema disproves.
+    def aliases_for(wire_values)
+      declared = wire_values.sort.join(", ")
+
+      @aliases.each do |from, to|
+        unless wire_values.include?(from)
+          raise GraphWeaver::Error,
+            "enum #{graphql_name} has no value #{from.inspect} to alias — its values are #{declared}; " \
+            "fix the spelling or drop the alias"
+        end
+        unless wire_values.include?(to)
+          raise GraphWeaver::Error,
+            "enum #{graphql_name}: alias #{from.inspect} => #{to.inspect} names no value of #{graphql_name} — " \
+            "its values are #{declared}; the target is the spelling that goes on the wire"
+        end
+      end
+
+      @aliases
+    end
+
+    # The register_enum a set of indistinguishable wire values needs, ready to
+    # paste. SCREAMING_CASE is the GraphQL convention, so the odd spelling is
+    # guessed as the alias — every caller's sentence says to check the direction.
+    def self.alias_suggestion(graphql_name, groups, type = nil)
+      pairs = groups.flat_map { |group|
+        target = group.find { |value| value == value.upcase } || group.first
+        (group - [target]).map { |value| "#{value.inspect} => #{target.inspect}" }
+      }
+
+      "GraphWeaver.register_enum(#{graphql_name.inspect}#{type ? ", #{type}" : ""}, " \
+        "alias: { #{pairs.join(", ")} })"
     end
 
     private
 
+    # 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 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, alias: { \"old\" => \"NEW\" } to read two wire values as one, " \
+          "or fallback: true to absorb values the server adds"
+      end
+
+      extra = { map:, requires: }.compact.keys.first
+      if extra
+        raise ArgumentError,
+          "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 = []
+    end
+
+    # Sorted so generated source is stable across registration order.
+    def normalize_aliases!(aliases)
+      return {} if aliases.nil?
+
+      unless aliases.is_a?(Hash)
+        raise ArgumentError, "alias: is a hash of wire value => wire value, got #{aliases.inspect}"
+      end
+
+      pairs = aliases.to_h { |from, to| [from.to_s, to.to_s] }
+
+      self_alias = pairs.find { |from, to| from == to }
+      if self_alias
+        raise ArgumentError, "register_enum(#{graphql_name.inspect}): alias #{self_alias.first.inspect} => " \
+          "#{self_alias.last.inspect} reads a value as itself — drop it"
+      end
+
+      chained = pairs.keys.find { |from| pairs.value?(from) }
+      if chained
+        raise ArgumentError, "register_enum(#{graphql_name.inspect}): #{chained.inspect} is both an alias and " \
+          "the value an alias points at — an alias can't chain; point every spelling at the one that goes on the wire"
+      end
+
+      pairs.sort.to_h
+    end
+
+    # member => the one wire value it serializes to. Two spellings on one
+    # member with no alias saying which goes out is ambiguous — invert used to
+    # pick whichever came last, which for a deprecation pair was the dead one.
+    def to_wire(from_wire, aliases)
+      canonical = from_wire.except(*aliases.keys)
+      ambiguous = canonical.group_by { |_, member| member }.select { |_, pairs| pairs.size > 1 }
+      if ambiguous.any?
+        member, = ambiguous.first
+        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 " \
+          "#{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
+
+      canonical.invert
+    end
+
     # "CAT" matches serialize "cat"; "NOT_FOUND" matches "not_found"
     def infer(wire)
       @type.values.find { |member| normalize(member.serialize.to_s) == normalize(wire) }
@@ -80,19 +205,24 @@ 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 (see EnumType). The one
-    # implementation — GraphWeaver.register_enum is a delegate, so the same
-    # call reaches it whichever door you came in by.
+    # 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.
     #
     # A value map is a natural third *positional* guess, and Ruby's arity
     # complaint ("given 3, expected 2") never mentions the keyword.
-    def register_enum(graphql_name, type, positional_map = nil, map: nil, fallback: nil, requires: nil)
+    def register_enum(graphql_name, type = nil, positional_map = nil, map: nil, fallback: nil, requires: nil,
+      alias: nil)
       if positional_map
         raise GraphWeaver::Error, "register_enum: the value map is a keyword — " \
           "register_enum(#{graphql_name.inspect}, #{type}, map: {...})"
       end
 
-      enum_registry[graphql_name.to_s] = EnumType.new(graphql_name, type, map:, fallback:, requires:)
+      # `alias` is a Ruby keyword, so the parameter is only readable through binding
+      aliases = binding.local_variable_get(:alias)
+      enum_registry[graphql_name.to_s] = EnumType.new(graphql_name, type, map:, fallback:, requires:, aliases:)
     end
 
     def enum_registry

data/lib/graph_weaver/codegen/nodes.rb

@@ -113,11 +113,11 @@ class GraphWeaver::Codegen
 
     def cast(expr, depth)
       var = "v#{depth}"
-      element = if @of.non_null? || @of.identity?
-        @of.identity? ? var : @of.cast(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.cast("v#{depth + 1}", depth + 2)} }"
-      end
+      element =
+        if @of.identity? then var
+        elsif @of.non_null? then @of.cast(var, depth + 1)
+        else "#{var}&.then { |v#{depth + 1}| #{@of.cast("v#{depth + 1}", depth + 2)} }"
+        end
 
       "#{expr}.map { |#{var}| #{element} }"
     end
@@ -127,11 +127,11 @@ class GraphWeaver::Codegen
 
     def serialize(expr, depth)
       var = "v#{depth}"
-      element = if @of.non_null? || @of.serialize_identity?
-        @of.serialize_identity? ? var : @of.serialize(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.serialize("v#{depth + 1}", depth + 2)} }"
-      end
+      element =
+        if @of.serialize_identity? then var
+        elsif @of.non_null? then @of.serialize(var, depth + 1)
+        else "#{var}&.then { |v#{depth + 1}| #{@of.serialize("v#{depth + 1}", depth + 2)} }"
+        end
 
       "#{expr}.map { |#{var}| #{element} }"
     end
@@ -153,11 +153,11 @@ class GraphWeaver::Codegen
 
     def hash_coerce(expr, depth)
       var = "v#{depth}"
-      inner = if @of.non_null? || @of.hash_coerce_identity?
-        @of.hash_coerce_identity? ? var : @of.hash_coerce(var, depth + 1)
-      else
-        "#{var}&.then { |v#{depth + 1}| #{@of.hash_coerce("v#{depth + 1}", depth + 2)} }"
-      end
+      inner =
+        if @of.hash_coerce_identity? then var
+        elsif @of.non_null? then @of.hash_coerce(var, depth + 1)
+        else "#{var}&.then { |v#{depth + 1}| #{@of.hash_coerce("v#{depth + 1}", depth + 2)} }"
+        end
       return "#{expr}.map { |#{var}| #{inner} }" if hash_coerce_identity?
 
       # the index is a path segment — `where._and.0._not.species` needs the 0
@@ -178,14 +178,16 @@ class GraphWeaver::Codegen
 
     attr_reader :class_name, :fields
     # the GraphQL type this struct was generated from, any registered helper
-    # modules to include, and any resolved alias delegators (see extend_type)
-    attr_accessor :graphql_type, :mixins, :aliases
+    # modules to include, any resolved alias delegators, and the member names a
+    # mixin declares abstract — Sorbet demands the override on those (extend_type)
+    attr_accessor :graphql_type, :mixins, :aliases, :overrides
 
     def initialize(class_name)
       @class_name = class_name
       @fields = []
       @mixins = []
       @aliases = []
+      @overrides = []
     end
 
     def bare_type = class_name
@@ -203,19 +205,37 @@ class GraphWeaver::Codegen
   end
 
   class EnumNode < Node
-    attr_reader :class_name, :values
+    attr_reader :class_name, :values, :aliases
 
-    def initialize(class_name, values)
+    # fallback: the name of the member unknown wire values cast to (register_enum
+    # fallback: true), or nil for a strict enum
+    def initialize(class_name, values, aliases = {}, fallback: nil)
       @class_name = class_name
       @values = values
+      @aliases = aliases
+      @fallback = fallback
     end
 
     def bare_type = class_name
 
+    # wire spellings this enum reads as another of its values (register_enum
+    # alias:) — a module-level table, emitted beside the class
+    def aliased? = !@aliases.empty?
+    def alias_const = "#{GraphWeaver::Inflect.underscore(class_name).upcase}_ALIASES"
+
+    # register_enum fallback: true — the extra member every value the schema
+    # doesn't declare casts to, and the one member a variable can't send
+    attr_reader :fallback
+    def fallback? = !@fallback.nil?
+    def fallback_const = "#{class_name}::#{@fallback}"
+
     def cast(expr, _depth)
-      "GraphWeaver::Hints.enum(#{class_name}, #{expr})"
+      "GraphWeaver::Hints.enum(#{class_name}, #{expr}#{runtime_args})"
     end
 
+    # Other serializes to ENUM_FALLBACK_WIRE, which casts back to Other — so a
+    # result carrying it still round-trips through #as_json, even though no
+    # server would accept that spelling.
     def serialize(expr, _depth)
       "#{expr}.serialize"
     end
@@ -227,7 +247,11 @@ class GraphWeaver::Codegen
     def coerce? = true
 
     def coerce(expr)
-      "GraphWeaver::InputStruct.enum(#{class_name}, #{expr})"
+      "GraphWeaver::InputStruct.enum(#{class_name}, #{expr}#{runtime_args})"
+    end
+
+    def runtime_args
+      "#{", #{alias_const}" if aliased?}#{", fallback: #{fallback_const}" if fallback?}"
     end
 
     def input_type = "T.any(#{class_name}, String)"
@@ -240,13 +264,13 @@ class GraphWeaver::Codegen
   # <NAME>_TO_WIRE constants translate at the boundary. fallback: makes
   # casting absorb unknown wire values (inputs stay strict).
   class MappedEnum < Node
-    attr_reader :graphql_name, :mapping
+    attr_reader :graphql_name, :mapping, :to_wire
 
     def initialize(enum_type, wire_values)
       @graphql_name = enum_type.graphql_name
       @type_name = enum_type.type.name
       @fallback = enum_type.fallback
-      @mapping = enum_type.mapping_for(wire_values)
+      @mapping, @to_wire = enum_type.tables_for(wire_values)
     end
 
     def const_prefix = GraphWeaver::Inflect.underscore(@graphql_name).upcase
@@ -350,20 +374,22 @@ class GraphWeaver::Codegen
     def nested = self
   end
 
-  # A reference to a union hoisted into the shared types module (a named
-  # shared fragment spread as a whole union field): the query references
-  # <Name>::Type and dispatches through <Name>.from_h, where <Name> is the
-  # alias the query module gives GraphQLTypes::<Name>. The type family lives
-  # once in the shared module, so the same union across queries is one Ruby
-  # type — nested is nil, nothing is emitted here.
-  class UnionRefNode < Node
-    attr_reader :class_name
-
-    def initialize(class_name)
+  # A reference to a type hoisted into the shared types module (a named shared
+  # fragment spread as a whole field): the query casts through <Name>.from_h,
+  # where <Name> is the alias the query module gives GraphQLTypes::<Name>. The
+  # type lives once in the shared module, so the same fragment across queries
+  # is one Ruby type — nested is nil, nothing is emitted here.
+  class HoistedRefNode < Node
+    # graphql_type is carried for refusals alone — an alias path that tries to
+    # read into the hoisted struct says which type to register itself on
+    attr_reader :class_name, :graphql_type
+
+    def initialize(class_name, graphql_type = nil)
       @class_name = class_name
+      @graphql_type = graphql_type
     end
 
-    def bare_type = "#{class_name}::Type"
+    def bare_type = class_name
 
     def cast(expr, _depth)
       "#{class_name}.from_h(#{expr})"
@@ -374,12 +400,21 @@ class GraphWeaver::Codegen
     end
   end
 
+  # The same, on an abstract type: the hoisted name is a dispatch module, so
+  # the Ruby type is its member union rather than the module itself.
+  class UnionRefNode < HoistedRefNode
+    def bare_type = "#{class_name}::Type"
+  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,
   # normalized (and type-checked) through the generated .coerce.
   class InputNode < Node
-    Field = Struct.new(:prop, :wire, :node, :required)
+    # type: the schema's spelling of the field's type ("[Float!]!"), which a
+    # refusal reports — the Sorbet prop type is the library's vocabulary, not
+    # the caller's.
+    Field = Struct.new(:prop, :wire, :node, :required, :type)
 
     # graphql_name as well as class_name: a schema coordinate is spelled the
     # schema's way (pokemon_bool_exp.name), which camelize has already lost.
@@ -443,6 +478,6 @@ class GraphWeaver::Codegen
   # The IR is codegen's own vocabulary — every node type is reachable only
   # from inside the walk.
   private_constant :Node, :Scalar, :NonNull, :List, :ObjectNode, :EnumNode,
-    :MappedEnum, :NarrowedNode, :UnionNode, :UnionRefNode, :InputNode,
-    :RepresentationNode
+    :MappedEnum, :NarrowedNode, :UnionNode, :HoistedRefNode, :UnionRefNode,
+    :InputNode, :RepresentationNode
 end

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -56,6 +56,8 @@ class GraphWeaver::Codegen
     # is the whole rule, so key on that — a custom scalar registered as a
     # plain String gets the same check. ID is the exception GraphQL itself
     # names (see Coerce.id), matched by GraphQL name in #coercer.
+    # Read back off the wire too, where the type is one JSON already holds
+    # (see #wire_cast).
     COERCERS = {
       "Integer" => "integer",
       "Float" => "float",
@@ -83,15 +85,15 @@ class GraphWeaver::Codegen
 
     STDLIB = {
       "BigDecimal" => { serialize: [:to_s, "F"], requires: "bigdecimal" },
-      # JSON has one number type, so a whole Float arrives as `1` from every
-      # encoder that drops the trailing zero (graphql-js and Go both do)
-      "Float" => { cast: ->(expr) { "GraphWeaver::Coerce.float(#{expr})" } },
       # strftime, not #iso8601: DateTime < Date passes the is_a? guard, and its
       # #iso8601 writes a timestamp where the schema said a date goes
       "Date" => { cast: :iso8601, serialize: [:strftime, "%F"], requires: "date" },
-      # #iso8601 takes no precision, so it writes whole seconds and a
-      # sub-second timestamp goes back out poorer than it came in
-      "Time" => { cast: :parse, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "time" },
+      # Time.iso8601, not Time.parse: the latter also reads "Jan 15 2024
+      # 10:20", which no spec-compliant server writes, at 3× the cost.
+      # Writing back goes through Coerce.timestamp rather than #iso8601,
+      # which takes no precision — a sub-second timestamp would go out
+      # poorer than it came in.
+      "Time" => { cast: :iso8601, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "time" },
       "DateTime" => { cast: :iso8601, serialize: TIMESTAMP, call: TIMESTAMP_CALL, requires: "date" },
     }.freeze
 
@@ -122,11 +124,12 @@ class GraphWeaver::Codegen
         end
       @cast_given = cast unless cast == :itself
       codec = @klass && CODECS.find { |c| @klass.respond_to?(c.probe) }
-      @cast = normalize_cast(cast || known[:cast], codec&.cast || kernel_cast)
+      @cast = normalize_cast(cast || known[:cast], wire_cast || codec&.cast || kernel_cast)
       @serialize = normalize_serialize(serialize || known[:serialize], codec&.serialize)
       @serialize_value = (known[:call] if serialize.nil?) ||
         runtime_serialize(serialize || known[:serialize], codec)
       warn_half_a_value_object
+      warn_half_a_codec(serialize)
     end
 
     def cast(expr) = @cast&.call(expr)
@@ -145,6 +148,10 @@ class GraphWeaver::Codegen
       @serialize_value.call(value)
     end
 
+    # Whether #serialize_value actually runs this registration's serializer,
+    # rather than passing the value through for want of one to run.
+    def serialize_value? = !@serialize_value.nil?
+
     # The code that normalizes a loose input — a Rails param — into this
     # scalar's Ruby type before it is serialized, or nil for nothing to do.
     # The Ruby type's own rule in Coerce is the check, which is what
@@ -207,6 +214,32 @@ class GraphWeaver::Codegen
       end
     end
 
+    # The other half of the same rule: a registration says both directions or
+    # is told what it can't do. A cast with nothing to write back reads the
+    # wire and can't put a variable of that scalar onto it, and a result's
+    # #as_json can't reproduce what the server sent — both silent, since
+    # `#to_json` answers for any object.
+    def warn_half_a_codec(serialize)
+      # nothing said and nothing inferred: `serialize: :itself` said it, and a
+      # Ruby type JSON already holds has no other half to name
+      return if !cast? || serialize? || !serialize.nil? || json_shaped?
+
+      GraphWeaver::Internal::Log.log(:warn) do
+        "register_scalar(#{@graphql_name.inspect}, #{@klass ? @type : @type.inspect}): cast: reads " \
+          "#{GraphWeaver::Internal::Util.article(@type)} #{@type} off the wire and nothing writes one " \
+          "back — a #{@graphql_name} variable goes out as whatever #to_json makes of it, and a result's " \
+          "#as_json can't reproduce what the server sent. Name the other half (serialize: :to_s names an " \
+          "instance method, serialize: [:to_s, \"F\"] passes it arguments, " \
+          "serialize: ->(v) { \"\#{v}.to_s\" } emits any expression), or serialize: :itself if the value " \
+          "really does go out as it is"
+      end
+    end
+
+    # A Ruby type JSON already holds writes itself, subclasses included
+    def json_shaped?
+      wire_class?(@type) || (!@klass.nil? && WIRE_CLASSES.any? { |native| @klass <= native })
+    end
+
     def defines?(method)
       ![BasicObject, Kernel, Object].include?(@klass.instance_method(method).owner)
     end
@@ -231,13 +264,31 @@ class GraphWeaver::Codegen
       end
     end
 
+    # `register_scalar("Count", Integer)` says the scalar IS an Integer, so the
+    # library's own rule for that class runs in both directions — the entry
+    # #coercer brands a variable with, reading the wire as well. It is the
+    # lenient reading: a custom scalar is the server's own, and may write the
+    # number as a string where the spec's `Int` may not (which is why the
+    # pre-registered Int/String/Boolean/ID opt out with `cast: :itself`).
+    # Only the wire class itself — Coerce hands back the plain type, so a
+    # subclass would land in a prop it doesn't satisfy — and only where Coerce
+    # has a rule, leaving Hash and Array passing through.
+    def wire_cast
+      return unless wire_class?(@type) && (fn = COERCERS[@type])
+
+      ->(_type, expr) { "GraphWeaver::Coerce.#{fn}(#{expr}, #{@graphql_name.inspect})" }
+    end
+
+    # T::Boolean is the pair TrueClass/FalseClass, spelled as Sorbet types it
+    def wire_class?(name) = name == "T::Boolean" || WIRE_CLASSES.any? { |native| native.name == name }
+
     # Kernel's conversion functions are how a wire value becomes one of these
     # — BigDecimal defines neither .parse nor .load, but Kernel#BigDecimal has
     # read a decimal string all along. Only for a type the wire can't already
     # be: Kernel#String and Kernel#Array wrap a value rather than convert it.
     def kernel_cast
       return unless Kernel.private_method_defined?(@type.to_sym)
-      return if WIRE_CLASSES.any? { |native| native.name == @type }
+      return if wire_class?(@type)
 
       ->(type, expr) { "#{type}(#{expr})" }
     end
@@ -373,12 +424,15 @@ class GraphWeaver::Codegen
     # Pre-registered scalars — ordinary entries in the one registry, so a
     # later register_scalar overrides any of them.
     #
-    # The five the spec names stay pass-through: their Ruby classes (String,
-    # Integer) define neither .parse nor .load, so inference matches nothing
-    # and leaves them identity — which is exactly why we can name them with
-    # the real class constants. Float is the exception, and its rule lives in
-    # STDLIB with the others, so `register_scalar "Ratio", Float` reads the
-    # wire exactly as the built-in Float does.
+    # Four of the five the spec names stay pass-through coming back —
+    # `cast: :itself` — because the spec guarantees their JSON type, so
+    # checking it would cost a call on the commonest leaves in every response
+    # and refuse nothing a compliant server sends. (Going out is another
+    # matter: a Rails param is a String whatever the sig says, so the same
+    # scalars still coerce there.) A scalar an app registers as one of those
+    # classes is the server's own, and gets the rule in both directions.
+    # Float is the exception even coming back: JSON has one number type, so
+    # `1.0` arrives as `1` from graphql-js and from Go.
     #
     # The rest are names, not guesses: graphql-ruby ships all but DateTime as
     # its own scalars, and this library runs a graphql-ruby schema in-process.
@@ -388,11 +442,11 @@ class GraphWeaver::Codegen
     # away. Date and datetime are told apart by their Ruby type — a Date cast
     # to Time would invent a midnight the server never sent.
     def register_builtin_scalars!
-      register_scalar "ID", String
-      register_scalar "String", String
-      register_scalar "Int", Integer
+      register_scalar "ID", String, cast: :itself
+      register_scalar "String", String, cast: :itself
+      register_scalar "Int", Integer, cast: :itself
       register_scalar "Float", Float
-      register_scalar "Boolean", "T::Boolean"
+      register_scalar "Boolean", "T::Boolean", cast: :itself
       register_scalar "Date", Date
       register_scalar "ISO8601Date", Date
       register_scalar "ISO8601DateTime", Time