graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/testing/cassette.rb

@@ -3,6 +3,7 @@
 
 require "fileutils"
 require "graphql"
+require "json"
 require "yaml"
 
 module GraphWeaver
@@ -19,7 +20,7 @@ module GraphWeaver
       def initialize(path:, query:, variables:, recorded:, size:)
         super([
           "no recording for this request in #{GraphWeaver::Internal::Util.relative(path)}",
-          "  variables: #{GraphWeaver::Internal::Log.filter_variables(Internal::RequestKey.normalize_variables(variables)).inspect}",
+          "  variables: #{JSON.generate(GraphWeaver::Internal::Log.filter_variables(Internal::RequestKey.normalize_variables(variables)))}",
           "  #{self.class.recorded_summary(recorded, size)}",
           "  query: #{Internal::RequestKey.summarize(query)}",
           "re-record it (GRAPHWEAVER_RECORD=1 with a client:), or delete the cassette to start over.",
@@ -30,7 +31,7 @@ module GraphWeaver
         return "no entry recorded for this query (#{size} in the cassette)" if recorded.empty?
 
         more = recorded.size > SHOWN ? " (+#{recorded.size - SHOWN} more)" : ""
-        shown = recorded.first(SHOWN).map { |set| GraphWeaver::Internal::Log.filter_variables(set).inspect }
+        shown = recorded.first(SHOWN).map { |set| JSON.generate(GraphWeaver::Internal::Log.filter_variables(set)) }
         "#{recorded.size} #{(recorded.size == 1) ? "entry" : "entries"} recorded for this query, " \
           "with variables #{shown.join(", ")}#{more}"
       end
@@ -85,7 +86,7 @@ module GraphWeaver
 
           ["#{GraphWeaver::Internal::Util.relative(path)}: #{stale.size} stale (#{counted.join(", ")})"] +
             stale.flat_map do |entry|
-              ["  #{entry.module_name} #{entry.variables.inspect}", "    #{entry.message}"]
+              ["  #{entry.module_name} #{JSON.generate(entry.variables)}", "    #{entry.message}"]
             end
         end
       end
@@ -114,11 +115,8 @@ module GraphWeaver
 
       def initialize(path)
         @path = Testing.cassette_path(path)
-        @entries = File.exist?(@path) ? YAML.safe_load_file(@path, aliases: true) : []
+        @entries = read_entries
         @flagged = []
-        # record is read-modify-write; two threads recording through one
-        # cassette (a parallel spec run) would each save a snapshot missing
-        # the other's entry — atomic_write keeps the file whole, not complete
         @lock = Mutex.new
       end
 
@@ -146,7 +144,13 @@ module GraphWeaver
         entry["response"] = response
 
         wanted = Internal::RequestKey.for(query, variables, operation_name)
-        @lock.synchronize do
+        # Recording rewrites the whole file, and parallel_tests points several
+        # processes at one cassette — so the read-modify-write happens under a
+        # lock every recorder shares, re-reading inside it. The snapshot taken
+        # at construction is already missing whatever another process recorded
+        # since, and saving it would throw those entries away.
+        locked do
+          @entries = read_entries
           @entries.reject! { |existing| Internal::RequestKey.for_entry(existing) == wanted }
           @entries << entry
           save
@@ -160,7 +164,7 @@ module GraphWeaver
       # and nothing else notices when that server's answers drift out of the
       # shape the structs were generated for: `verify`, `queries:check` and
       # `schema:diff` all ask about the local side. Without this the drift
-      # surfaces mid-spec as a `TypeError` naming a struct and a sorbet
+      # surfaces mid-spec as a `CastError` naming a struct and a sorbet
       # frame, with nothing pointing at the stale file.
       #
       # Matching is on the query text, which is the module that sent it — a
@@ -197,6 +201,26 @@ module GraphWeaver
 
       private
 
+      def read_entries = File.exist?(@path) ? YAML.safe_load_file(@path, aliases: true) : []
+
+      # Serialize a read-modify-write against every other recorder, in this
+      # process and any other. The Mutex is the threads; the flock is the
+      # processes. Both, because flock is held per open file, so one process's
+      # two threads would each take their own.
+      def locked
+        @lock.synchronize do
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+      end
+
+      # A sidecar, not the cassette itself: save renames a fresh file into
+      # place, so a lock held on the replaced inode guards nothing.
+      def lock_path = "#{@path}.lock"
+
       def save
         yaml = YAML.dump(@entries)
         FileUtils.mkdir_p(File.dirname(@path))
@@ -281,7 +305,7 @@ module GraphWeaver
 
       def initialize(schema:, seed: nil, values: nil)
         @schema = schema
-        @values = Internal::Values.new(seed:, values:)
+        @values = Internal::Values.new(seed:, values:, schema:)
       end
 
       # The whole response, not just `data`: an error message routinely

data/lib/graph_weaver/testing/endpoint.rb

@@ -0,0 +1,107 @@
+# typed: true
+# frozen_string_literal: true
+
+require "json"
+
+module GraphWeaver
+  module Testing
+    # A Rack app serving any client — the {Router}, a live schema class, a
+    # {FakeClient} — at a GraphQL endpoint, so a query crosses a real wire:
+    # serialized by your transport, posted, deserialized by `from_h`.
+    #
+    #      run GraphWeaver::Testing::Endpoint.new(router)
+    #
+    # In rspec that is the `graphql: :wire` tag, which mounts this behind
+    # your own transport's url (see graph_weaver/rspec). Anywhere else it is
+    # an ordinary Rack app — a rackup file, a Puma in a thread, WebMock's
+    # `to_rack`.
+    #
+    # It answers the way a router and graphql-ruby answer: a query the
+    # server can't parse or validate is a **200 carrying GraphQL errors**,
+    # not an HTTP failure. Only a request that isn't a GraphQL request at
+    # all — the wrong method, a body that isn't JSON — is a 400, and it says
+    # what it got.
+    #
+    # A client whose `context` is a **proc** is asked what this request's
+    # headers mean, per request: that is the identity-propagation seam, the
+    # one thing an in-process client can't test.
+    #
+    #      Router.new(supergraph:, context: ->(headers) { { current_user: User.find_by(token: headers["Authorization"]) } })
+    #
+    # Answering that proc means writing the client's context for the length
+    # of one dispatch, so the client is what resolves it: any client
+    # answering `with_request_context(headers) { }` gets the seam, which
+    # {InProcess} and {Router} take from {GraphWeaver::ContextSeam}. A client
+    # without it is served untouched, and concurrently.
+    class Endpoint
+      JSON_HEADERS = { "content-type" => "application/json" }.freeze
+      TEXT_HEADERS = { "content-type" => "text/plain" }.freeze
+      private_constant :JSON_HEADERS, :TEXT_HEADERS
+
+      # how much of an unservable body the 400 quotes back
+      EXCERPT = 200
+      private_constant :EXCERPT
+
+      def initialize(client)
+        @client = client
+      end
+
+      def call(env)
+        method = env["REQUEST_METHOD"]
+        return refuse("expected a POST of a GraphQL request, got #{method}") unless method == "POST"
+
+        body = env["rack.input"]&.read.to_s
+        request = begin
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          return refuse("expected a JSON GraphQL request body, got #{excerpt(body)} (#{e.message})")
+        end
+        unless request.is_a?(Hash) && request["query"].is_a?(String)
+          return refuse("expected a JSON GraphQL request body with a \"query\" string, got #{excerpt(body)}")
+        end
+
+        result = with_context(headers(env)) do
+          @client.execute(request["query"], variables: request["variables"] || {},
+            operation_name: request["operationName"])
+        end
+        [200, JSON_HEADERS, [JSON.generate(result)]]
+      end
+
+      # never leak the client's context (tokens, current_user)
+      def inspect = "#<#{self.class.name} client=#{@client.class}>"
+      alias to_s inspect
+
+      private
+
+      # A `context:` proc is answered from the request in hand, and the
+      # client's context is what gets written to answer it — so the client
+      # does it, under its own lock. This endpoint is built per request by
+      # `graphql: :wire`; a lock held here would guard nothing the next
+      # request shares.
+      def with_context(headers, &block)
+        return yield unless @client.respond_to?(:with_request_context)
+
+        @client.with_request_context(headers, &block)
+      end
+
+      # Rack spells a header HTTP_X_CALLER; the proc reads "X-Caller".
+      # Capitalization is reconstructed, not remembered — the CGI env
+      # dropped it — so a header sent as X-CALLER arrives here as X-Caller.
+      def headers(env)
+        env.each_with_object({}) do |(key, value), headers|
+          name = case key
+          when /\AHTTP_(.+)\z/ then Regexp.last_match(1)
+          when "CONTENT_TYPE", "CONTENT_LENGTH" then key
+          end
+          next unless name && value.is_a?(String)
+
+          headers[name.downcase.split("_").map(&:capitalize).join("-")] = value
+        end
+      end
+
+      def excerpt(body) = body.empty? ? "an empty body" : body[0, EXCERPT].inspect
+
+      def refuse(message) = [400, TEXT_HEADERS, [message]]
+    end
+  end
+end

data/lib/graph_weaver/testing/failure.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "net/http" # Net::ReadTimeout, the shape a real read timeout arrives in
 
 module GraphWeaver
   module Testing
@@ -10,13 +11,14 @@ module GraphWeaver
     # server that misbehaves on cue:
     #
     #      PersonQuery.execute(client: Failure.transport, id: "1")   # TransportError
+    #      PersonQuery.execute(client: Failure.timeout, id: "1")      # TransportError, read timeout
     #      PersonQuery.execute(client: Failure.server(status: 502), id: "1")
     #      PersonQuery.execute(client: Failure.throttled, id: "1")    # QueryError, code THROTTLED
     #      PersonQuery.execute(client: Failure.stale_schema, id: "1") # schema_stale? => true
     #
     # For type mismatches, corrupt the wire with a FakeClient override:
     #      FakeClient.new(schema:, overrides: { "Person.birthday" => 123 })
-    # casting then raises GraphWeaver::TypeError, exactly as a bad server
+    # casting then raises GraphWeaver::CastError, exactly as a bad server
     # payload would. For partial failures, see FakeClient's fail_at:.
     module Failure
       include Kernel # for sorbet
@@ -25,12 +27,31 @@ module GraphWeaver
       # the request never reaches the server — cause preserved, and the
       # message shaped as the bundled transports shape it
       def transport(message = "simulated network failure", cause: SocketError)
+        network_failure(cause, message)
+      end
+
+      # The request went out and no answer came back in time — net/http's own
+      # Net::ReadTimeout as #cause, so a spec says "it timed out" without
+      # naming net/http's classes. Retriable, but a read timeout says nothing
+      # about whether the server applied the request, which is why Retry gives
+      # a mutation one attempt.
+      def timeout(message = "simulated read timeout")
+        network_failure(Net::ReadTimeout, message)
+      end
+
+      # What Transport does with a network-level failure: a TransportError
+      # reading "Class: detail", the original preserved as #cause. The detail
+      # is passed rather than read off the exception — Net::ReadTimeout's own
+      # initialize takes the socket it gave up on, not a message, so a string
+      # handed to `raise` lands in quotes where the socket goes.
+      def network_failure(cause, message)
         FailureClient.new do
-          raise cause, message
+          raise cause
         rescue cause => e
-          raise GraphWeaver::TransportError, "#{e.class}: #{e.message}"
+          raise GraphWeaver::TransportError, "#{e.class}: #{message}"
         end
       end
+      private_class_method :network_failure
 
       # The server answered non-2xx. headers: is where the answer to "wait,
       # then" lives — ServerError#retry_after and #throttled? read it, so a
@@ -41,24 +62,60 @@ module GraphWeaver
         FailureClient.new { raise GraphWeaver::ServerError.new(status:, body:, headers:) }
       end
 
-      # top-level GraphQL errors: strings, or hashes with message/path/
-      # extensions; data: rides along for partial-failure envelopes
-      def graphql(*errors, data: nil, extensions: {})
-        normalized = errors.flatten.map do |error|
-          error.is_a?(String) ? { "message" => error } : JSON.parse(JSON.generate(error))
+      # The wire fields an error carries, beyond its message. `code:` is the
+      # sugar fail_at: already uses — extensions.code, the one every server
+      # states. Anything else is refused by name: a swallowed keyword leaves a
+      # simulated failure that doesn't simulate what the example asked for.
+      ERROR_FIELDS = %i[code extensions path locations].freeze
+      private_constant :ERROR_FIELDS
+
+      # Top-level GraphQL errors — a **whole-response** failure unless data:
+      # rides along. Each positional is a String (just the message) or a Hash
+      # in the wire error shape; the fields of ONE error may be named beside
+      # its message instead:
+      #
+      #      Failure.graphql("boom")
+      #      Failure.graphql("boom", code: "BAD_USER_INPUT", path: ["adopt"])
+      #      Failure.graphql("min must be at least 1", code: "BAD_USER_INPUT",
+      #        extensions: { "input" => { "kind" => "out_of_range", "min" => 1 } })
+      #      Failure.graphql({ message: "a", path: ["x"] }, { message: "b" }, data: { "x" => nil })
+      def graphql(*errors, data: nil, **fields)
+        unknown = fields.keys - ERROR_FIELDS
+        unless unknown.empty?
+          raise ArgumentError, "Failure.graphql: unknown keyword(s) #{unknown.join(", ")} — " \
+            "expected data:, or #{ERROR_FIELDS.join(", ")} to shape the error"
         end
 
-        response = { "errors" => normalized }
+        errors = errors.flatten
+        unless fields.empty? || errors.one?
+          raise ArgumentError, "Failure.graphql: #{fields.keys.join(", ")} shapes one error, " \
+            "got #{errors.size} — give each its own hash"
+        end
+
+        response = { "errors" => errors.map { |error| wire_error(error, fields) } }
         response["data"] = data if data
-        response["extensions"] = JSON.parse(JSON.generate(extensions)) unless extensions.empty?
         FailureClient.new { response }
       end
 
+      # a String is its message; a Hash is the wire error as written. The
+      # kwargs merge on top, so `code:` and `extensions:` compose.
+      def wire_error(error, fields)
+        wire = error.is_a?(String) ? { "message" => error } : JSON.parse(JSON.generate(error))
+        return wire if fields.empty?
+
+        extensions = JSON.parse(JSON.generate(fields[:extensions] || {}))
+        extensions["code"] = fields[:code].to_s if fields[:code]
+        wire.merge!(JSON.parse(JSON.generate(fields.slice(:path, :locations))))
+        wire["extensions"] = (wire["extensions"] || {}).merge(extensions) unless extensions.empty?
+        wire
+      end
+      private_class_method :wire_error
+
       def throttled
         # a code from the list #throttled? recognizes, not one spelled here —
         # a fake that doesn't trip the predicate it exists to exercise is worse
-        # than no fake. (array-wrapped so the hash can't parse as kwargs)
-        graphql([{ message: "rate limited", extensions: { code: GraphWeaver::GraphQLError::THROTTLE_CODES.first } }])
+        # than no fake
+        graphql("rate limited", code: GraphWeaver::GraphQLError::THROTTLE_CODES.first)
       end
 
       # A validation-shaped rejection — trips schema_stale? and its

data/lib/graph_weaver/testing/fake_client.rb

@@ -30,13 +30,15 @@ require_relative "../parsing"
 # takes one. Keys are checked against the schema, since a typo'd one would
 # pin nothing and leave the test green. (A pin with a wrong-typed value is
 # also the way to simulate a corrupt payload — casting raises
-# GraphWeaver::TypeError.)
+# GraphWeaver::CastError.)
 #
 #      FakeClient.new({ "Money" => "12.00", "Person" => build(:person),
 #                       "email" => -> { "test@example.com" } }, schema:)
 #
-# Options are lowercase words, so a key with a dot or a leading capital is
-# a pin wherever it is written — `overrides:` is the same hash by keyword,
+# Pins and options are the same keywords, told apart by a lookup: a key
+# this fake takes is an option, a key your schema knows is a pin, and a key
+# that is neither is refused naming both. So a lowercase type pins as
+# readily as a capitalized one. `overrides:` is the same hash by keyword,
 # and the leading one wins where both name a key.
 #
 # A pin covers a whole subtree as readily as a leaf, and **merges** rather
@@ -53,6 +55,11 @@ require_relative "../parsing"
 # other way round: the reader is the snake_cased field name, not the alias,
 # and a field it doesn't answer is fabricated.
 #
+# registry: whose register_scalar/register_enum calls the fabricated values
+# have to satisfy — GraphWeaver::Graph#registry, since a Money registered
+# for one graph is not a Money for the next. Left unsaid it is read back off
+# schema:, which is the answer for every app with one graph.
+#
 # requests: every execute, in order ({ query:, variables:, operation_name: })
 # — "did we send the right variables", and "did we call it at all".
 #
@@ -65,11 +72,16 @@ require_relative "../parsing"
 #      FakeClient.new(schema:, fail_at: "person.pets.name")
 #      FakeClient.new(schema:, fail_at: { path: "person.email", message: "hidden", code: "PRIVATE" })
 #
+# The path is response keys joined by dots, and a list index is a segment
+# of its own — "people.0.pets.1.name". State only the indices you mean;
+# the rest match any position, so "people.pets.name" fails the first
+# element the walk reaches.
+#
 # errors: appends verbatim top-level errors alongside the fake data.
 #
 # Type mismatches: corrupt: names fields ("Type.field") that should
 # arrive wire-corrupted — a wrong-typed value derived from the schema,
-# so casting raises GraphWeaver::TypeError. One spec checks the failure
+# so casting raises GraphWeaver::CastError. One spec checks the failure
 # path; every other spec gets working data:
 #
 #      FakeClient.new(schema:, corrupt: "Person.birthday")
@@ -81,6 +93,14 @@ require_relative "../parsing"
 #
 #      FakeClient.new(schema:, null_chance: 1.0)   # everything nullable, null
 #
+# list_size: how long an unbounded list is — an Integer exactly, a Range
+# randomized within it, and a Hash per list, keyed the way a pin is (a
+# "Type.field" coordinate or a bare field name) with "default" for the rest.
+# Every list the walk reaches reads this, so nested lists MULTIPLY under one
+# number: n rows each fabricate n tags. Naming the inner one flattens that.
+#
+#      FakeClient.new(schema:, list_size: { "Row.tags" => 3, default: 500 })
+#
 # seed: makes a run reproducible (also seeds faker). schema:, overrides:
 # and list_size: fall back to GraphWeaver::Testing.config — and the
 # config's schema falls back to the committed dump.
@@ -113,44 +133,49 @@ class GraphWeaver::Testing::FakeClient
   # misspelled key arrived as a bare "unknown keyword" from inside the
   # fabricator, naming neither the accepted options nor the one you meant.
   OPTIONS = {
-    schema: nil, overrides: {}, seed: nil, values: nil, list_size: nil,
+    schema: nil, registry: nil, overrides: {}, seed: nil, values: nil, list_size: nil,
     null_chance: nil, errors: nil, fail_at: nil, corrupt: nil,
   }.freeze
 
-  # One rule tells a pin from an option: options are lowercase words, and
-  # anything with a dot or a leading capital names something in the schema.
-  # Ruby 3 hands every braceless pair to **options — String keys included —
-  # so `FakeClient.new("Order.total" => "9", seed: 1)` arrives whole and is
-  # split here, as is a quoted symbol (`"Order.total":`) or a hash forwarded
-  # by a router's fake:.
-  PIN_KEY = /\A[A-Z]|\./
-
   # JSON's own types are already on the wire: at a leaf they skip the
-  # registry's serializer, and at a composite position (a Hash aside, which
-  # is response keys) they pin the field as written — nil is null, the rest
-  # is the corrupt payload the example asked for.
-  WIRE = [NilClass, TrueClass, FalseClass, Numeric, String, Symbol, Array, Hash].freeze
+  # registry's serializer (Values#wire), and at a composite position (a Hash
+  # aside, which is response keys) they pin the field as written — nil is
+  # null, the rest is the corrupt payload the example asked for.
+  WIRE = GraphWeaver::Internal::Values::WIRE
 
   # Methods every Ruby object answers aren't fields: a schema does have a
   # `hash` or a `count`, and a Struct answers both with plausible nonsense
   # where fabricating is right.
   RUBY_OWN = [BasicObject, Kernel, Object, Comparable, Enumerable, Struct, Data].freeze
-  private_constant :OPTIONS, :PIN_KEY, :WIRE, :RUBY_OWN
+
+  # The scalars the GraphQL spec serializes as JSON strings, whatever Ruby
+  # holds them.
+  STRING_SCALARS = %w[ID String].freeze
+  private_constant :OPTIONS, :WIRE, :RUBY_OWN, :STRING_SCALARS
 
   def initialize(pins = {}, **options)
-    pins, options = check_options!(pins, options)
     config = GraphWeaver::Testing.config
+    # resolved before the split, because the split asks the schema which keys
+    # are pins
     @schema = options[:schema] || config.schema || raise(GraphWeaver::Error,
       "no schema to fake against — set GraphWeaver::Testing.config.schema, pass schema:, " \
       "or commit a schema dump at #{GraphWeaver.schema_path}")
+    pins, options = check_options!(pins, options)
     # last wins, narrowest last: the suite's, then overrides:, then the pins
     # this fake was handed outright
     @overrides = [config.overrides, options[:overrides], pins]
       .map { |hash| hash.transform_keys(&:to_s) }.reduce(:merge)
     GraphWeaver::Internal::Overrides.validate!(@schema, @overrides)
+    # A graph whose schema is a file can't be matched back off the schema
+    # object — SchemaLoader builds a fresh anonymous class each load — so a
+    # caller holding the graph passes its registry rather than letting the
+    # lookup fall through to the default one.
+    @registry = options[:registry] || GraphWeaver::Internal::Util.registry_for(@schema)
     @values = GraphWeaver::Internal::Values.new(seed: options[:seed], values: options[:values],
-      pins: @overrides)
+      pins: @overrides, schema: @schema, registry: @registry)
     @list_size = options[:list_size] || config.list_size
+    @list_size = @list_size.transform_keys(&:to_s) if @list_size.is_a?(Hash)
+    GraphWeaver::Internal::Overrides.validate_list_size!(@schema, @list_size)
     @null_chance = options[:null_chance] || 0.0
     # NOT Array(): it would explode a bare Hash into key/value pairs
     @extra_errors = wrap(options[:errors]).map { |error| normalize_error(error) }
@@ -229,21 +254,39 @@ class GraphWeaver::Testing::FakeClient
 
   private
 
-  # A misspelled option pins nothing and leaves the example green — the same
-  # silent pass a typo'd override key is refused for.
+  # One rule tells a pin from an option, and it is a lookup rather than a
+  # guess at spelling: a key this fake takes is an option, a key the schema
+  # knows is a pin, and a key that is neither is a typo — refused naming both
+  # dictionaries, since only the author knows which they were reaching for. A
+  # misspelled option would otherwise pin nothing and leave the example green.
+  #
+  # Ruby 3 hands every braceless pair to **options — String keys included —
+  # so `FakeClient.new("Order.total" => "9", seed: 1)` arrives whole and is
+  # split here, as is a quoted symbol (`"Order.total":`) or a hash forwarded
+  # by a router's fake:. A leading positional hash is only ever pins, which
+  # is the spelling for a schema whose own vocabulary collides with an
+  # option name.
   def check_options!(pins, options)
-    options, keyed_pins = options.partition { |key, _| !PIN_KEY.match?(key.to_s) }.map(&:to_h)
-    # what was written as a leading hash wins: it is the one form that can
-    # only ever be a pin
-    pins = keyed_pins.merge(pins.to_h)
+    options, keyed_pins = options.partition { |key, _| OPTIONS.key?(key) }.map(&:to_h)
+    unknown = keyed_pins.keys.reject { |key| GraphWeaver::Internal::Overrides.schema_reference?(@schema, key) }
+    refuse_key!(unknown.first) if unknown.any?
 
-    unknown = options.keys - OPTIONS.keys
-    return [pins, OPTIONS.merge(options)] if unknown.empty?
+    [keyed_pins.merge(pins.to_h), OPTIONS.merge(options)]
+  end
 
-    suggestion = GraphWeaver::Internal::Util.did_you_mean(OPTIONS.keys.map(&:to_s), unknown.first.to_s)
-    hint = suggestion ? " — did you mean #{suggestion}:?" : "."
-    raise ArgumentError, "a fake doesn't take #{unknown.first}:#{hint} It takes " \
-      "#{OPTIONS.keys.map { |name| "#{name}:" }.join(", ")}"
+  def refuse_key!(key)
+    dictionary = OPTIONS.keys.map(&:to_s) + GraphWeaver::Internal::Overrides.pin_names(@schema)
+    suggestion = GraphWeaver::Internal::Util.did_you_mean(dictionary, key.to_s)
+    hint = if suggestion.nil?
+      "."
+    elsif OPTIONS.key?(suggestion.to_sym)
+      " — did you mean #{suggestion}:?"
+    else
+      " — did you mean the pin #{suggestion.inspect}?"
+    end
+    raise ArgumentError, "a fake doesn't take #{key}:#{hint} It takes " \
+      "#{OPTIONS.keys.map { |name| "#{name}:" }.join(", ")}, and pins keyed by anything in your " \
+      "schema — a type, a \"Type.field\" coordinate, or a field name"
   end
 
   def rng = @values.rng
@@ -298,7 +341,37 @@ class GraphWeaver::Testing::FakeClient
   end
 
   def normalize_fail_spec(spec)
-    spec.is_a?(String) ? { "path" => spec } : JSON.parse(JSON.generate(spec))
+    normalized = spec.is_a?(String) ? { "path" => spec } : JSON.parse(JSON.generate(spec))
+    normalized["chain"] = fail_chain(normalized["path"])
+    normalized
+  end
+
+  # A fail_at path as (field, indices) pairs: "people.0.pets.name" is people
+  # at index 0, then pets at any index, then name. An index you state has to
+  # match; one you leave out matches every position, so the plain
+  # "people.pets.name" fails the first element the walk reaches — which is
+  # what it has always done. Silently ignoring an index was the alternative,
+  # and a fail_at that never fires looks exactly like a passing test.
+  def fail_chain(path)
+    unless path.is_a?(String) && !path.empty?
+      raise ArgumentError, "fail_at: expected a response path like \"person.email\", got #{path.inspect}"
+    end
+
+    segments = path.split(".").map { |segment| segment.match?(/\A\d+\z/) ? Integer(segment) : segment }
+    if segments.first.is_a?(Integer)
+      raise ArgumentError, "fail_at: #{path.inspect} starts with a list index — a path starts with a field"
+    end
+
+    path_chain(segments)
+  end
+
+  # the shared fold: a fail_at path and the walk's own @path become the same
+  # shape, so one comparison serves both
+  def path_chain(segments)
+    segments.each_with_object([]) do |segment, chain|
+      field = chain.last
+      field && segment.is_a?(Integer) ? field.last << segment : chain << [segment, []]
+    end
   end
 
   # pins: the response keys an override pinned at this object, merged in as
@@ -433,16 +506,31 @@ class GraphWeaver::Testing::FakeClient
     case type.kind.name
     when "NON_NULL" then wire_value(type.of_type, value, coordinate)
     when "LIST"
-      value.is_a?(Array) ? value.map { |element| wire_value(type.of_type, element, coordinate) } : value
-    when "SCALAR"
-      return value if wire?(value)
-
-      GraphWeaver::Codegen.scalar(type.graphql_name, coordinate).serialize_value(value)
+      # whatever enumerates, not an Array alone: a has_many is an
+      # ActiveRecord CollectionProxy, and reading one straight onto the wire
+      # failed the cast as "the server sent a
+      # Order::ActiveRecord_Associations_CollectionProxy". A Hash is the one
+      # thing that enumerates and isn't a list.
+      return value if value.is_a?(Hash) || !value.is_a?(Enumerable)
+
+      value.map { |element| wire_value(type.of_type, element, coordinate) }
+    when "SCALAR" then scalar_wire(type.graphql_name, value, coordinate)
     when "ENUM" then value.is_a?(T::Enum) ? value.serialize : value
     else value # a composite: pinned_object reads it, one level down
     end
   end
 
+  # ID and String are JSON strings on every real wire, whatever Ruby type the
+  # object's column holds — an Integer primary key read straight through
+  # failed the cast with the advice for a server that sends ids unquoted,
+  # which is advice about a server that isn't there.
+  def scalar_wire(name, value, coordinate)
+    wired = @values.wire(name, value, coordinate)
+    return wired unless STRING_SCALARS.include?(name) && !wired.nil? && !wired.is_a?(String)
+
+    wired.to_s
+  end
+
   # The concrete type a pinned object is fabricated as. At a union or
   # interface the pin has to say: picking a member at random would fabricate
   # a shape the pinned keys don't fit, in whichever fraction of runs the
@@ -506,24 +594,55 @@ class GraphWeaver::Testing::FakeClient
     end
   end
 
-  # first untriggered fail_at spec whose field chain (indices stripped)
-  # matches where we are
+  # first untriggered fail_at spec whose chain matches where we are
   def matching_failure
-    chain = @path.reject { |segment| segment.is_a?(Integer) }.join(".")
-    @fail_at.find { |spec| !spec["triggered"] && spec["path"] == chain }
+    here = path_chain(@path)
+    @fail_at.find { |spec| !spec["triggered"] && at?(spec["chain"], here) }
+  end
+
+  def at?(chain, here)
+    return false unless chain.size == here.size
+
+    chain.zip(here).all? do |(field, indices), (at, positions)|
+      field == at && indices.each_with_index.all? { |index, depth| positions[depth] == index }
+    end
   end
 
   # honor pagination-ish arg semantics: first/last/limit caps the fabricated
   # list length, whether it arrives as a literal or as a variable
-  def list_length(node)
+  def list_length(node, coordinate)
     argument = node.arguments.find { |arg| %w[first last limit].include?(arg.name) }
     capped = argument && argument_value(argument)
     # Array.new(-1) is "negative array size" out of the fabricator's guts; a
     # cap below zero asks for nothing, which is what a page of none is
     return [capped, 0].max if capped.is_a?(Integer)
+    return 0 if errors_list?(node.name)
 
+    size = list_size_for(coordinate, node.name)
     # an Integer list_size means exactly that many; a Range randomizes within it
-    @list_size.is_a?(Range) ? rng.rand(@list_size) : @list_size
+    size.is_a?(Range) ? rng.rand(size) : size
+  end
+
+  # A list field whose name ends in `errors` fabricates empty. The Relay and
+  # Shopify payload convention — `placeOrder { order userErrors }` — otherwise
+  # comes back with a fabricated order AND a fabricated failure, which is a
+  # response no server can send, so the natural happy-path assertion is flaky
+  # until it is pinned. Pin it to fabricate the failure path.
+  def errors_list?(name) = name.downcase.end_with?("errors")
+
+  # How long an unbounded list is. A Hash says it per list, read most
+  # specific first like a pin — which is what keeps nested lists from
+  # multiplying: every list the walk reaches re-reads this, so one number
+  # for all of them is n rows x n tags.
+  def list_size_for(coordinate, name)
+    return @list_size unless @list_size.is_a?(Hash)
+
+    @list_size.fetch(coordinate) do
+      @list_size.fetch(name) do
+        @list_size.fetch(GraphWeaver::Internal::Overrides::LIST_SIZE_DEFAULT,
+          GraphWeaver::Testing::Config::DEFAULT_LIST_SIZE)
+      end
+    end
   end
 
   def type_value(type, node, selections, coordinate: nil, non_null: false)
@@ -536,7 +655,7 @@ class GraphWeaver::Testing::FakeClient
 
     case type.kind.name
     when "LIST"
-      elements = Array.new(list_length(node)) do |index|
+      elements = Array.new(list_length(node, coordinate)) do |index|
         @path.push(index)
         element = type_value(type.of_type, node, selections, coordinate:)
         @path.pop