graph_weaver 0.4.6 → 0.5.0

data/lib/graph_weaver/errors.rb

@@ -2,6 +2,8 @@
 # frozen_string_literal: true
 
 require "sorbet-runtime"
+require "time" # Time.httpdate, for Retry-After
+
 require_relative "inflect"
 require_relative "logging"
 
@@ -12,8 +14,9 @@ module GraphWeaver
   # structured failures to users. One subclass per failure site —
   # {TransportError} (never reached the server), {ServerError} (non-2xx),
   # {QueryError} (GraphQL-level errors), {TypeError} (response wouldn't
-  # cast), {InputError} (bad variables), {ValidationError} (build time) —
-  # each merging its specifics into #to_h.
+  # cast), {InputError} (bad variables), {ValidationError} (build time),
+  # {ConfigurationError} (setup judged against your schema) — each merging
+  # its specifics into #to_h.
   class Error < StandardError
     extend T::Sig
 
@@ -85,17 +88,49 @@ module GraphWeaver
     sig { returns(T.untyped) }
     attr_reader :body
 
-    sig { params(status: Integer, body: T.untyped).void }
-    def initialize(status:, body: nil)
+    # The response headers, names downcased — the rate-limit budget
+    # (x-ratelimit-remaining), the request id your provider wants in a
+    # support ticket, Retry-After. Empty when the transport had none.
+    sig { returns(T::Hash[String, String]) }
+    attr_reader :headers
+
+    sig { params(status: Integer, body: T.untyped, headers: T::Hash[String, String]).void }
+    def initialize(status:, body: nil, headers: {})
       @status = status
       @body = body
+      @headers = headers
       snippet = body.to_s.empty? ? "" : ": #{body.to_s[0, 500]}"
       super("HTTP #{status}#{snippet}")
     end
 
+    # Seconds to wait per the server's Retry-After, which is either a
+    # delay in seconds or an HTTP-date. nil when absent or unparseable;
+    # negative dates (already past) clamp to 0. See RFC 9110 §10.2.3.
+    sig { returns(T.nilable(Float)) }
+    def retry_after
+      value = headers["retry-after"]&.strip
+      return if value.nil? || value.empty?
+      return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
+
+      seconds = Time.httpdate(value) - Time.now
+      [seconds, 0.0].max
+    rescue ArgumentError
+      nil
+    end
+
+    # True when the server said "you're going too fast" — 429, or the
+    # 503 + Retry-After that some gateways send instead. Same question,
+    # same name, as QueryError#throttled?: an API may answer either way.
+    sig { returns(T::Boolean) }
+    def throttled?
+      status == 429 || (status == 503 && !retry_after.nil?)
+    end
+
     sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
-      super.merge("status" => status)
+      # the raw headers stay off the machine side — Set-Cookie and
+      # friends don't belong in a log line; read #headers for those
+      super.merge("status" => status, "retry_after" => retry_after).compact
     end
   end
 
@@ -171,6 +206,23 @@ module GraphWeaver
       code == "GRAPHQL_VALIDATION_FAILED" || VALIDATION_MESSAGE.match?(message)
     end
 
+    # The codes servers use to say "you're going too fast". No standard
+    # exists, so this is the union of what the big graphs actually send:
+    # Shopify THROTTLED, GitHub RATE_LIMITED, Apollo/Hasura the rest.
+    # Pass it to Retry (retry_codes:) rather than hand-writing strings.
+    THROTTLE_CODES = T.let(
+      %w[THROTTLED RATE_LIMITED RATE_LIMIT_EXCEEDED TOO_MANY_REQUESTS REQUEST_LIMIT_EXCEEDED].freeze,
+      T::Array[String],
+    )
+
+    # True when this error is the GraphQL-level equivalent of a 429 —
+    # the same question ServerError#throttled? asks of an HTTP status,
+    # since an API may answer either way.
+    sig { returns(T::Boolean) }
+    def throttled?
+      THROTTLE_CODES.include?(code)
+    end
+
     # The field the error points at, as a stable dotted path with list
     # indices stripped — ["people", 3, "email"] => "people.email". The
     # parseable key for grouping/reporting (the raw #path keeps indices).
