graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver/coerce.rb

@@ -0,0 +1,113 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module GraphWeaver
+  # Called by generated code — not semver'd for direct use.
+  #
+  # Turning a loose value into the Ruby type a generated kwarg promises.
+  #
+  # Generated `execute` sigs are `.checked(:never)`, so a `params[:first]`
+  # String reaches the body instead of being rejected by sorbet-runtime
+  # first — and this is what stands where that check used to: it converts
+  # what converts unambiguously and refuses the rest.
+  #
+  # The conversions raise plain Ruby errors (as Kernel#Integer does) and the
+  # caller brands them: `.variable` for an execute kwarg, InputStruct.coerce
+  # for an input-object field, Hints.field for a response leaf. One table in
+  # both directions — `Coerce.float` is also Float's cast from the wire.
+  module Coerce
+    # Kernel#Integer reads "010" as octal and "0x1f" as hex, and Kernel#Float
+    # takes "1_0" — Ruby literal syntax, not wire syntax, and a zero-padded
+    # form field is a real input that must not silently mean something else.
+    INTEGER = /\A[+-]?\d+\z/
+    NUMBER = /\A[+-]?\d+(\.\d+)?([eE][+-]?\d+)?\z/
+
+    class << self
+      def integer(value)
+        case value
+        when Integer then value
+        when Float then whole(value)
+        when String then INTEGER.match?(value.strip) ? Integer(value.strip, 10) : unparseable(value, "Int")
+        else refuse(value, "Int")
+        end
+      end
+
+      def float(value)
+        case value
+        when Float then value
+        when Integer then value.to_f
+        when String then NUMBER.match?(value.strip) ? Float(value.strip) : unparseable(value, "Float")
+        else refuse(value, "Float")
+        end
+      end
+
+      # Ruby has no Kernel#Boolean, and every string rule ("0", "off", "no")
+      # is somebody's convention — so refuse rather than pick one.
+      def boolean(value)
+        return value if value == true || value == false
+
+        refuse(value, "Boolean", "there is no one right reading of it — convert at the call site")
+      end
+
+      def string(value)
+        return value if value.is_a?(String)
+
+        refuse(value, "String")
+      end
+
+      # The GraphQL spec has ID serialize as a String but accept an integer
+      # input, which is `execute(id: user.id)` — the everyday Rails call.
+      # String gets no such licence: an Integer where a String belongs is
+      # more often a bug than a spelling.
+      def id(value)
+        case value
+        when String then value
+        when Integer then value.to_s
+        else refuse(value, "ID")
+        end
+      end
+
+      # Brands one variable's coercion failure with the variable and the
+      # operation: a cast complains about the value alone ("invalid date"),
+      # which locates nothing in an app that runs a hundred queries.
+      def variable(name, operation, value)
+        yield value
+      rescue GraphWeaver::InputError => e
+        raise GraphWeaver::InputError.new(
+          "#{at(name, operation)}: #{Internal::Redact.detail(name, e.message)}", field: name, struct: e.struct,
+        )
+      rescue StandardError => e
+        # a cast complains about the value without quoting it ("invalid date")
+        shown = value.inspect
+        got = " (got #{shown})" unless e.message.include?(shown)
+        raise GraphWeaver::InputError.new(
+          "#{at(name, operation)}: #{Internal::Redact.detail(name, "#{e.message}#{got}")}", field: name,
+        )
+      end
+
+      private
+
+      def at(name, operation) = operation ? "$#{name} of #{operation}" : "$#{name}"
+
+      def whole(value)
+        # Integer(2.5) is 2 — a silent loss where refusing costs nothing
+        return value.to_i if value.finite? && (value % 1).zero?
+
+        raise ArgumentError, "#{expected("Int")}, got #{value.inspect} — not a whole number"
+      end
+
+      def unparseable(value, scalar)
+        raise ArgumentError, "#{expected(scalar)}, got #{value.inspect}"
+      end
+
+      # ::TypeError — inside GraphWeaver, a bare TypeError is ours
+      def refuse(value, scalar, hint = nil)
+        raise ::TypeError, "#{expected(scalar)}, got #{value.inspect}#{" — #{hint}" if hint}"
+      end
+
+      def expected(scalar) = "expected #{%w[Int ID].include?(scalar) ? "an" : "a"} #{scalar}"
+    end
+  end
+end

