graph_weaver 0.7.5 → 0.7.6

data/lib/graph_weaver/codegen.rb

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

data/lib/graph_weaver/graph.rb

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

data/lib/graph_weaver/in_process.rb

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

data/lib/graph_weaver/input_struct.rb

@@ -24,7 +24,13 @@ module GraphWeaver
     # is the schema's name for the slot ("PetFilter.species") and type its
     # spelling of what goes there ("[Float!]!"), so a refusal can say where
     # it happened, and in whose vocabulary, without reflecting at runtime.
-    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate, :type)
+    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate, :type) do
+      # How a message names this field. The prop is what you type in Ruby, so
+      # it leads; the wire name is what you grep the .graphql for, so it comes
+      # along where the two differ. Nothing structured reads this — #path,
+      # #field and #coordinate are the schema's spelling either way.
+      def label = (wire == prop.to_s) ? prop.to_s : "#{prop} (#{wire})"
+    end
 
     # 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
@@ -70,6 +76,25 @@ module GraphWeaver
       table.fetch(value) { invalid_enum!(type, value, table.keys) }
     end
 
+    # The way back out: a member => the wire value it sends as. Generation
+    # makes that table total, so a miss is a T::Enum that grew a member since
+    # — and Hash#fetch's KeyError named the anonymous table rather than the
+    # member or anything it could have sent. Also the result side's `as_json`,
+    # where nothing wraps a raised KeyError into a GraphWeaver error at all.
+    def self.enum_wire(graphql_name, table, member)
+      table.fetch(member) do
+        raise GraphWeaver::Internal::Refusal.brand(
+          GraphWeaver::Error.new(
+            # a T::Enum member inspects as #<Type::Name>
+            "#{member.inspect[2..-2]} maps onto no #{graphql_name} value, so there is nothing to " \
+            "send for it — expected one of: #{table.values.sort.join(", ")}; a member added since " \
+            "you generated needs a regenerate",
+          ),
+          :not_a_member, members: table.values.sort,
+        )
+      end
+    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 its
@@ -83,7 +108,7 @@ module GraphWeaver
       raise e.within(field.wire, prop:) if e.field && !redact.filtered?(prop)
 
       raise GraphWeaver::InputError.new(
-        "#{prop}: #{redact.detail(prop, e.message)}",
+        "#{field.label}: #{redact.detail(prop, e.message)}",
         kind: e.kind, path: [field.wire, *e.path], coordinate: e.coordinate || field.coordinate,
         # #value is the value AT #path: this layer owns it only when nothing
         # inner named a field (so a missing one stays valueless, as it is)
@@ -93,7 +118,7 @@ module GraphWeaver
     rescue StandardError => e
       redact = GraphWeaver::Internal::Redact
       raise GraphWeaver::InputError.new(
-        "#{prop}: #{redact.detail(prop, e.message)}",
+        "#{field.label}: #{redact.detail(prop, e.message)}",
         kind: GraphWeaver::Internal::Refusal.kind_of(e), path: [field.wire],
         coordinate: field.coordinate, value: redact.value(prop, raw),
         details: GraphWeaver::Internal::Refusal.details_of(e), struct:,
@@ -284,7 +309,7 @@ module GraphWeaver
           field = T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }
           type = field&.type || T::Utils.coerce(info[:type]).to_s
           return GraphWeaver::InputError.new(
-            "#{prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
+            "#{field&.label || prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
             kind: :type_mismatch, path: [prop.to_s], coordinate: field&.coordinate,
             value: GraphWeaver::Internal::Redact.value(prop, value),
             details: { type: }, struct: self,

data/lib/graph_weaver/internal/overrides.rb

@@ -10,9 +10,9 @@ module GraphWeaver
     # 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
-      # The key a Hash `list_size:` says its fallback under — every list it
-      # doesn't name.
-      LIST_SIZE_DEFAULT = "default"
+      # The key a per-field Hash (`list_size:`, `null_chance:`) says its
+      # fallback under — everything it doesn't name.
+      DEFAULT_KEY = "default"
 
       class << self
         # A pin key names something in the schema: a type ("Money",
@@ -51,16 +51,22 @@ module GraphWeaver
         # minus the bare type name: a type says nothing about how long any one
         # of its fields is.
         def validate_list_size!(schema, list_size)
-          return unless list_size.is_a?(Hash)
-
-          list_size.each do |key, value|
-            unless value.is_a?(Integer) || value.is_a?(Range)
-              raise GraphWeaver::Error, "list_size: #{key.to_s.inspect} must be an Integer or a " \
-                "Range — how long an unbounded list is — got #{value.inspect}"
-            end
-            next if key.to_s == LIST_SIZE_DEFAULT
+          reaches = ->(type) { type.list? }
+          validate_per_field!(schema, list_size, "list_size",
+            reaches:, unreached: "is not a list and has no length to set — name a list field") do |value|
+            "an Integer or a Range of them, neither negative — how long an unbounded list is" unless
+              length?(value)
+          end
+        end
 
-            validate_field_key!(schema, key.to_s, "list_size: key")
+        # A Hash `null_chance:` is keyed the same way, one nullable field at a
+        # time.
+        def validate_null_chance!(schema, null_chance)
+          reaches = method(:nullable_anywhere?)
+          validate_per_field!(schema, null_chance, "null_chance",
+            reaches:, unreached: "can never come back null — name a nullable field") do |value|
+            "a number from 0 to 1 — how often a nullable field comes back null" unless
+              value.is_a?(Numeric) && (0..1).cover?(value)
           end
         end
 
@@ -75,6 +81,83 @@ module GraphWeaver
 
         private
 
+        # The two shapes both per-field options take: one value for every
+        # field, or a Hash keyed by field — a "Type.field" coordinate or a
+        # bare field name — with DEFAULT_KEY for the rest. The block says
+        # what a value has to be, in the words the refusal uses, and says it
+        # of both shapes: a plain `null_chance: 7` used to sail through and
+        # null everything, a plain `list_size: "3"` to die inside the
+        # fabricator.
+        def validate_per_field!(schema, option, name, reaches:, unreached:)
+          unless option.is_a?(Hash)
+            refuse_value!(name, nil, option, yield(option))
+            return
+          end
+
+          option.each do |key, value|
+            refuse_value!(name, key, value, yield(value))
+            next if key.to_s == DEFAULT_KEY
+
+            label = "#{name}: key"
+            validate_field_key!(schema, key.to_s, label)
+            reaches!(schema, key.to_s, label, reaches, unreached)
+          end
+        end
+
+        # A key naming a field the option can never reach is inert, which is
+        # the silent green every other key check exists to stop: the
+        # fabricator asks `null_chance` at nullable positions only and
+        # `list_size` at lists only, so it never looks this key up.
+        def reaches!(schema, key, label, reaches, unreached)
+          types = field_types(schema, key)
+          return if types.empty? || types.any? { |type| reaches.call(type) }
+
+          spelled = types.map(&:to_type_signature).uniq.sort.join(", ")
+          raise GraphWeaver::Error, "#{label} #{key.inspect} (#{spelled}) #{unreached}, " \
+            "or drop the key"
+        end
+
+        # Every field a per-field key names: the one a coordinate points at,
+        # or every field of that name in the schema for a bare one.
+        def field_types(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?("__")
+          return [schema.get_type(type_name).fields.fetch(field_name).type] if field_name
+
+          schema.types.each_value.filter_map do |type|
+            type.fields[type_name]&.type if type.respond_to?(:fields)
+          end
+        end
+
+        # Whether null_chance has a position in this type to reach. The outer
+        # wrapper isn't the whole answer: `[Pet]!` is non-null and its ELEMENTS
+        # are nullable, which is where the fabricator puts the nulls.
+        def nullable_anywhere?(type)
+          return true unless type.non_null?
+
+          inner = type.of_type
+          inner.list? && nullable_anywhere?(inner.of_type)
+        end
+
+        def refuse_value!(name, key, value, wanted)
+          return unless wanted
+
+          raise GraphWeaver::Error, "#{name}:#{" #{key.to_s.inspect}" if key} must be #{wanted} — " \
+            "got #{value.inspect}"
+        end
+
+        # A length is a count the fabricator can build an Array of: Array.new(-1)
+        # is "negative array size" out of its guts, and a Range the seeded rng
+        # can't sample (endless, or beginless) is worse.
+        def length?(value)
+          case value
+          when Integer then !value.negative?
+          when Range then [value.begin, value.end].all? { |edge| edge.is_a?(Integer) && !edge.negative? }
+          else false
+          end
+        end
+
         # 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)
@@ -113,20 +196,49 @@ module GraphWeaver
             known = field_names(schema)
             return if known.include?(type_name)
 
+            # a type name reads like a reasonable key here — `null_chance: {
+            # "Person" => 1.0 }` looks like "null the whole subtree" — and
+            # did_you_mean sent it to the nearest FIELD ('person') instead of
+            # saying these options are keyed by field
+            named = schema.get_type(type_name)
+            type_key!(label, key, named) if named
             bad!(label, key, "matches no field in this schema", known, type_name)
           end
 
           coordinate!(schema, label, key, type_name, field_name)
         end
 
+        def type_key!(label, key, type)
+          reach = type.respond_to?(:fields) ? "#{type.graphql_name}.<field>".inspect : "a \"Type.field\" coordinate"
+          raise GraphWeaver::Error, "#{label} #{key.inspect} names " \
+            "#{type.kind.name.downcase.tr("_", " ")} #{type.graphql_name}, and a key here names " \
+            "one field — #{reach}, or a bare field name"
+        end
+
         def coordinate!(schema, label, key, type_name, field_name)
           type = schema.get_type(type_name)
           unless type.respond_to?(:fields)
             bad!(label, key, "names no object type in this schema", schema.types.keys, type_name)
           end
-          return if type.fields.key?(field_name)
+          unless type.fields.key?(field_name)
+            bad!(label, key, "is not a field of #{type_name}", type.fields.keys, field_name)
+          end
+
+          concrete!(schema, label, key, type, field_name)
+        end
+
+        # The abstract-type refusal, in the coordinate form. An interface
+        # declares the field, so "Named.name" reads as a key that must work
+        # — and it matches nothing: the walk picks a member before it builds
+        # a coordinate, so every key it looks up is "Person.name".
+        def concrete!(schema, label, key, type, field_name)
+          return unless type.kind.abstract?
 
-          bad!(label, key, "is not a field of #{type_name}", type.fields.keys, field_name)
+          members = schema.possible_types(type)
+            .map { |member| "#{member.graphql_name}.#{field_name}".inspect }.sort
+          raise GraphWeaver::Error, "#{label} #{key.inspect} names #{type.kind.name.downcase} " \
+            "#{type.graphql_name}, and a fake only ever holds a concrete type: name the " \
+            "concrete type — #{members.join(", ")}"
         end
 
         # A type pin says what every value of that type is, and the fake only

data/lib/graph_weaver/internal/test_clients.rb

@@ -97,15 +97,20 @@ module GraphWeaver
           # :wire takes no client slot: it serves the resolvers at the
           # endpoint each client already posts to — the transport you ship,
           # running unchanged, is the whole point
-          return if @mode == :wire
+          return if @mode == :wire && GraphWeaver.graphs.all?(&:client_url)
           # :live is the app's own clients, untouched — so with nothing
           # standing in there is nothing to look up
           return if @mode == :live && !built?
 
+          graph = graph_for!(mod)
+          # a graph whose client posts to no url has no wire to be served at,
+          # so :wire serves it here instead — the same pick, one hop shorter
+          return if @mode == :wire && graph&.client_url
+
           # a helper's entry wins whatever the example's mode is, and :live
           # builds nothing of its own, so an untagged example's other graphs
           # still resolve their own clients
-          standin(graph_for!(mod))
+          standin(graph)
         end
 
         # The stand-in `graph`'s modules run against under the installed mode,
@@ -165,12 +170,29 @@ module GraphWeaver
           return :in_process if config.schema_class?(graph)
           return :fake if config.schema || graph&.named_schema?
 
-          raise GraphWeaver::Error, ":wire serves your schema at the endpoint your client posts " \
-            "to, and #{graph&.name ? "graph #{graph.name.inspect}" : "this app"} has none to " \
-            "serve — no live GraphQL::Schema class, no composed supergraph, and no type " \
+          raise GraphWeaver::Error, nothing_to_serve(graph)
+        end
+
+        # Two graphs are in different states here, and the served one's
+        # sentences are all false for the other: a graph whose client posts
+        # nowhere has no endpoint to stub, no stub of ours to introspect, and
+        # no url to refresh a dump from — what it is missing is a schema.
+        def nothing_to_serve(graph)
+          missing = "no live GraphQL::Schema class, no composed supergraph, and no type " \
             "information (nothing at #{GraphWeaver.schema_path}, and " \
-            "GraphWeaver::Testing.config.schema is unset). Your client's own schema can't stand " \
-            "in here: reading it introspects the endpoint :wire has stubbed. Commit a dump " \
+            "GraphWeaver::Testing.config.schema is unset)"
+          if graph&.name && !graph.client_url
+            return ":wire has no endpoint for graph #{graph.name.inspect} — its client posts to " \
+              "none, so its modules run above the wire, against the most faithful stand-in the " \
+              "graph has. It has #{missing}. Name one where the graph is declared: " \
+              "GraphWeaver.graph(#{graph.name.inspect}) { schema -> { MySchema } }, or a dump " \
+              "(schema \"schema.graphql\"). Or tag the example graphql: :live."
+          end
+
+          ":wire serves your schema at the endpoint your client posts to, and " \
+            "#{graph&.name ? "graph #{graph.name.inspect}" : "this app"} has none to serve — " \
+            "#{missing}. Your client's own schema can't stand in here: reading it introspects " \
+            "the endpoint :wire has stubbed. Commit a dump " \
             "(rake graph_weaver:schema:refresh URL=…), or tag the example graphql: :live."
         end