@@ -249,6 +301,15 @@ module GraphWeaver
       errors.any?(&:validation?)
     end
 
+    # True when the server said "you're going too fast" in the errors
+    # array rather than in an HTTP status — back off and retry, don't
+    # rewrite the query. Same name as ServerError#throttled?, because an
+    # API may answer either way and callers shouldn't have to care which.
+    sig { returns(T::Boolean) }
+    def throttled?
+      errors.any?(&:throttled?)
+    end
+
     # Errors grouped by the field they point at (index-stripped dotted
     # path; nil key for global errors) — iterate with each_error:
     #
@@ -312,7 +373,7 @@ module GraphWeaver
   end
 
   # Raised when a GraphQL response carried top-level errors and the caller
-  # demanded data (Response#data!, or the one-shot GraphWeaver.execute).
+  # demanded data (Response#data!, or the one-shot GraphWeaver.run!).
   # Carries the structured errors, any partial data, and top-level
   # extensions (cost/throttle metadata).
   class QueryError < Error
@@ -354,19 +415,28 @@ module GraphWeaver
     def to_h
       super.merge(
         "schema_stale" => schema_stale?,
+        "throttled" => throttled?,
         "codes" => codes,
         "errors" => errors.map(&:to_h),
         "extensions" => extensions,
       )
     end
 
+    # what a validation-shaped rejection means, and the way out of it
+    DRIFT_HINT = T.let(
+      "the server rejected the query shape: the schema may have changed since generation; " \
+        "refresh the schema dump and regenerate " \
+        "(rake graph_weaver:schema:refresh && rake graph_weaver:generate)",
+      String,
+    )
+
     private
 
     sig { returns(String) }
     def summary
       first = errors.first
-      more = errors.size > 1 ? " (and #{errors.size - 1} more)" : ""
-      drift = schema_stale? ? " — the server rejected the query shape: the schema may have changed since generation; refresh the schema dump and regenerate (rake graph_weaver:schema:refresh && rake graph_weaver:generate)" : ""
+      more = " (and #{errors.size - 1} more)" if errors.size > 1
+      drift = " — #{DRIFT_HINT}" if schema_stale?
       "GraphQL query failed: #{first}#{more}#{drift}"
     end
   end
@@ -383,10 +453,16 @@ module GraphWeaver
     sig { returns(T.untyped) }
     attr_reader :struct
 
+    # sorbet-runtime appends its own frame to a prop type error ("Caller:
+    # .../call_validation.rb:331"), which is a path into the gem and never
+    # into the code with the problem — so it is dropped rather than reprinted
+    # as if it located anything.
+    SORBET_CALLER = /\s*\nCaller: .*\z/m
+
     sig { params(struct: T.untyped, error: T.nilable(Exception), message: T.nilable(String)).void }
     def initialize(struct:, error: nil, message: nil)
       @struct = struct
-      super("failed to cast response into #{struct}: #{message || error&.message}")
+      super("failed to cast response into #{struct}: #{message || error&.message&.sub(SORBET_CALLER, "")}")
     end
 
     sig { override.returns(T::Hash[String, T.untyped]) }
@@ -424,6 +500,15 @@ module GraphWeaver
     end
   end
 
+  # The setup doesn't add up — judged against your schema, not against the
+  # shape of an argument. Which Ruby schema serves which subgraph is the
+  # case that exists: two schemas fit one subgraph, or the one you named
+  # doesn't define what the supergraph says that subgraph resolves. A
+  # verdict the library reached, so it's under the Error umbrella and a
+  # spec helper can rescue it; a plainly wrong argument (`pool_size: must
+  # be >= 1`) stays an ArgumentError, as in any Ruby method.
+  class ConfigurationError < Error; end
+
   # Build-time: the query didn't validate against the schema. Carries the
   # structured validation errors (message + line/column) rather than a
   # joined string. Under the Error umbrella like everything else raised
