graph_weaver 0.7.5 → 0.7.6

data/lib/graph_weaver/internal/unused.rb

@@ -26,10 +26,17 @@ module GraphWeaver
       # call that names none of them. Caught where the sink line carries the
       # module's own name, or a local a line above assigned from it.
       SINKS = /\b(?:to_h|to_json|as_json|serialize|deconstruct_keys)\b|render\s+json:/
-      # `result = PersonQuery.execute!(...)` — the local a response lands in.
+      # `result = PersonQuery.execute!(...)` — the name a response lands in.
       # Following one is what lets the sink be on the NEXT line, which is how
-      # anyone actually writes a controller. Excludes == and =~.
-      ASSIGN = /\b([a-z_]\w*)\s*=[^=~]/
+      # anyone actually writes a controller. The `@` is part of the capture:
+      # it is what says the name outlives the method. Excludes == and =~.
+      ASSIGN = /(@?\b[a-z_]\w*)\s*=[^=~]/
+      # Where a plain local stops standing for the module it was assigned
+      # from: the next method is a new scope, and a block param there that
+      # happens to share the name holds someone else's value. An ivar crosses
+      # it — `before_action` loading `@result` for the action to render is
+      # the shape every Rails controller has.
+      SCOPE = /^[ \t]*def\s/
       # A graphql-ruby TYPE class NAMES every field the server offers, as
       # `field :sku` and as a resolver method — which is the server answering,
       # not this app reading a prop back. Without this an app that serves the
@@ -189,6 +196,7 @@ module GraphWeaver
             # `result = Q.execute!(...)`, then `render json: result.person`.
             locals = Hash.new { |hash, key| hash[key] = [] }
             body.each_line.with_index(1) do |line, number|
+              locals.each_value { |names| names.select! { |n| n.start_with?("@") } } if SCOPE.match?(line)
               candidates.each do |name, base|
                 locals[name] << Regexp.last_match(1) if line.include?(base) && ASSIGN.match(line)
               end
@@ -197,7 +205,7 @@ module GraphWeaver
               candidates.each do |name, base|
                 # the line naming the module is the better evidence; the local
                 # is what it falls back to