data/lib/graph_weaver/errors.rb

@@ -12,7 +12,7 @@ module GraphWeaver
   # all. #message is the human-friendly side; #to_h is the machine side —
   # a JSON-ready Hash (string keys) for logging, agents, or surfacing
   # structured failures to users. One subclass per failure site —
-  # {TransportError} (never reached the server), {ServerError} (non-2xx),
+  # {TransportError} (no response came back), {ServerError} (non-2xx),
   # {QueryError} (GraphQL-level errors), {TypeError} (response wouldn't
   # cast), {InputError} (bad variables), {ValidationError} (build time),
   # {ConfigurationError} (setup judged against your schema) — each merging
@@ -25,7 +25,7 @@ module GraphWeaver
     sig { params(args: T.untyped).void }
     def initialize(*args)
       super
-      GraphWeaver.log(:warn) { "#{self.class.name}: #{message}" }
+      GraphWeaver::Internal::Log.log(:warn) { "#{self.class.name}: #{message}" }
     end
 
     sig { overridable.returns(T::Hash[String, T.untyped]) }
@@ -34,9 +34,11 @@ module GraphWeaver
     end
   end
 
-  # The request never reached the server: connection refused, DNS failure,
-  # TLS handshake, timeout. The original exception is preserved as #cause.
-  # Generally retriable.
+  # No response came back: connection refused, DNS failure, TLS handshake,
+  # timeout, a socket that died mid-body. The original exception is preserved
+  # as #cause. Retriable — though a *read* timeout says nothing about whether
+  # the server applied the request, which is why Retry gives a mutation one
+  # attempt.
   class TransportError < Error
     extend T::Sig
 
@@ -100,7 +102,23 @@ module GraphWeaver
       @body = body
       @headers = headers
       snippet = body.to_s.empty? ? "" : ": #{body.to_s[0, 500]}"