@@ -437,12 +522,44 @@ module GraphWeaver
     sig { params(errors: T::Array[T::Hash[Symbol, T.untyped]]).void }
     def initialize(errors)
       @errors = errors
-      super("invalid query: #{errors.map { |e| e[:message] }.join("; ")}")
+      super(render(errors))
     end
 
     sig { override.returns(T::Hash[String, T.untyped]) }
     def to_h
       super.merge("errors" => errors.map { |e| e.transform_keys(&:to_s) })
     end
+
+    # "queries/person.graphql:4:5 Field 'nmae' …" back into its three parts —
+    # [path, "line:column", message]. Codegen folds the position (and, when it
+    # knows it, the file) into :message, so anything reporting the parts
+    # separately splits it back out here rather than growing a second splitter
+    # to disagree with. A message with no such prefix passes through whole.
+    sig { params(error: T::Hash[Symbol, T.untyped]).returns([T.nilable(String), String, String]) }
+    def self.split(error)
+      message = error[:message].to_s
+      position = [error[:line], error[:column]].compact.join(":")
+      return [nil, position, message] if position.empty?
+
+      match = message.match(/\A(?:(?<path>.+):)?#{Regexp.escape(position)} (?<rest>.*)\z/m)
+      match ? [match[:path], position, match[:rest]] : [nil, position, message]
+    end
+
+    private
+
+    # Compiler-style: the query file once in the header, then one error per
+    # line — thirty typos on one joined line is a wall nobody reads.
+    sig { params(errors: T::Array[T::Hash[Symbol, T.untyped]]).returns(String) }
+    def render(errors)
+      entries = errors.map { |error| ValidationError.split(error) }
+      paths = entries.map(&:first).compact.uniq
+      hoisted = paths.one?
+
+      lines = entries.map do |path, position, message|
+        prefix = [(path unless hoisted), position].reject { |part| part.nil? || part.empty? }.join(":")
+        prefix.empty? ? "  #{message}" : "  #{prefix}  #{message}"
+      end
+      [hoisted ? "invalid query in #{paths.first}:" : "invalid query:", *lines].join("\n")
+    end
   end
 end

data/lib/graph_weaver/federation.rb

@@ -0,0 +1,272 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+
+require_relative "schema_loader"
+require_relative "schemas"
+
+module GraphWeaver
+  # Federation checks that need no network — the supergraph you committed,
+  # read against the subgraph schemas running in this process.
+  module Federation
+    # Has someone changed a subgraph without recomposing the supergraph?
+    #
+    #      rake graph_weaver:federation:diff SUPERGRAPH=supergraph.graphql
+    #
+    # A committed supergraph is a snapshot of a composition. Change a
+    # subgraph and skip the recompose and it quietly describes a graph that
+    # no longer exists — the failure this catches, locally and before merge,
+    # where {SchemaLoader.stale?} needs the server and answers a different
+    # question (has the *server* drifted from my dump).
+    #
+    # Both directions, because they mean opposite things:
+    #
+    # - **stale** — the supergraph carries `Product.weight` and no schema
+    #   here defines it any more. Recompose.
+    # - **not composed in** — a schema here defines `Product.dimensions` and
+    #   the supergraph doesn't carry it. Publish the subgraph.
+    #
+    # What "defines" means: a coordinate is compared only against the
+    # schemas that could *be* the subgraph the supergraph attributes it to —
+    # the ones defining every non-root type it declares. Exact field-set
+    # equality would be too strict in both directions: a subgraph carries
+    # federation plumbing (`_entities`, `_service`) the supergraph never
+    # has, and a field can legitimately sit in more than one subgraph
+    # (`@external` copies, `@shareable`). So the uncomposed side reports
+    # only a field the supergraph's type doesn't carry **at all** — not one
+    # it merely attributes elsewhere — and underscore-prefixed fields never
+    # count.
+    #
+    # A supergraph is routinely only **partly local** — the rest served by
+    # another process, or answered with fabricated data ({Testing::Subgraphs}
+    # `=> :fake`). Neither can be compared against anything, so the report
+    # names three states rather than two: checked, not here, and faked. A
+    # clean result that didn't say what it couldn't see would be actively
+    # misleading on the graphs this is for.
+    class Drift
+      # Composition names the root types conventionally, and every subgraph
+      # declares one — so a root can't tell subgraphs apart, and a schema
+      # is recognized by the other types it defines.
+      ROOTS = %w[Query Mutation Subscription].freeze
+
+      # { "Product.weight" => ["products"] } — the supergraph says these
+      # subgraphs resolve it, and no schema of theirs here defines it
+      attr_reader :stale
+
+      # { "Product.dimensions" => ["Products::Schema"] } — defined here,
+      # absent from the supergraph
+      attr_reader :uncomposed
+
+      # { "inventory" => ["Warehouse"] } — subgraph => the types that would
+      # identify it, which nothing here defines
+      attr_reader :skipped
+
+      # subgraphs answered with fabricated data, so there's no real schema
+      # behind them to compare against
+      attr_reader :faked
+
+      # every subgraph that was actually compared
+      attr_reader :checked
+
+      # supergraph: the composed SDL (a path or the content); defaults to
+      # the conventional dump. subgraphs: the same map {Testing::Router}
+      # takes — a named schema skips detection, `:fake` (like anything else
+      # that isn't a schema class) says there's nothing real to compare.
+      # schemas: overrides which loaded schemas detection searches — by
+      # default every named GraphQL::Schema in the process.
+      def initialize(supergraph: nil, subgraphs: nil, schemas: nil)
+        source = (supergraph || GraphWeaver::SchemaLoader.locate_path).to_s
+        @table = GraphWeaver::SchemaLoader.routing_table(source)
+        # SDL passed as content has no name to print
+        @source = source.include?("\n") ? "the supergraph" : source
+        @given = named(subgraphs)
+        @schemas = schemas || GraphWeaver::Schemas.loaded
+        @stale = {}
+        @uncomposed = {}
+        @skipped = {}
+        @faked = []
+        @checked = []
+        compare
+      end
+
+      # whether the supergraph and the code here disagree — what CI gates on
+      def drift? = @stale.any? || @uncomposed.any?
+
+      # Nothing was compared, so "no drift" is vacuous: the gate would pass
+      # whatever the subgraphs said. Categorically different from "checked 3
+      # of 4" — that one checked something, and a partly-local supergraph is
+      # a supported setup.
+      def vacuous? = @checked.empty?
+
+      # JSON-ready: the drift, keyed by coordinate, and what wasn't compared.
+      # Empty stale + uncomposed means every subgraph reached was accurate;
+      # `skipped` and `faked` say which weren't reached, and why.
+      def to_h
+        {
+          "stale" => @stale,
+          "uncomposed" => @uncomposed,
+          "skipped" => @skipped,
+          "faked" => @faked,
+        }
+      end
+
+      def report
+        return "#{@source} names no subgraphs" if @table.subgraphs.empty?
+
+        [headline, *section(STALE, @stale), *section(UNCOMPOSED, @uncomposed),
+          *skipped_section, *faked_section].join("\n")
+      end
+      alias to_s report
+
+      def inspect
+        "#<#{self.class.name} #{@stale.size} stale, #{@uncomposed.size} uncomposed, " \
+          "#{@checked.size}/#{@table.subgraphs.size} checked>"
+      end
+
+      private
+
+      STALE = "stale — the supergraph carries these, no schema here defines them (recompose):"
+      UNCOMPOSED = "not composed in — a schema here defines these, the supergraph doesn't carry them:"
+
+      # `subgraphs:` with string keys, refusing a name this supergraph
+      # doesn't have — the same check Testing::Subgraphs makes, and for the
+      # same reason: a typo'd key would silently check nothing
+      def named(given)
+        map = (given || {}).to_h { |name, schema| [name.to_s, schema] }
+        unknown = map.keys - @table.subgraphs
+        if unknown.any?
+          raise GraphWeaver::ConfigurationError, "subgraphs: names #{unknown.join(", ")}, which " \
+            "this supergraph doesn't have (its subgraphs are #{@table.subgraphs.join(", ")})"
+        end
+
+        map
+      end
+
+      def compare
+        @table.subgraphs.each do |name|
+          next unless (fitting = comparable(name))
+
+          @checked << name
+          record_stale(name, fitting)
+          record_uncomposed(name, fitting)
+        end
+      end
+
+      # The schemas to compare this subgraph against, or nil when there are
+      # none — recording why. A named schema is taken as given; otherwise
+      # the schemas defining every type the supergraph says it declares are
+      # the ones that could be it.
+      def comparable(name)
+        if @given.key?(name)
+          schema = @given[name]
+          # :fake, and anything else that isn't a schema class, has nothing
+          # real behind it
+          return [schema] if schema.is_a?(Class)
+
+          @faked << name
+          return
+        end
+
+        anchors = identifying_types(name)
+        fitting = anchors.empty? ? [] : @schemas.select { |s| anchors.all? { |t| s.get_type(t) } }
+        return fitting if fitting.any?
+
+        @skipped[name] = anchors
+        nil
+      end
+
+      def declared_types(name)
+        @table.types.select { |type| @table.declared_in(type).include?(name) }
+      end
+
+      # The types that recognize this subgraph's schema: the ones it
+      # declares, minus the roots every subgraph has.
+      def identifying_types(name) = declared_types(name) - ROOTS
+
+      # Fields the supergraph says this subgraph resolves, but none of its
+      # candidate schemas still defines. Every declared field, not only the
+      # explicitly routed ones — a field with no @join__field lives wherever
+      # its type does, and dropping one is exactly the drift this looks for.
+      def record_stale(name, fitting)
+        declared_types(name).each do |type_name|
+          @table.declared_fields(type_name).each do |field_name|
+            next unless @table.owners(type_name, field_name).include?(name)
+
+            coordinate = "#{type_name}.#{field_name}"
+            next if fitting.any? { |schema| GraphWeaver::Schemas.defines?(schema, coordinate) }
+
+            (@stale[coordinate] ||= []) << name
+          end
+        end
+      end
+
+      # fields those schemas define on this subgraph's types that the
+      # supergraph's own type doesn't carry
+      def record_uncomposed(name, fitting)
+        declared_types(name).each do |type_name|
+          fitting.each do |schema|
+            local_fields(schema, type_name).each do |field_name|
+              next if @table.declares?(type_name, field_name)
+
+              entry = (@uncomposed["#{type_name}.#{field_name}"] ||= [])
+              entry << schema.name unless entry.include?(schema.name)
+            end
+          end
+        end
+      end
+
+      # a schema's own fields on a type, minus federation's and
+      # introspection's plumbing (_entities, _service, __typename) — which
+      # no supergraph carries and which is never drift
+      def local_fields(schema, type_name)
+        type = schema.get_type(type_name)
+        members =
+          if type.respond_to?(:fields) then type.fields.keys
+          elsif type.respond_to?(:arguments) then type.arguments.keys
+          else []
+          end
+
+        members.reject { |field| field.start_with?("_") }
+      end
+
+      def headline
+        counts = [
+          ("#{@stale.size} stale" if @stale.any?),
+          ("#{@uncomposed.size} not composed in" if @uncomposed.any?),
+        ].compact
+        # "matches the schemas here" over nothing compared is the one verdict
+        # that reads as a pass and isn't one
+        verdict =
+          if counts.any? then counts.join(", ")
+          elsif vacuous? then "compared against nothing here"
+          else "matches the schemas here"
+          end
+        "#{@source}: #{verdict} " \
+          "(checked #{@checked.size} of #{@table.subgraphs.size} subgraphs)"
+      end
+
+      def section(title, entries)
+        return [] if entries.empty?
+
+        ["", title, *entries.sort.map { |coordinate, who| "  #{coordinate} (#{who.join(", ")})" }]
+      end
+
+      # Not an error — a supergraph is routinely only partly local — but a
+      # clean report has to say what it didn't look at.
+      def skipped_section
+        return [] if @skipped.empty?
+
+        ["", "not checked — nothing here defines what the supergraph says these declare " \
+          "(running elsewhere, or the type is gone):",
+          *@skipped.sort.map { |name, types| "  #{name} (#{types.empty? ? "root types only" : types.join(", ")})" }]
+      end
+
+      def faked_section
+        return [] if @faked.empty?
+
+        ["", "not checked — answered with fabricated data:", *@faked.sort.map { |name| "  #{name}" }]
+      end
+    end
+  end
+end

data/lib/graph_weaver/hints.rb

@@ -48,11 +48,19 @@ module GraphWeaver
       super
     end
 
+    # keeps #method and #respond_to? agreeing with method_missing — without
+    # it `struct.method(:nmae)` raises a bare NameError while `struct.nmae`
+    # gets the hint
+    def respond_to_missing?(name, include_private = false)
+      !!prop_hint(name.to_s) || super
+    end
+
     private
 
     def prop_hint(name)
       prop = GraphWeaver::Inflect.underscore(name)
-      if prop != name && respond_to?(prop)
+      # method_defined?, not respond_to? — respond_to_missing? lands back here
+      if prop != name && T.unsafe(self.class).method_defined?(prop)
         return "GraphQL fields generate snake_case props; use '#{prop}'"
       end
 

data/lib/graph_weaver/in_process.rb

@@ -0,0 +1,90 @@
+# typed: true
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+require_relative "parsing"
+require_relative "transport"
+
+# Runs queries against a live graphql-ruby schema in the same process —
+# no socket, no serialization:
+#
+#      GraphWeaver.new(MySchema, context: { current_user: user })
+#      GraphWeaver::InProcess.new(MySchema, context: { current_user: user })
+#
+# A schema class already satisfies the client contract on its own (and
+# still does — it stays usable bare). The wrapper adds the three things
+# it can't do for itself:
+#
+#   - **context:** — `Schema.execute` takes one, but nothing supplied it,
+#     so a resolver reading `context[:current_user]` got nil and it
+#     surfaced as "Cannot return null for non-nullable field Query.me".
+#     For server-side composition, context *is* the request.
+#   - **logging** — all of it lived in Transport#execute, which an
+#     in-process schema bypasses entirely.
+#   - **branded errors** — a resolver raise was a bare RuntimeError,
+#     where the same failure over HTTP is a ServerError, so
+#     `rescue GraphWeaver::Error` caught one and missed the other.
+#
+# The original exception stays as #cause: in-process, the real backtrace
+# is usually the whole reason you're running in-process.
+class GraphWeaver::InProcess
+  include GraphWeaver::Parsing
+
+  # the schema queries run against, and the context handed to every one
+  attr_reader :schema, :context
+
+  def initialize(schema, context: {})
+    unless schema.respond_to?(:execute)
+      raise ArgumentError, "expected a graphql-ruby schema class, got #{schema.inspect}"
+    end
+
+    @schema = schema
+    @context = context
+  end
+
+  def execute(query, variables: {}, operation_name: nil)
+    operation_name ||= GraphWeaver::Transport.operation_name(query)
+    payload = { url: nil, schema: @schema.to_s, operation: operation_name }
+
+    GraphWeaver.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
+      perform(query, variables, operation_name, payload)
+    end
+  end
+
+  # The query itself. Separate from execute so the instrumenter wraps a
+  # call rather than a block this method returns out of.
+  private def perform(query, variables, operation_name, payload)
+    # same tag/truncation as the network transports, so one log reads the
+    # same whichever side of the seam a query ran on
+    tag = GraphWeaver.logger && GraphWeaver::Transport.log_tag(operation_name)
+
+    GraphWeaver.log(:debug) do
+      "in-process #{@schema} #{tag} variables=#{JSON.generate(variables)}\n" \
+        "#{GraphWeaver::Transport.truncate_for_log(query)}"
+    end
+
+    result = GraphWeaver.log_timed(:debug, "in-process #{@schema} #{tag} completed") do
+      @schema.execute(query, variables:, operation_name:, context: @context)
+    end
+
+    # the same key the network transports set, so one instrumenter
+    # subscriber reads both sides of the seam without branching — a
+    # resolver raise rides the ServerError(500) the hook already sees
+    payload[:status] = 200
+    result
+  rescue GraphWeaver::Error
+    raise
+  rescue => e
+    # a resolver blew up. The same failure over HTTP arrives as a 500, so
+    # raise what HTTP would — code that rescues GraphWeaver::Error, or
+    # branches on ServerError#status, behaves the same either side.
+    raise GraphWeaver::ServerError.new(status: 500, body: "#{e.class}: #{e.message}")
+  end
+
+  # never leak the context (session tokens, current_user) through logs or
+  # exceptions — an in-process client inspects as its schema, nothing more
+  def inspect = "#<#{self.class.name} schema=#{@schema}>"
+  alias to_s inspect
+end

data/lib/graph_weaver/input_struct.rb

@@ -27,12 +27,24 @@ module GraphWeaver
 
     # the wire hash — optional fields left nil stay off the wire
     def serialize
-      self.class.const_get(:FIELDS).each_with_object({}) do |field, wire|
+      wire = self.class.const_get(:FIELDS).each_with_object({}) do |field, out|
         value = public_send(field.prop)
         next if value.nil? && !field.required
 
-        wire[field.wire] = field.serializer && !value.nil? ? field.serializer.call(value) : value
+        out[field.wire] = field.serializer && !value.nil? ? field.serializer.call(value) : value
       end
+
+      # @oneOf declares "exactly one of these", but every field is nullable, so
+      # nothing before here can enforce it — not the struct's types, not the
+      # server until the round trip
+      if wire.size != 1 && self.class.const_defined?(:ONE_OF, false)
+        raise GraphWeaver::InputError.new(
+          "#{self.class} is @oneOf — supply exactly one field, got #{wire.empty? ? "none" : wire.keys.sort.join(", ")}",
+          struct: self.class,
+        )
+      end
+
+      wire
     end
     alias_method :to_h, :serialize
 

data/lib/graph_weaver/logging.rb

@@ -37,5 +37,34 @@ module GraphWeaver
       log(level) { "#{label} (#{ms}ms)" }
       result
     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:
+    #
+    #      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 carries :url (nil in-process),
+    # :schema (in-process only), :operation (the document's operation
+    # name, nil for an anonymous one), and — added after the response
+    # lands — :status. Never the query text or the variables: those
+    # carry PII and belong at debug on the logger, where they're gated.
+    attr_accessor :instrumenter
+
+    # Internal: wrap the block in the instrumenter, if one is set. The
+    # payload is a plain Hash the caller may add to inside the block.
+    def instrument(event, payload)
+      hook = instrumenter
+      return yield unless hook
+
+      hook.call(event, payload) { yield }
+    end
   end
+
+  # The one instrumentation event: a single GraphQL request, start to
+  # parsed response, whichever client slot served it.
+  EXECUTE_EVENT = "graph_weaver.execute"
 end