-                via = locals[name].find { |local| line.match?(/\b#{Regexp.escape(local)}\b/) } \
+                via = locals[name].find { |local| line.match?(/(?<![\w@])#{Regexp.escape(local)}\b/) } \
                   unless line.include?(base)
                 next unless via || line.include?(base)
 
@@ -221,20 +229,31 @@ module GraphWeaver
             result = Object.const_get(name)
             next [] unless result.const_defined?(:Result, false)
 
-            words = source.scan(/[A-Za-z_]\w*/).uniq
+            keys = response_keys(GraphQL.parse(source).definitions)
             props(result.const_get(:Result, false))
-              .map { |struct, prop| Selection.new(path, name, struct, prop, wire_word(words, prop)) }
+              .map { |struct, prop| Selection.new(path, name, struct, prop, wire_word(keys, prop)) }
           end
         end
       end
 
       # How the query spells a prop, when that isn't the prop's own name — a
       # camelCase field, an alias, a reserved rename. Read back off the query
-      # text rather than derived from the prop, since no rule inverts an
-      # alias; nil when the query spells it the same way, which is most of
-      # the time.
-      def wire_word(words, prop)
-        words.find { |word| word != prop.to_s && GraphWeaver::Codegen.prop_name(word) == prop.to_s }
+      # rather than derived from the prop, since no rule inverts an alias; nil
+      # when the query spells it the same way, which is most of the time.
+      def wire_word(keys, prop)
+        keys.find { |key| key != prop.to_s && GraphWeaver::Codegen.prop_name(key) == prop.to_s }
+      end
+
+      # Every response key the document asks for. The coordinate is the
+      # selection to go and delete, so it can only be one of these: scanning
+      # the file's text let `$id: ID!` — or a comment — name a field the query
+      # never selected.
+      def response_keys(nodes, found = [])
+        nodes.each do |node|
+          found << (node.alias || node.name) if node.is_a?(GraphQL::Language::Nodes::Field)
+          response_keys(node.selections, found) if node.respond_to?(:selections)
+        end
+        found
       end
 
       # Nested structs are nested constants, so the props of a whole response

data/lib/graph_weaver/internal/values.rb

@@ -88,7 +88,12 @@ class GraphWeaver::Internal::Values
   # for the next, and only a caller holding the graph can say which. Left
   # unsaid they are read back off the schema, which is the answer for every
   # app with one graph running a live class.
-  def initialize(seed: nil, values: nil, pins: nil, schema: nil, registry: nil)
+  # pin_advice: how to pin, in the words of the door the caller came in by —
+  # a callable taking the scalar's name. Left unsaid it is the three doors
+  # onto a fake, which is where this is reached from unless something says
+  # otherwise (check_scalars! runs outside all three).
+  def initialize(seed: nil, values: nil, pins: nil, schema: nil, registry: nil, pin_advice: nil)
+    @pin_advice = pin_advice
     @registry = registry || GraphWeaver::Internal::Util.registry_for(schema)
     @rng = Random.new(seed || GraphWeaver::Testing.config.seed || Random.new_seed)
     @pins = (pins || GraphWeaver::Testing.config.overrides).transform_keys(&:to_s)
@@ -202,12 +207,19 @@ class GraphWeaver::Internal::Values
   # for — `Money.parse` accepts what its author decided it accepts — and
   # guessing hands the generated cast a placeholder, which fails deep inside
   # from_h blaming the codec.
+  #
+  # Each door onto a fake spells a pin differently and this can't know which
+  # you came in by, so the advice names all three — unless the caller said,
+  # in which case it is the one that works there.
   def unfakeable!(type_name, field_name, registered, coordinate, at)
+    type = type_name.inspect
+    advice = @pin_advice&.call(type_name) ||
+      "Pin the type (#{type}) or just this field (#{(coordinate || field_name).inspect}), " \
+      "wherever the fake is built — graphql_fake(#{type} => ...) in an rspec example, " \
+      "FakeClient.new(#{type} => ...) outside one, or GraphWeaver::Testing.config.overrides " \
+      "for the whole suite."
     raise GraphWeaver::Error, "can't fabricate a #{type_name} #{at ? "at #{at}" : "for #{field_name.inspect}"}: " \
-      "it deserializes into #{registered.type}, and only you know what wire value that accepts. " \
-      "Pin the type — overrides: { #{type_name.inspect} => ... } — or this one field: " \
-      "overrides: { #{(coordinate || field_name).inspect} => ... }. Suite-wide, that's " \
-      "GraphWeaver::Testing.config.overrides."
+      "it deserializes into #{registered.type}, and only you know what wire value that accepts. #{advice}"
   end
 
   # :faker is an explicit ask — fail loudly when the gem is missing; auto

data/lib/graph_weaver/internal.rb

@@ -243,14 +243,14 @@ module GraphWeaver
             "or cache one: GraphWeaver.new(url, cache: true).schema"
         end
 
-        # The graphql-ruby schema class the app default executes against,
-        # when it runs in-process — a Client wrapping one, or the class in
-        # the slot bare. nil for every network client. Not memoized: in dev
-        # the class object is replaced on reload.
-        def live_schema
+        # The graphql-ruby schema class a client executes against, when it
+        # runs in-process — a Client wrapping one, or the class in the slot
+        # bare. nil for every network client. Defaults to the app's own, and
+        # a graph passes its client. Not memoized: in dev the class object is
+        # replaced on reload.
+        def live_schema(client = GraphWeaver.client)
           # through #transport, not #schema: a url client's #schema
           # introspects, so asking it would answer over the network
-          client = GraphWeaver.client
           target = client.is_a?(Client) ? client.transport : client
           target = target.schema if target.is_a?(InProcess)
           target if target.is_a?(Class) && target <= GraphQL::Schema

data/lib/graph_weaver/log_subscriber.rb

@@ -14,17 +14,20 @@ module GraphWeaver
   #      GraphWeaver PersonQuery (12.3ms) ok
   #      GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
   #      GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+  #      GraphWeaver PersonQuery (44.0ms) failed GraphWeaver::CastError
   #      GraphWeaver billing/InvoicesQuery (12.3ms) ok
   #
   # Attached by the railtie wherever ActiveSupport is, and fed by the
   # instrumenter it sets. Requires ActiveSupport — `require` this yourself
   # only if you subscribe by hand.
   #
-  # **One rule decides which line you get: the summary is info, the wire is
-  # debug.** This is the only GraphWeaver line at info, so a production log
-  # gets one per operation and nothing that could carry PII; turning
-  # GraphWeaver.logger up to debug adds the query, the variables and the
-  # response *beneath* it rather than repeating it.
+  # **One rule decides which line you get: the operation is info, the
+  # attempt is debug.** The info line is one CALL of a generated module, so
+  # it says what the caller got — a cast that raised reads `failed`, and a
+  # test mode's stand-in gets a line like every other client. A production
+  # log gets one per operation and nothing that could carry PII; turning
+  # GraphWeaver.logger up to debug adds each attempt, with the url, the HTTP
+  # status and which retry it was, beneath it.
   #
   # It writes through GraphWeaver.logger rather than Rails.logger, so
   # `GraphWeaver.logger = nil` — the documented way to silence the gem —
@@ -33,17 +36,10 @@ module GraphWeaver
   class LogSubscriber < ActiveSupport::LogSubscriber
     # attach_to(:graph_weaver) subscribes "#{method}.graph_weaver" and
     # ActiveSupport::Subscriber#call dispatches on the name up to the first
-    # dot — so this method name is EXECUTE_EVENT's first half, both ways.
-    def execute(event)
-      payload = event.payload
+    # dot — so these method names are the events' first halves, both ways.
+    def operation(event) = write(:info, event)
 
-      GraphWeaver::Internal::Log.log(:info) do
-        # duration_ms is the instrumenter's own measurement; event.duration
-        # covers a subscriber attached to something that didn't set it
-        ms = payload[:duration_ms] || event.duration
-        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
-      end
-    end
+    def execute(event) = write(:debug, event)
 
     # GraphWeaver's logger, not Rails' — LogSubscriber#call skips a
     # subscriber whose logger is nil, which is what makes the gem's own
@@ -52,7 +48,20 @@ module GraphWeaver
 
     private
 
-    # What ran: the operation, prefixed by its graph when the request carried
+    # One shape for both, so the attempt beneath an operation reads as the
+    # same line rather than a second format to learn.
+    def write(level, event)
+      payload = event.payload
+
+      GraphWeaver::Internal::Log.log(level) do
+        # duration_ms is the instrumenter's own measurement; event.duration
+        # covers a subscriber attached to something that didn't set it
+        ms = payload[:duration_ms] || event.duration
+        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
+      end
+    end
+
+    # What ran: the operation, prefixed by its graph when the payload names
     # one — an app with several graphs reads `billing/InvoicesQuery` without
     # a second line shape to learn, and one with a single graph never sees it.
     def subject(payload)
@@ -61,7 +70,8 @@ module GraphWeaver
     end
 
     # status, then whatever narrows it: the error class, the reason an alert
-    # groups by, and which attempt this was when a Retry is in the stack.
+    # groups by, and — on a debug attempt line — which try this was. The last
+    # two are attempt facts, so only the debug line ever carries them.
     def outcome(payload)
       parts = [payload[:status], payload[:error]]
       # the GraphQL code, or the HTTP status where the request never got one

data/lib/graph_weaver/logging.rb

@@ -43,19 +43,22 @@ module GraphWeaver
       @filter_parameters = filters
     end
 
-    # One callable wrapping every request GraphWeaver makes — over the
-    # wire or in-process — so an APM can time it and count errors. A
-    # no-op until you set one (Rails sets this one for you):
+    # One callable wrapping every call GraphWeaver makes — one generated
+    # module's execute, and every request under it, over the wire or
+    # in-process — so an APM can time it and count errors. A no-op until
+    # you set one (Rails sets this one for you):
     #
     #      GraphWeaver.instrumenter = lambda do |event, payload, &block|
     #        ActiveSupport::Notifications.instrument(event, payload, &block)
     #      end
     #
-    # It must call the block and return its value. The only event today is
-    # EXECUTE_EVENT; its payload is the contract in docs/logging.md —
-    # :operation, :client, :kind, :status, :duration_ms, :graph always;
-    # :url/:http_status over the wire, :schema in-process, :error/:code on a
-    # failure, :retries when a Retry wrapped it. Never the query text or the
+    # It must call the block and return its value. Two events, and their
+    # payloads are the contract in docs/logging.md: OPERATION_EVENT is one
+    # call of a generated module (:operation, :module, :graph, :kind,
+    # :client, :status, :duration_ms), and EXECUTE_EVENT is one request
+    # inside it (:url/:http_status over the wire, :schema in-process,
+    # :retries under a Retry). Both add :error on a raise and :code on a
+    # response that carried GraphQL errors. Never the query text or the
     # variables: the payload fans out to subscribers that know none of the
     # filtering rules, so PII belongs at debug on the logger, where the
     # level gates it and filter_parameters scrubs it.
@@ -137,14 +140,24 @@ module GraphWeaver
 
   self.filter_parameters = DEFAULT_FILTER_PARAMETERS
 
-  # The one instrumentation event: a single GraphQL request, start to
-  # parsed response, whichever client slot served it. `<event>.<namespace>`
-  # is how every notification in this ecosystem is spelled
-  # (sql.active_record, execute_multiplex.graphql) — it's what
-  # ActiveSupport::LogSubscriber.attach_to and an APM's namespace routing
-  # key on, so a backwards name made both of them a puzzle.
+  # One GraphQL REQUEST, start to parsed response, whichever client slot
+  # served it — one attempt, so a call a Retry made three goes at is three
+  # of these. `<event>.<namespace>` is how every notification in this
+  # ecosystem is spelled (sql.active_record, execute_multiplex.graphql) —
+  # it's what ActiveSupport::LogSubscriber.attach_to and an APM's namespace
+  # routing key on, so a backwards name made both of them a puzzle.
   EXECUTE_EVENT = "execute.graph_weaver"
 
+  # One CALL of a generated module's execute/execute!: the request it makes,
+  # every retry and backoff beneath it, and the cast into the typed structs.
+  # One or more EXECUTE_EVENTs nest inside it.
+  #
+  # It says what the CALLER got, which a request can't: a CastError is raised
+  # after the response is back, so the request closed :ok while the app saw a
+  # failure. And it fires at the module seam, which every client slot passes
+  # through — a fake, the test router and a cassette report here too.
+  OPERATION_EVENT = "operation.graph_weaver"
+
   module Internal
     # The emitting half of the narration the three accessors above
     # configure. Setting a logger is API; writing to it is not, and the
@@ -174,48 +187,29 @@ module GraphWeaver
           result
         end
 
-        # Wrap the block in the instrumenter, if one is set. The caller
-        # supplies what only it knows (:url, :schema, :client); this fills
-        # in the half every path shares — how it ended, how long it took,
-        # what a Retry had already spent — so one subscriber reads one
-        # shape whichever client slot served the request.
-        def instrument(event, payload)
-          hook = GraphWeaver.instrumenter
-          return yield unless hook
+        # Wrap one REQUEST in the instrumenter, if one is set. The caller
+        # supplies what only it knows (:url, :schema, :client); this adds the
+        # attempt facts — the graph in scope, what a Retry had already spent —
+        # so one subscriber reads one shape whichever client slot served it.
+        def instrument_request(payload, &block)
+          return yield unless GraphWeaver.instrumenter
 
-          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           retries = Thread.current[RETRIES]
           payload[:retries] = retries if retries
           payload[:graph] = Thread.current[GRAPH]
-          # pessimistic, so :status is set even for what a rescue can't
-          # see — an Interrupt, a killed thread — and never silently absent
-          payload[:status] = :failed
 
           # One dispatch labels one request. Whatever THIS request reaches —
           # a resolver serving it that calls out — is a request of its own,
           # and the caller's graph would be a wrong label on it.
-          with_graph(nil) do
-            hook.call(event, payload) do
-              result = yield
-              errors = response_errors(result)
-              if errors.empty?
-                payload[:status] = :ok
-              else
-                payload[:status] = :errors
-                code = errors.grep(Hash).filter_map { |e| GraphWeaver::GraphQLError.from_h(e).code }.first
-                payload[:code] = Redact.tag(code)
-              end
-              result
-            rescue => e
-              payload[:error] = e.class.name
-              # :code stays the GraphQL error code and nothing else — it used
-              # to hold a ServerError's status here, so one tag carried two
-              # dimensions ("THROTTLED" and 429). The number is :http_status.
-              raise
-            ensure
-              payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
-            end
-          end
+          with_graph(nil) { measure(GraphWeaver::EXECUTE_EVENT, payload, &block) }
+        end
+
+        # Wrap one CALL of a generated module: the request under it and the
+        # cast that follows. The caller names :graph here rather than reading
+        # it out of the fiber-local, because it IS the module that set it —
+        # and it stays set, so the request below wears the same label.
+        def instrument_operation(payload, &block)
+          measure(GraphWeaver::OPERATION_EVENT, payload, &block)
         end
 
         # What a Retry has already spent, read by the attempt it is about
@@ -275,13 +269,55 @@ module GraphWeaver
           end
         end
 
-        # The GraphQL errors a response carries, whatever answered it — a
-        # Hash from a transport, a graphql-ruby Result in-process, a fake.
-        # Never raises: an instrumenter that decides which exception a
-        # caller sees is worse than a missing tag.
+        # The half both events share: run the block inside the hook, and
+        # record how it ended, the code an alert groups by, and how long it
+        # took — every one of them before the hook's block returns, so a
+        # subscriber reads a complete payload.
+        def measure(event, payload)
+          hook = GraphWeaver.instrumenter
+          return yield unless hook
+
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          # pessimistic, so :status is set even for what a rescue can't
+          # see — an Interrupt, a killed thread — and never silently absent
+          payload[:status] = :failed
+
+          hook.call(event, payload) do
+            result = yield
+            errors = response_errors(result)
+            if errors.empty?
+              payload[:status] = :ok
+            else
+              payload[:status] = :errors
+              code = errors.grep(GraphWeaver::GraphQLError).filter_map(&:code).first
+              payload[:code] = Redact.tag(code)
+            end
+            result
+          rescue => e
+            payload[:error] = e.class.name
+            # :code stays the GraphQL error code and nothing else — it used
+            # to hold a ServerError's status here, so one tag carried two
+            # dimensions ("THROTTLED" and 429). The number is :http_status.
+            raise
+          ensure
+            payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+          end
+        end
+
+        # The GraphQL errors a result carries, whatever answered it — a Hash
+        # from a transport, a graphql-ruby Result in-process, a fake, or the
+        # typed Response a generated cast built. A Hash becomes a GraphQLError
+        # so one reading answers for :code whichever arrived; anything else in
+        # the list is left as it came, since its presence alone already means
+        # the response carried errors. Never raises: an instrumenter that
+        # decides which exception a caller sees is worse than a missing tag.
         def response_errors(result)
+          return result.errors if result.is_a?(GraphWeaver::Response)
+
           errors = result.to_h["errors"] if result.respond_to?(:to_h)
-          errors.is_a?(Array) ? errors : []
+          return [] unless errors.is_a?(Array)
+
+          errors.map { |e| e.is_a?(Hash) ? GraphWeaver::GraphQLError.from_h(e) : e }
         rescue StandardError
           []
         end

data/lib/graph_weaver/parsing.rb

@@ -7,9 +7,9 @@ require_relative "codegen"
 require_relative "internal"
 
 module GraphWeaver
-  # Anything that holds a schema parses against it. That's a Client, an
-  # InProcess wrapper, a FakeClient, and the test Router — each of which
-  # already has the two things parsing needs, a schema to check the query
+  # Anything that holds a schema parses and checks against it. That's a
+  # Client, an InProcess wrapper, a FakeClient, and the test Router — each of
+  # which already has the two things parsing needs, a schema to check the query
   # against and a client for the module to run on:
   #
   #      DashboardQuery = router.parse("query { me { username } }")
@@ -31,6 +31,35 @@ module GraphWeaver
       GraphWeaver.parse(schema: T.unsafe(self).schema, query:, name:, client: self)
     end
 
+    # Does this query validate? The string form of GraphWeaver.check_queries,
+    # answering with the same JSON-ready hashes — `message`, `line`, `column`,
+    # plus `subgraphs` where a supergraph brands them — so an empty array means
+    # it validates:
+    #
+    #      client.check_query("query { viewer { login } }")   # => []
+    #      client.check_query("query { viewer { lgoin } }")
+    #      # => [{ "message" => "Field 'lgoin' doesn't exist on type 'User'",
+    #      #      "line" => 1, "column" => 17 }]
+    #
+    # Checked against this object's own schema — what `execute` would run
+    # against — so a url client introspects on first use as it always does, and
+    # nothing re-introspects the way check_queries defaults to. That is why it
+    # lives here: inside an example `GraphWeaver.client` is a fake, an InProcess
+    # or the test router, and each of those holds the schema the question is
+    # about. An unparseable source is an entry like any other; nothing here
+    # raises for a bad query. Shared fragments are inlined from fragments: the
+    # same way every other door inlines them.
+    def check_query(source, fragments: GraphWeaver.fragments_paths)
+      # a dump-backed Client can brand each error with the subgraph it is
+      # about; nothing else in the slot has a file behind its schema
+      holder = T.unsafe(self)
+      dump = holder.schema_source if holder.respond_to?(:schema_source)
+      GraphWeaver::Internal::QueryCheck.errors(
+        holder.schema, source, GraphWeaver::Codegen.load_fragments(fragments),
+        GraphWeaver::Internal::QueryCheck.routing_table_for(dump),
+      )
+    end
+
     # Parse every query in a directory (subdirectories included) into typed
     # modules, named like generation would name them — the no-build-step
     # analog of generate! + load_generated!:

data/lib/graph_weaver/query_module.rb

@@ -59,30 +59,69 @@ module GraphWeaver
     attr_writer :client
 
     # The one call a generated `execute` makes: resolve the client, run this
-    # module's own operation, hand the raw response back for from_response to
-    # wrap. Here rather than emitted, so what has to BRACKET a request — the
-    # graph label today — costs nothing in every generated file, and one
-    # reading of it covers every module in the app.
+    # module's own operation, and cast the raw response with the block the
+    # caller hands over — under one OPERATION_EVENT, which is the only seam
+    # that sees what the caller actually GOT. Here rather than emitted, so
+    # what has to bracket a call — the graph label, the event — costs nothing
+    # in every generated file, and one reading of it covers every module.
+    #
+    # Without a block it is the request alone, unreported: that is a module
+    # generated before the operation event existed, and an event closing :ok
+    # over half a call is worse than no event, since the cast it can't see is
+    # exactly where a CastError comes from.
     #
     # The constants come off the module rather than the caller: a generated
     # `execute` already knows them, but reading them here is what makes this
     # the whole of the call instead of three arguments' worth of it.
-    sig { params(variables: T::Hash[String, T.untyped], client: T.untyped).returns(T.untyped) }
-    def dispatch(variables, client:)
+    sig do
+      params(
+        variables: T::Hash[String, T.untyped],
+        client: T.untyped,
+        cast: T.nilable(T.proc.params(raw: T.untyped).returns(T.untyped)),
+      ).returns(T.untyped)
+    end
+    def dispatch(variables, client:, &cast)
       # A value with no JSON form is a bug in the call, not in the client that
       # would have carried it — so it is refused here, where every mode passes,
       # rather than in the transport, which :in_process and :fake never reach.
       # (A transport asks the same question of a raw query string, which never
       # comes through here.)
       GraphWeaver::Internal::Wire.check_variables!(variables)
+      target = client_for(client)
 
       # the graph codegen baked in, never one inferred from the client — a
       # wrong label on a request is worse than no label
       GraphWeaver::Internal::Log.with_graph(graph_name) do
-        client_for(client).execute(query_string, variables:, operation_name:)
+        next request(target, variables) unless cast
+
+        GraphWeaver::Internal::Log.instrument_operation(operation_payload(target)) do
+          cast.call(request(target, variables))
+        end
       end
     end
 
+    # This module's own operation, through the client this call resolved to.
+    sig { params(target: T.untyped, variables: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def request(target, variables)
+      target.execute(query_string, variables:, operation_name:)
+    end
+
+    # What one call of this module is, for an APM. :module is the fact this
+    # seam has and the request below it doesn't — two graphs can name the same
+    # operation, and a trace that is slow wants the file. :client is what the
+    # module RESOLVED to, so a test mode's stand-in names itself; the request
+    # event underneath names the transport that carried it.
+    sig { params(target: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+    def operation_payload(target)
+      {
+        operation: operation_name,
+        module: T.unsafe(self).name,
+        graph: graph_name,
+        kind: GraphWeaver::Internal::Wire.kind(query_string),
+        client: target.class,
+      }
+    end
+
     # The client one execute runs through: the per-call `client:`, else the
     # module's, else the app default. Checked here so a wrong one names the
     # contract and the module, rather than surfacing as a NoMethodError from
@@ -96,7 +135,8 @@ module GraphWeaver
       # Kernel.raise: this module is extended into another, so sorbet can't
       # see that its host is an Object
       Kernel.raise GraphWeaver::Error,
-        "#{self}: client must respond to #execute(query, variables:), got #{target.class}"
+        "#{self}: client must respond to #execute(query, variables:, operation_name:), " \
+        "got #{target.class}"
     end
 
     # A module knows which graph it belongs to, and the graph knows how to

data/lib/graph_weaver/rspec.rb

@@ -161,7 +161,9 @@ module GraphWeaver
       # suite's WebMock setup is touched.
       def self.serve!
         webmock!
-        wire_targets.map do |url, graph|
+        targets, above = wire_targets
+        above.each { |graph| disclose_above!(graph) }
+        targets.map do |url, graph|
           # built here, so a graph with nothing to serve refuses before the
           # example runs rather than from inside its first request
           disclose!(GraphWeaver::Internal::TestClients.standin(graph), url, graph)
@@ -210,6 +212,17 @@ module GraphWeaver
         end
       end
 
+      # Say which graph ran above the wire. Its stand-in is built when one of
+      # its modules first runs, not here — a graph the example never touches
+      # must not refuse it — so this names the graph rather than what is
+      # behind it.
+      def self.disclose_above!(graph)
+        GraphWeaver::Internal::Log.log(:info) do
+          ":wire has no endpoint for #{graph.name ? "graph #{graph.name.inspect}" : "this app"} — " \
+            "its client posts to none, so its modules run above the wire, as #{TAG}: :in_process would"
+        end
+      end
+
       # What the stand-in IS, read off the object rather than re-deciding —
       # one answer, and it can't drift from what was built. A fake of a dump
       # has no name to give: the dump loads as an anonymous class, and
@@ -254,21 +267,24 @@ module GraphWeaver
       # inside the cleanup.
       def self.unserve!(stub) = WebMock::StubRegistry.instance.request_stubs.delete(stub)
 
-      # Every endpoint an example's modules can post to, each with the graph
-      # whose resolvers belong behind it: the client each graph names, or
-      # GraphWeaver.client for a graph naming none. One graph per endpoint —
-      # an app whose graphs all name clients needs no app default at all.
+      # What :wire does with each graph, in two lists: the endpoints to stub,
+      # each with the graph whose resolvers belong behind it, and the graphs
+      # there is no endpoint for. One graph per endpoint — an app whose graphs
+      # all name clients needs no app default at all.
+      #
+      # A graph whose client posts to no url has no wire to be served at, so
+      # it runs above one instead of refusing the example — including the
+      # examples that never touch it. An example where NO graph posts anywhere
+      # is refused, since a :wire that serves nothing tests no transport.
       def self.wire_targets
-        targets = GraphWeaver.graphs.filter_map do |graph|
-          client = graph.client || GraphWeaver.client
-          [endpoint!(client, graph), graph] if client
-        end
+        targets, above = GraphWeaver.graphs.map { |graph| [graph.client_url, graph] }.partition(&:first)
         refuse_shared_endpoint!(targets)
-        return targets if targets.any?
+        return [targets, above.map(&:last)] if targets.any?
 
-        # nothing bakes a client and the app has none: the endpoint refusal
-        # names the empty slot, which is the thing to fix
-        endpoint!(GraphWeaver.client)
+        # the endpoint refusal names the client that posts to none, which is
+        # the thing to fix
+        graph = GraphWeaver.graphs.first
+        endpoint!(graph&.client || GraphWeaver.client, graph)
       end
 
       # One stub per url, so two graphs on one endpoint used to mean the
@@ -343,7 +359,8 @@ module GraphWeaver
       end
 
       private_class_method :wire_targets, :refuse_shared_endpoint!, :whose_client,
-        :webmock!, :webmock_enabled?, :disclose!, :served, :unnamed_schemas, :loaded_schemas
+        :webmock!, :webmock_enabled?, :disclose!, :disclose_above!, :served, :unnamed_schemas,
+        :loaded_schemas
 
       # Included into every example group, so graphql_context is there
       # whether or not this example took a client from the hook.
@@ -570,10 +587,17 @@ module GraphWeaver
           raise GraphWeaver::Error, "graphql_context needs resolvers to receive it, and a " \
             "#{TAG}: :fake example runs against fabricated data — tag it #{TAG}: :in_process or " \
             "#{TAG}: :router (or pin the data itself: " \
-            "graphql_fake(overrides: { \"Person.name\" => \"Ada\" }))"
+            "graphql_fake(\"Person.name\" => \"Ada\"))"
         else
-          raise GraphWeaver::Error, "graphql_context needs an example running against your " \
-            "resolvers — tag it #{TAG}: :in_process or #{TAG}: :router"
+          # :live, which is what an untagged example is. The app's own client
+          # stays in the slot holding the context it was built with, so there
+          # is nothing here to merge onto — and saying "you need resolvers"
+          # reads as false to an app whose own client is an InProcess, which
+          # is running them
+          raise GraphWeaver::Error, "graphql_context says what THIS example's resolvers see, " \
+            "and #{TAG}: :live leaves your app's own client exactly as it is — carrying the " \
+            "context it was built with. Tag the example #{TAG}: :in_process or #{TAG}: :router, " \
+            "which build a client per example."
         end
       end