graph_weaver 0.5.1 → 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
@@ -505,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
 
@@ -512,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
@@ -82,7 +83,7 @@ module GraphWeaver
         # 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::Schemas.loaded
+        @schemas = schemas || GraphWeaver::Internal::Schemas.loaded
         @stale = {}
         @uncomposed = {}
         @skipped = {}
@@ -181,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

data/lib/graph_weaver/internal/overrides.rb

@@ -0,0 +1,101 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "../internal"
+
+module GraphWeaver
+  module Internal
+    # What a pin is: the key it may be written under, and how its value is
+    # read. Both doors need the answer — Testing.configure checks the
+    # suite-wide ones while the block that set them is still on the stack,
+    # and a fake built with its own checks them then.
+    module Overrides
+      class << self
+        # A pin key names something in the schema: a type ("Money",
+        # "Person"), a "Type.field" coordinate, or a bare field name
+        # matching that field on any type. Anything else is a typo that
+        # would silently fabricate random data instead of pinning a value.
+        def validate!(schema, overrides)
+          overrides.each do |key, value|
+            validate_arity!(key, value)
+            validate_key!(schema, key.to_s)
+          end
+        end
+
+        # A pin that's a proc is handed the seeded Random when it takes one
+        # and called bare when it doesn't, so a varying pin still reproduces
+        # under `rspec --seed`.
+        def resolve(value, rng)
+          return value unless value.is_a?(Proc)
+
+          value.arity.zero? ? value.call : value.call(rng)
+        end
+
+        private
+
+        # A proc taking anything else can't be called at fabrication time,
+        # and the ArgumentError it would raise there names no pin.
+        def validate_arity!(key, value)
+          return unless value.is_a?(Proc) && value.arity > 1
+
+          raise GraphWeaver::Error, "the pin for #{key.inspect} takes no arguments, or one — the " \
+            "seeded Random (-> (rng) { ... }); this one takes #{value.arity}"
+        end
+
+        def validate_key!(schema, key)
+          type_name, field_name = key.split(".", 2)
+          # introspection fields (__typename) are real but absent from #fields
+          return if (field_name || type_name).start_with?("__")
+
+          if field_name.nil?
+            return if (type = schema.get_type(type_name)) && pinnable!(schema, key, type)
+
+            known = field_names(schema)
+            return if known.include?(type_name)
+
+            # a leading capital names a type, as it does wherever a pin is written
+            dictionary = type_name.match?(/\A[A-Z]/) ? schema.types.keys : known
+            bad!(key, "matches no type or field in this schema", dictionary, type_name)
+          end
+
+          type = schema.get_type(type_name)
+          unless type.respond_to?(:fields)
+            bad!(key, "names no object type in this schema", schema.types.keys, type_name)
+          end
+          return if type.fields.key?(field_name)
+
+          bad!(key, "is not a field of #{type_name}", type.fields.keys, field_name)
+        end
+
+        # A type pin says what every value of that type is, and the fake only
+        # ever holds a concrete one: at an interface or union the walk has
+        # already picked a member, so a pin keyed on the abstract name would
+        # match nothing and leave the example green.
+        def pinnable!(schema, key, type)
+          return true if %w[SCALAR ENUM OBJECT].include?(type.kind.name)
+
+          advice = if type.kind.abstract?
+            members = schema.possible_types(type).map { |member| member.graphql_name.inspect }.sort
+            "pin the concrete type — #{members.join(", ")}"
+          else
+            "only output types are fabricated"
+          end
+          raise GraphWeaver::Error, "override key #{key.inspect} names #{type.kind.name.downcase.tr("_", " ")} " \
+            "#{type.graphql_name}, and a pin fabricates a scalar, enum or object: #{advice}"
+        end
+
+        def bad!(key, problem, dictionary, term)
+          suggestion = Util.did_you_mean(dictionary, term)
+          hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
+          raise GraphWeaver::Error, "override key #{key.inspect} #{problem}#{hint}"
+        end
+
+        # Every output field name in the schema — walked only when a bare key
+        # asks for it.
+        def field_names(schema)
+          schema.types.each_value.flat_map { |type| type.respond_to?(:fields) ? type.fields.keys : [] }.uniq
+        end
+      end
+    end
+  end
+end