-      super("HTTP #{status}#{snippet}")
+      super("HTTP #{status}#{snippet}#{" — #{hint}" if hint}")
+    end
+
+    # What to do about this status, where the status says it. A redirect is
+    # not followed — replaying a POST, with its Authorization header, at a
+    # host the server named is not ours to decide — so the destination has to
+    # reach whoever configured the url.
+    REDIRECTS = [301, 302, 303, 307, 308].freeze
+
+    sig { returns(T.nilable(String)) }
+    def hint
+      if REDIRECTS.include?(status)
+        location = headers["location"]
+        "redirects are not followed#{" — point the client at #{location}" if location}"
+      elsif [401, 403].include?(status)
+        "the server rejected the credentials — check auth: (the token, and its scopes)"
+      end
     end
 
     # Seconds to wait per the server's Retry-After, which is either a
@@ -189,12 +207,32 @@ module GraphWeaver
       extensions["code"] || @error_type
     end
 
-    # Message shapes servers use when they reject the *shape* of a query
-    # (unknown field/type/argument). Heuristic by necessity: only Apollo
-    # sets a standard code (GRAPHQL_VALIDATION_FAILED); graphql-ruby and
-    # GitHub speak in messages.
+    # Codes a server sets when it rejects the *shape* of a query. Apollo has
+    # one flat code; graphql-ruby names the rule that fired, and it is the
+    # in-process client this library ships, so its drift-shaped rules are
+    # listed rather than guessed at from prose.
+    VALIDATION_CODES = T.let(%w[
+      GRAPHQL_VALIDATION_FAILED
+      undefinedField undefinedType undefinedDirective
+      argumentNotAccepted argumentType argumentLiteralsIncompatible
+      missingRequiredArguments missingRequiredInputObjectAttribute
+      cannotSpreadFragment fragmentOnNonCompositeType
+      variableMismatch variableRequiresValidType variableNotDefined
+      selectionMismatch invalidOneOfInputObject
+    ].to_set.freeze, T::Set[String])
+
+    # For servers that send no code at all. Variable coercion reports through
+    # the message in both dialects, and a required input field appearing is
+    # unambiguous here: a generated input struct enforces its own required
+    # fields, so the app cannot produce that error itself.
     VALIDATION_MESSAGE = T.let(
-      /doesn't exist|Cannot query field|Unknown (field|type|argument)|isn't defined|undefined (field|type)/i,
+      Regexp.union(
+        /doesn't exist/i, /Cannot query field/i, /Unknown (field|type|argument)/i,
+        /is ?n[o']t defined/i, /undefined (field|type)/i, /No such type/i,
+        /can't be spread inside/i, /is missing required arguments/i,
+        /doesn't accept argument/i, /Field is not defined on/i,
+        /was provided invalid value for .+ \(Expected value to not be null\)/i,
+      ),
       Regexp,
     )
 
@@ -203,7 +241,8 @@ module GraphWeaver
     # changed after generation.
     sig { returns(T::Boolean) }
     def validation?
-      code == "GRAPHQL_VALIDATION_FAILED" || VALIDATION_MESSAGE.match?(message)
+      # to_s: a nil code is never a member, and sorbet can't narrow a call
+      VALIDATION_CODES.include?(code.to_s) || VALIDATION_MESSAGE.match?(message)
     end
 
     # The codes servers use to say "you're going too fast". No standard
@@ -484,6 +523,10 @@ module GraphWeaver
     sig { returns(T.nilable(String)) }
     attr_reader :field
 
+    # The generated input struct class where generation produced one, and
+    # the GraphQL type name where it didn't — a federation representation
+    # builds a plain Hash, so an entity has only its name there. Branch on
+    # #to_h's "struct" instead, which is `to_s` either way.
     sig { returns(T.untyped) }
     attr_reader :struct
 
@@ -491,7 +534,8 @@ module GraphWeaver
     def initialize(message, field: nil, struct: nil)
       @field = field
       @struct = struct
-      super(message)
+      # the message often IS a sorbet prop error — drop its frame, as TypeError does
+      super(message.sub(TypeError::SORBET_CALLER, ""))
     end
 
     sig { override.returns(T::Hash[String, T.untyped]) }

data/lib/graph_weaver/federation.rb

@@ -4,7 +4,7 @@
 require "graphql"
 
 require_relative "schema_loader"
-require_relative "schemas"
+require_relative "internal/schemas"
 
 module GraphWeaver
   # Federation checks that need no network — the supergraph you committed,
@@ -17,7 +17,7 @@ module GraphWeaver
     # A committed supergraph is a snapshot of a composition. Change a
     # subgraph and skip the recompose and it quietly describes a graph that
     # no longer exists — the failure this catches, locally and before merge,
-    # where {SchemaLoader.stale?} needs the server and answers a different
+    # where {SchemaLoader.diff} needs the server and answers a different
     # question (has the *server* drifted from my dump).
     #
     # Both directions, because they mean opposite things:
@@ -39,7 +39,7 @@ module GraphWeaver
     # count.
     #
     # A supergraph is routinely only **partly local** — the rest served by
-    # another process, or answered with fabricated data ({Testing::Subgraphs}
+    # another process, or answered with fabricated data ({Internal::Subgraphs}
     # `=> :fake`). Neither can be compared against anything, so the report
     # names three states rather than two: checked, not here, and faked. A
     # clean result that didn't say what it couldn't see would be actively
@@ -49,6 +49,7 @@ module GraphWeaver
       # declares one — so a root can't tell subgraphs apart, and a schema
       # is recognized by the other types it defines.
       ROOTS = %w[Query Mutation Subscription].freeze
+      private_constant :ROOTS
 
       # { "Product.weight" => ["products"] } — the supergraph says these
       # subgraphs resolve it, and no schema of theirs here defines it
@@ -78,10 +79,11 @@ module GraphWeaver
       def initialize(supergraph: nil, subgraphs: nil, schemas: nil)
         source = (supergraph || GraphWeaver::SchemaLoader.locate_path).to_s
         @table = GraphWeaver::SchemaLoader.routing_table(source)
-        # SDL passed as content has no name to print
-        @source = source.include?("\n") ? "the supergraph" : source
-        @given = named(subgraphs)
-        @schemas = schemas || GraphWeaver::Schemas.loaded
+        # SDL passed as content has no name to print — asked the way the
+        # loader asks it, which a one-line supergraph doesn't fool
+        @source = GraphWeaver::SchemaLoader.sdl_content?(source) ? "the supergraph" : source
+        @given = @table.named_subgraphs(subgraphs)
+        @schemas = schemas || GraphWeaver::Internal::Schemas.loaded
         @stale = {}
         @uncomposed = {}
         @skipped = {}
@@ -129,20 +131,6 @@ module GraphWeaver
       STALE = "stale — the supergraph carries these, no schema here defines them (recompose):"
       UNCOMPOSED = "not composed in — a schema here defines these, the supergraph doesn't carry them:"
 
-      # `subgraphs:` with string keys, refusing a name this supergraph
-      # doesn't have — the same check Testing::Subgraphs makes, and for the
-      # same reason: a typo'd key would silently check nothing
-      def named(given)
-        map = (given || {}).to_h { |name, schema| [name.to_s, schema] }
-        unknown = map.keys - @table.subgraphs
-        if unknown.any?
-          raise GraphWeaver::ConfigurationError, "subgraphs: names #{unknown.join(", ")}, which " \
-            "this supergraph doesn't have (its subgraphs are #{@table.subgraphs.join(", ")})"
-        end
-
-        map
-      end
-
       def compare
         @table.subgraphs.each do |name|
           next unless (fitting = comparable(name))
@@ -194,7 +182,7 @@ module GraphWeaver
             next unless @table.owners(type_name, field_name).include?(name)
 
             coordinate = "#{type_name}.#{field_name}"
-            next if fitting.any? { |schema| GraphWeaver::Schemas.defines?(schema, coordinate) }
+            next if fitting.any? { |schema| GraphWeaver::Internal::Schemas.defines?(schema, coordinate) }
 
             (@stale[coordinate] ||= []) << name
           end

data/lib/graph_weaver/hints.rb

@@ -4,9 +4,12 @@
 require "sorbet-runtime"
 
 require_relative "errors"
+require_relative "internal"
 require_relative "inflect"
 
 module GraphWeaver
+  # Called by generated code — not semver'd for direct use.
+  #
   # Included in generated response structs. GraphQL's camelCase fields
   # become snake_case props, and reaching for the wire name is a classic
   # stumble — result.nameWithOwner instead of result.name_with_owner.
@@ -29,7 +32,7 @@ module GraphWeaver
         suggestion = if known.include?(prop)
           prop # a wire-cased key — the exact snake_case prop exists
         else
-          GraphWeaver.did_you_mean(known, prop)
+          GraphWeaver::Internal::Util.did_you_mean(known, prop)
         end
         suggestion ? "#{key} (did you mean '#{suggestion}'?)" : key
       end
@@ -40,6 +43,77 @@ module GraphWeaver
       )
     end
 
+    # Wraps one field's cast in generated from_h so a failure says which
+    # field. A scalar's cast is arbitrary Ruby — Float(), Date.iso8601, an
+    # app's Money.parse — and its complaint is about the value alone
+    # ("invalid date"), which locates nothing on a struct holding four
+    # dates. Sorbet's own prop errors already name the prop, so this is
+    # only on the leaves that cast.
+    def self.field(struct, key)
+      yield
+    rescue GraphWeaver::Error
+      raise # a nested struct already named its own field
+    rescue StandardError => e
+      raise GraphWeaver::TypeError.new(struct:, message: "#{key}: #{e.message}")
+    end
+
+    # A wire value the generated enum doesn't have — the response-side twin
+    # of InputStruct.enum. Almost always drift (the server grew a value since
+    # you generated) rather than a bad value, and T::Enum's own KeyError says
+    # neither that nor which values exist. Raised bare so the enclosing
+    # Hints.field brands it with the field.
+    def self.enum(type, value)
+      type.try_deserialize(value) || drifted!(type, value, type.values.map(&:serialize))
+    end
+
+    # the same, for an enum mapped onto an app-owned T::Enum, where the wire
+    # table rather than the type knows the accepted values
+    def self.mapped_enum(type, table, value)
+      table.fetch(value) { drifted!(type, value, table.keys) }
+    end
+
+    def self.drifted!(type, value, values)
+      raise KeyError, "#{value.inspect} is not a #{type} — expected one of: " \
+        "#{values.sort.join(", ")}; a value the server added since you generated " \
+        "needs a regenerate, or register_enum fallback: to absorb them"
+    end
+    private_class_method :drifted!
+
+    # The message for a response that wouldn't cast. sorbet names the prop
+    # and the value but not whose bug it is, and an ID the server sent as
+    # its raw integer primary key is the case that keeps happening — so
+    # say that GraphQL requires the quotes, and how to take it anyway.
+    def self.cast_message(struct, data, error)
+      message = error.message.sub(GraphWeaver::TypeError::SORBET_CALLER, "")
+      keys = unquoted_keys(struct, data)
+      return message if keys.empty?
+
+      "#{message} — the server sent #{keys.join(", ")} unquoted; GraphQL serializes ID and " \
+        "String as JSON strings, so that is the server being out of spec. To take it anyway, " \
+        'register the scalar loosely: GraphWeaver.register_scalar("ID", "T.untyped")'
+    end
+
+    # Response keys whose prop would take a String but whose value is
+    # another JSON scalar. Narrow on purpose: a prop that casts (a Date, an
+    # enum) legitimately arrives as some other type, so only the
+    # pass-through String ones say anything.
+    def self.unquoted_keys(struct, data)
+      return [] unless data.is_a?(Hash) && struct.respond_to?(:props)
+
+      props = struct.props
+      data.filter_map do |key, value|
+        next unless value.is_a?(Numeric) || value == true || value == false
+
+        prop = props[GraphWeaver::Inflect.underscore(key.to_s).to_sym]
+        next unless prop
+
+        # :type is a raw Class for a bare-class prop, a T::Types::Base otherwise
+        type = T::Utils.coerce(prop[:type])
+        key.inspect if type.valid?("") && !type.valid?(value)
+      end
+    end
+    private_class_method :unquoted_keys
+
     def method_missing(name, *args, &block)
       if args.empty? && (hint = prop_hint(name.to_s))
         raise NoMethodError, "undefined method '#{name}' for #{self.class} — #{hint}"
@@ -67,7 +141,7 @@ module GraphWeaver
       # a guess, not a mapping — spellcheck the (underscored) miss
       # against the props that exist, so typos in either casing land
       props = T.unsafe(self.class).props.keys.map(&:to_s)
-      suggestion = GraphWeaver.did_you_mean(props, prop)
+      suggestion = GraphWeaver::Internal::Util.did_you_mean(props, prop)
       "did you mean '#{suggestion}'?" if suggestion
     end
   end

data/lib/graph_weaver/in_process.rb

@@ -4,6 +4,7 @@
 require "json"
 
 require_relative "errors"
+require_relative "internal"
 require_relative "parsing"
 require_relative "transport"
 
@@ -45,10 +46,10 @@ class GraphWeaver::InProcess
   end
 
   def execute(query, variables: {}, operation_name: nil)
-    operation_name ||= GraphWeaver::Transport.operation_name(query)
+    operation_name ||= GraphWeaver::Internal::Wire.operation_name(query)
     payload = { url: nil, schema: @schema.to_s, operation: operation_name }
 
-    GraphWeaver.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
+    GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
       perform(query, variables, operation_name, payload)
     end
   end
@@ -58,15 +59,17 @@ class GraphWeaver::InProcess
   private def perform(query, variables, operation_name, payload)
     # same tag/truncation as the network transports, so one log reads the
     # same whichever side of the seam a query ran on
-    tag = GraphWeaver.logger && GraphWeaver::Transport.log_tag(operation_name)
+    tag = GraphWeaver.logger && GraphWeaver::Internal::Wire.log_tag(operation_name)
 
-    GraphWeaver.log(:debug) do
-      "in-process #{@schema} #{tag} variables=#{JSON.generate(variables)}\n" \
-        "#{GraphWeaver::Transport.truncate_for_log(query)}"
+    GraphWeaver::Internal::Log.log(:debug) do
+      "in-process #{@schema} #{tag} variables=#{JSON.generate(GraphWeaver::Internal::Log.filter_variables(variables))}\n" \
+        "#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
     end
 
-    result = GraphWeaver.log_timed(:debug, "in-process #{@schema} #{tag} completed") do
-      @schema.execute(query, variables:, operation_name:, context: @context)
+    result = GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{@schema} #{tag} completed") do
+      # a copy per query: graphql-ruby writes a resolver's `context[...] =`
+      # into the hash it is handed, and one client serves every request
+      @schema.execute(query, variables:, operation_name:, context: @context.dup)
     end
 
     # the same key the network transports set, so one instrumenter

data/lib/graph_weaver/inflect.rb

@@ -2,6 +2,8 @@
 # frozen_string_literal: true
 
 module GraphWeaver
+  # Called by generated code — not semver'd for direct use.
+  #
   # GraphQL names are plain camelCase/SCREAMING_SNAKE — no acronym edge
   # cases, so minimal inflection beats an activesupport dependency
   module Inflect

data/lib/graph_weaver/input_struct.rb

@@ -7,6 +7,8 @@ require_relative "errors"
 require_relative "hints"
 
 module GraphWeaver
+  # Called by generated code — not semver'd for direct use.
+  #
   # Runtime for generated input structs. Each struct declares its typed
   # consts plus a compact FIELDS table — (prop, wire name, requiredness,
   # serializer, coercer) per field, with the conversions emitted as
@@ -19,27 +21,82 @@ module GraphWeaver
 
     # serializer/coercer are code-as-data from the generated file; nil
     # means identity (the wire value passes through untouched)
-    Field = Struct.new(:prop, :wire, :required, :serializer, :coercer)
+    Field = Data.define(:prop, :wire, :required, :serializer, :coercer)
+
+    # An enum reaching the library as input — an execute kwarg or an input
+    # field — as the member or its wire value. Generated code calls these
+    # rather than T::Enum.deserialize / the wire table directly: both raise a
+    # bare KeyError naming an anonymous module and none of the values they
+    # would have taken.
+    def self.enum(type, value)
+      return value if value.is_a?(type)
+
+      type.try_deserialize(value) || invalid_enum!(type, value, type.values.map(&:serialize))
+    end
+
+    # the same, for an enum mapped onto an app-owned T::Enum (register_enum),
+    # where the wire table rather than the type knows the accepted values
+    def self.mapped_enum(type, table, value)
+      return value if value.is_a?(type)
+
+      table.fetch(value) { invalid_enum!(type, value, table.keys) }
+    end
+
+    # Names the input field a coercion refused — a scalar's coercer, an
+    # enum's, or a nested input's — since the complaint underneath is about
+    # the value alone. A nested error that already named a field keeps it:
+    # the innermost input is the one that actually held the bad value.
+    def self.field(struct, prop)
+      yield
+    rescue GraphWeaver::InputError => e
+      raise if e.field && !GraphWeaver::Internal::Redact.filtered?(prop)
+
+      raise GraphWeaver::InputError.new(
+        "#{prop}: #{GraphWeaver::Internal::Redact.detail(prop, e.message)}",
+        field: e.field || prop.to_s, struct: e.struct || struct,
+      )
+    rescue StandardError => e
+      raise GraphWeaver::InputError.new(
+        "#{prop}: #{GraphWeaver::Internal::Redact.detail(prop, e.message)}", field: prop.to_s, struct:,
+      )
+    end
+
+    # Raised bare, like Hints.drifted!: the enclosing .field or Coerce.variable
+    # knows the key, and so is the only layer that can decide whether this
+    # value may be named.
+    def self.invalid_enum!(type, value, values)
+      raise KeyError, "#{value.inspect} is not a valid #{type} — expected one of: #{values.sort.join(", ")}"
+    end
+    private_class_method :invalid_enum!
 
     def self.included(base)
       base.extend(ClassMethods)
     end
 
-    # the wire hash — optional fields left nil stay off the wire
+    # Which props the caller actually named, when we know. GraphQL tells an
+    # absent input field from an explicit null, and a Hash can say which it
+    # meant — so .coerce records it. A struct built with .new can't: every
+    # unset prop is nil either way, and nil there stays "leave it out".
+    attr_accessor :supplied
+
+    # the wire hash — an optional field stays off it unless the caller
+    # supplied the nil
     def serialize
+      given = supplied
       wire = self.class.const_get(:FIELDS).each_with_object({}) do |field, out|
         value = public_send(field.prop)
-        next if value.nil? && !field.required
+        next if value.nil? && !field.required && !given&.include?(field.prop)
 
         out[field.wire] = field.serializer && !value.nil? ? field.serializer.call(value) : value
       end
 
-      # @oneOf declares "exactly one of these", but every field is nullable, so
-      # nothing before here can enforce it — not the struct's types, not the
-      # server until the round trip
-      if wire.size != 1 && self.class.const_defined?(:ONE_OF, false)
+      # @oneOf declares "exactly one of these, and not null", but every field
+      # is nullable, so nothing before here can enforce it — not the struct's
+      # types, not the server until the round trip
+      if self.class.const_defined?(:ONE_OF, false) && (wire.size != 1 || wire.values.first.nil?)
+        supplied_names = wire.empty? ? "none" : wire.keys.sort.join(", ")
         raise GraphWeaver::InputError.new(
-          "#{self.class} is @oneOf — supply exactly one field, got #{wire.empty? ? "none" : wire.keys.sort.join(", ")}",
+          "#{self.class} is @oneOf — supply exactly one field, non-null, got #{supplied_names}",
           struct: self.class,
         )
       end
@@ -69,17 +126,63 @@ module GraphWeaver
         GraphWeaver::Hints.validate_keys!(self, value)
 
         fields = T.unsafe(self).const_get(:FIELDS)
-        T.unsafe(self).new(**fields.to_h do |field|
+        given = fields.select { |field| value.key?(field.prop) || value.key?(field.prop.to_s) }.map(&:prop)
+        supplied = fields.to_h do |field|
           raw = value.key?(field.prop) ? value[field.prop] : value[field.prop.to_s]
-          [field.prop, raw.nil? || field.coercer.nil? ? raw : field.coercer.call(raw)]
-        end)
+          next [field.prop, raw] if raw.nil? || field.coercer.nil?
+
+          # a coercer is arbitrary Ruby — Coerce.integer, Date.iso8601, a
+          # nested .coerce — and its complaint is about the value alone
+          [field.prop, GraphWeaver::InputStruct.field(self, field.prop) { field.coercer.call(raw) }]
+        end
+
+        # FIELDS knows which are required, so say what is missing — sorbet's
+        # own complaint describes the symptom ("Can't set .name to nil") and
+        # names only the first one it reaches
+        missing = fields.select { |field| field.required && supplied[field.prop].nil? }.map(&:prop)
+        unless missing.empty?
+          raise GraphWeaver::InputError.new(
+            "missing required key(s) for #{self}: #{missing.join(", ")}",
+            field: missing.join(", "), struct: self,
+          )
+        end
+
+        T.unsafe(self).new(**supplied).tap { |struct| struct.supplied = given }
       rescue GraphWeaver::InputError
         raise # already contextualized by a nested input / enum coercion
       rescue ::TypeError, ::ArgumentError, KeyError => e
         # a wrong-typed field, a missing required field, or an out-of-range
         # enum — surface one branded, structured error for a 422. (`::` so the
         # rescue catches Ruby's TypeError, not GraphWeaver::TypeError.)
-        raise GraphWeaver::InputError.new("invalid input for #{self}: #{e.message}", struct: self)
+        raise mistyped(supplied) ||
+          GraphWeaver::InputError.new("invalid input for #{self}: #{e.message}", struct: self)
+      end
+
+      private
+
+      # The prop whose value its own type refuses, reported the way every
+      # other input failure is. Only sorbet stands between a field with no
+      # coercer and the struct, and it names the prop and the value inside
+      # one free-text sentence — which reads as the library's own bug, and
+      # which no filter can see into.
+      def mistyped(supplied)
+        return unless supplied
+
+        T.unsafe(self).props.each do |prop, info|
+          value = supplied[prop]
+          # :type_object carries the nilable-ness the prop was declared with;
+          # :type is that unwrapped, which is the half worth naming — an
+          # absent optional field is nil and legal, and a missing required
+          # one was reported by name before we got here
+          next if T::Utils.coerce(info[:type_object]).valid?(value)
+
+          return GraphWeaver::InputError.new(
+            "#{prop}: expected #{T::Utils.coerce(info[:type])}, " \
+              "got #{GraphWeaver::Internal::Redact.detail(prop, value.inspect)}",
+            field: prop.to_s, struct: self,
+          )
+        end
+        nil
       end
     end
   end