graph_weaver 0.7.3 → 0.7.5

data/lib/graph_weaver/coerce.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "date" # Date/DateTime, named below
+require "time" # Time.iso8601
 
 require_relative "errors"
 require_relative "internal/refusal"
@@ -38,19 +39,24 @@ module GraphWeaver
       # app translates for a user. It defaults to the GraphQL scalar the rule
       # is named for; generated code passes the schema's own name, so a
       # `register_scalar("BigInt", Integer)` field refuses as a BigInt.
+      #
+      # A real number converts to the number the scalar names, and whether it
+      # is whole is asked of the value — so a BigDecimal off a decimal column
+      # and a Rational are ordinary arguments.
       def integer(value, scalar = "Int")
         case value
         when Integer then value
-        when Float then whole(value, scalar)
+        when Numeric then whole(real(value, scalar), scalar)
         when String then INTEGER.match?(value.strip) ? Integer(value.strip, 10) : unparseable(value, scalar)
         else refuse(value, scalar)
         end
       end
 
+      # Float's own precision is what asking for a Float means, so a BigDecimal
+      # past it loses digits here rather than being refused.
       def float(value, scalar = "Float")
         case value
-        when Float then finite(value, scalar)
-        when Integer then finite(value.to_f, scalar)
+        when Numeric then finite(real(value, scalar).to_f, scalar)
         when String then NUMBER.match?(value.strip) ? finite(Float(value.strip), scalar) : unparseable(value, scalar)
         else refuse(value, scalar)
         end
@@ -70,12 +76,16 @@ module GraphWeaver
         end
       end
 
+      # A timestamp string is ISO 8601, read by Time.iso8601 — the coercer
+      # graphql-ruby's own ISO8601DateTime reads input with, and the only
+      # shape its coerce_result writes. Time.parse also reads "Jan 15 2024
+      # 10:20", which no server sends and no generated struct should take.
       def time(value, scalar = "Time")
         case value
         when Time then value
         when DateTime then value.to_time # the same instant in another class
         when Date then cross(value, scalar, TIME_HINT)
-        when String then parsing(scalar, value) { Time.parse(value) }
+        when String then parsing(scalar, value) { Time.iso8601(value) }
         else time_like?(value) ? value.to_time : refuse(value, scalar)
         end
       end
@@ -194,8 +204,17 @@ module GraphWeaver
         raise mismatch(ArgumentError, "#{expected(scalar)}, got #{shown(value)} — not a finite number", scalar)
       end
 
+      # Complex is the one Numeric that is not a number a scalar can name, and
+      # #real? is the predicate for it — no class list to keep up to date.
+      def real(value, scalar)
+        return value if value.real?
+
+        refuse(value, scalar)
+      end
+
       def whole(value, scalar = "Int")
-        # Integer(2.5) is 2 — a silent loss where refusing costs nothing
+        # Integer(2.5) is 2 — a silent loss where refusing costs nothing. `% 1`
+        # is exact for a BigDecimal and a Rational; asking Float would not be.
         return value.to_i if value.finite? && (value % 1).zero?
 
         raise mismatch(ArgumentError, "#{expected(scalar)}, got #{shown(value)} — not a whole number", scalar)
@@ -236,7 +255,7 @@ module GraphWeaver
 
       # the article by the initial, so a registered Ruby class ("an Integer")
       # reads as well as the scalars ("an Int", "an ID", "a Date")
-      def expected(scalar) = "expected #{scalar.start_with?(/[AEIOU]/) ? "an" : "a"} #{scalar}"
+      def expected(scalar) = "expected #{Internal::Util.article(scalar)} #{scalar}"
     end
   end
 end

data/lib/graph_weaver/federation.rb

@@ -341,15 +341,10 @@ module GraphWeaver
           *@skipped.sort.map { |name, what| "  #{name} (#{evidence(what)})" }]
       end
 
-      # how many coordinates the report names before it says "and N more"
-      SAMPLE = 5
-      private_constant :SAMPLE
-
       def evidence(coordinates)
         return "the supergraph attributes nothing to it alone" if coordinates.empty?
-        return coordinates.join(", ") if coordinates.size <= SAMPLE
 
-        "#{coordinates.first(SAMPLE).join(", ")} and #{coordinates.size - SAMPLE} more"
+        Internal::Util.sample(coordinates)
       end
 
       def faked_section

data/lib/graph_weaver/graph.rb

@@ -54,12 +54,15 @@ module GraphWeaver
     # block runs once, at the declaration (GraphBuilder.build reads the
     # registry there), and every read after replays the module it made.
     def replay(registry, registration)
-      call, args, kwargs, block = registration
+      call, args, kwargs, block, aliases = registration
       entry = registry.public_send(call, *args, **kwargs, &block)
+      # the block's alias_field lines ran with it, so replay them too
+      entry[:aliases].merge!(aliases) if aliases
       return unless block && call == :extend_type
 
       registration[1] = args + [entry[:mixins].last]
       registration[3] = nil
+      registration[4] = entry[:aliases].dup
     end
     private :replay
 

data/lib/graph_weaver/hints.rb

@@ -68,20 +68,38 @@ module GraphWeaver
     # you generated) rather than a bad value, and T::Enum's own KeyError says
     # neither that nor which values exist. Raised bare so the enclosing
     # Hints.field brands it with the field.
-    def self.enum(type, value)
-      type.try_deserialize(value) || drifted!(type, value, type.values.map(&:serialize))
+    # aliases (register_enum alias:) is wire spelling => the value it reads as.
+    # fallback is the Other member, when the registration asked for one.
+    def self.enum(type, value, aliases = nil, fallback: nil)
+      value = aliases.fetch(value, value) if aliases
+      member = type.try_deserialize(value)
+      return member if member
+      return absorbed(type, value, fallback) if fallback
+
+      drifted!(type, value, type.values.map(&:serialize), "register_enum fallback: true")
     end
 
     # the same, for an enum mapped onto an app-owned T::Enum, where the wire
     # table rather than the type knows the accepted values
     def self.mapped_enum(type, table, value)
-      table.fetch(value) { drifted!(type, value, table.keys) }
+      table.fetch(value) { drifted!(type, value, table.keys, "register_enum fallback:") }
     end
 
-    def self.drifted!(type, value, values)
+    # A T::Enum member is a singleton, so Other can't carry the value it
+    # swallowed — this line is the only record that anything drifted.
+    def self.absorbed(type, value, fallback)
+      GraphWeaver::Internal::Log.log(:debug) do
+        # the member's bare constant name — a T::Enum member inspects as #<Type::Name>
+        "#{type} absorbed #{GraphWeaver::Internal::Redact.shown(value)} into #{fallback.inspect[/::(\w+)>\z/, 1]}"
+      end
+      fallback
+    end
+    private_class_method :absorbed
+
+    def self.drifted!(type, value, values, suggestion)
       raise KeyError, "#{GraphWeaver::Internal::Redact.shown(value)} is not a #{type} — expected one of: " \
         "#{values.sort.join(", ")}; a value the server added since you generated " \
-        "needs a regenerate, or register_enum fallback: to absorb them"
+        "needs a regenerate, or #{suggestion} to absorb them"
     end
     private_class_method :drifted!
 

data/lib/graph_weaver/in_process.rb

@@ -72,14 +72,12 @@ class GraphWeaver::InProcess
         "#{GraphWeaver::Internal::Wire.truncate_for_log(query)}"
     end
 
-    result = GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
+    GraphWeaver::Internal::Log.log_timed(:debug, "in-process #{schema_label} #{tag} completed") do
       # a copy per query: graphql-ruby writes a resolver's `context[...] =`
       # into the hash it is handed, and one client serves every request
       @schema.execute(query, variables:, operation_name:,
         context: GraphWeaver::Internal::Util.context!(@context).dup)
     end
-
-    result
   rescue GraphWeaver::Error
     raise
   rescue => e

data/lib/graph_weaver/input_struct.rb

@@ -21,19 +21,25 @@ module GraphWeaver
 
     # serializer/coercer are code-as-data from the generated file; nil
     # means identity (the wire value passes through untouched). coordinate
-    # is the schema's name for the slot ("PetFilter.species"), so a refusal
-    # can say where it happened without reflecting at runtime.
-    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate)
+    # is the schema's name for the slot ("PetFilter.species") and type its
+    # spelling of what goes there ("[Float!]!"), so a refusal can say where
+    # it happened, and in whose vocabulary, without reflecting at runtime.
+    Field = Data.define(:prop, :wire, :required, :serializer, :coercer, :coordinate, :type)
 
     # An enum reaching the library as input — an execute kwarg or an input
     # field — as the member or its wire value. Generated code calls these
     # rather than T::Enum.deserialize / the wire table directly: both raise a
     # bare KeyError naming an anonymous module and none of the values they
     # would have taken.
-    def self.enum(type, value)
-      return value if value.is_a?(type)
-
-      type.try_deserialize(value) || invalid_enum!(type, value, type.values.map(&:serialize))
+    # fallback is the generated Other member (register_enum fallback: true).
+    # It is the one member input refuses: nothing on the wire means it, so a
+    # variable carrying it would send a value the server never declared.
+    def self.enum(type, value, aliases = nil, fallback: nil)
+      member = value.is_a?(type) ? value : type.try_deserialize(aliases ? aliases.fetch(value, value) : value)
+      return member if member && !member.equal?(fallback)
+
+      accepted = type.values.map(&:serialize) - [fallback&.serialize].compact
+      member ? unsendable_enum!(member, accepted) : invalid_enum!(type, value, accepted)
     end
 
     # A list element's index, prepended when something inside it refused —
@@ -107,6 +113,18 @@ module GraphWeaver
     end
     private_class_method :invalid_enum!
 
+    # The fallback member is a landing pad for drift, not a value — so it is
+    # refused by name rather than listed among the ones you could have meant.
+    def self.unsendable_enum!(member, accepted)
+      # a T::Enum member inspects as #<Type::Name>
+      raise GraphWeaver::Internal::Refusal.brand(
+        KeyError.new("#{member.inspect[2..-2]} absorbs values the server added, so " \
+          "there is nothing to send for it — expected one of: #{accepted.sort.join(", ")}"),
+        :not_a_member, members: accepted.sort,
+      )
+    end
+    private_class_method :unsendable_enum!
+
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -260,11 +278,14 @@ module GraphWeaver
           # out blaming the list that held the struct, in sorbet's words.
           next if T::Utils.coerce(info[:type_object]).recursively_valid?(value)
 
-          type = T::Utils.coerce(info[:type]).to_s
+          # the SCHEMA's spelling, from the FIELDS row — #details[:type] is
+          # what an app translates for a user, and "T::Array[Float]" is the
+          # library's vocabulary leaking into theirs
+          field = T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }
+          type = field&.type || T::Utils.coerce(info[:type]).to_s
           return GraphWeaver::InputError.new(
             "#{prop}: expected #{type}, got #{GraphWeaver::Internal::Redact.shown(value, prop)}",
-            kind: :type_mismatch, path: [prop.to_s],
-            coordinate: T.unsafe(self).const_get(:FIELDS).find { |f| f.prop == prop }&.coordinate,
+            kind: :type_mismatch, path: [prop.to_s], coordinate: field&.coordinate,
             value: GraphWeaver::Internal::Redact.value(prop, value),
             details: { type: }, struct: self,
           )

data/lib/graph_weaver/internal/subgraphs.rb

@@ -34,9 +34,6 @@ module GraphWeaver
     # goes through the same check *and refuses at construction* — a swapped
     # pair fails there rather than as a mystery three fetches later.
     module Subgraphs
-      # how many coordinates a message names before it says "and N more"
-      SAMPLE = 5
-
       # answer this subgraph with fabricated data rather than refusing
       FAKE = :fake
 
@@ -117,15 +114,9 @@ module GraphWeaver
           return schema if gaps.empty?
 
           raise GraphWeaver::ConfigurationError, "subgraphs[#{name.inspect}] is " \
-            "#{schema.name || schema.inspect}, which doesn't define #{sample(gaps)} — the supergraph " \
+            "#{schema.name || schema.inspect}, which doesn't define #{Util.sample(gaps)} — the supergraph " \
             "says #{name} resolves them. Did two entries get swapped?"
         end
-
-        def sample(list)
-          return list.join(", ") if list.size <= SAMPLE
-
-          "#{list.first(SAMPLE).join(", ")} and #{list.size - SAMPLE} more"
-        end
       end
     end
   end

data/lib/graph_weaver/internal/unused.rb

@@ -47,6 +47,11 @@ module GraphWeaver
       # .json.erb's sibling JS — is a blind spot, and the footer says so.
       # .rake and .builder are Ruby too.
       EXTENSIONS = %w[.rb .rake .builder .erb .slim .haml .jbuilder].freeze
+      # Ruby that carries no extension to recognise it by. In a non-Rails
+      # project the entry points live here, so skipping them skipped the
+      # files that read the query.
+      SCRIPT_DIRS = Set["bin", "exe"].freeze
+      RUBY_SHEBANG = /\A#!.*\bruby\b/
       # Directories that hold no app source. "generated" covers both a graph's
       # own output under the convention and a spec/generated fixture dir; a
       # graph that writes somewhere else is pruned by #outputs.
@@ -60,8 +65,9 @@ module GraphWeaver
       # difference between a lint and a number somebody trusts.
       FOOTER = "This is a lint, not a proof — it matches prop names as text, so a common name reads " \
         "as\nused the moment anything says it. It can't see a prop reached by public_send, or a " \
-        "read\nin a file type it doesn't sweep (#{EXTENSIONS.join(", ")}). On a real app half to " \
-        "two\nthirds of genuinely unread selections go unreported; silence is the safe direction."
+        "read\nin a file type it doesn't sweep — #{EXTENSIONS.join(", ")},\nplus Ruby with no " \
+        "extension (any name under bin/ or exe/, a ruby shebang elsewhere). On\na real app half to " \
+        "two thirds of genuinely unread selections go unreported; silence is\nthe safe direction."
 
       # query: the .graphql that selected it. struct/prop: where it landed.
       # wire: how the query spells that prop, when it differs.
@@ -244,19 +250,22 @@ module GraphWeaver
       end
 
       def files
-        @files ||= @roots.flat_map { |root| collect(root, []) }.uniq.sort
+        @files ||= @roots
+          .flat_map { |root| collect(root, [], SCRIPT_DIRS.include?(File.basename(root))) }
+          .uniq.sort
       end
 
       # Pruned as it walks rather than globbed and filtered: node_modules is
-      # the directory you most want never to descend into.
-      def collect(dir, found)
+      # the directory you most want never to descend into. scripts says we are
+      # inside bin/ or exe/, which the walk knows and a path doesn't.
+      def collect(dir, found, scripts)
         Dir.children(dir).sort.each do |entry|
           path = File.join(dir, entry)
           # lstat, so a symlinked directory can't loop the walk
           stat = File.lstat(path)
           if stat.directory?
-            collect(path, found) unless skip_dir?(entry, path)
-          elsif stat.file? && EXTENSIONS.include?(File.extname(entry))
+            collect(path, found, scripts || SCRIPT_DIRS.include?(entry)) unless skip_dir?(entry, path)
+          elsif stat.file? && ruby?(path, entry, scripts)
             found << path
           end
         end
@@ -265,6 +274,22 @@ module GraphWeaver
         found
       end
 
+      # An extension names most of it. A file with none is Ruby if it sits
+      # under bin/ or exe/ — that is what those directories are for — or if
+      # its first line says so.
+      def ruby?(path, entry, scripts)
+        return true if EXTENSIONS.include?(File.extname(entry))
+        return false unless File.extname(entry).empty?
+
+        scripts || shebang?(path)
+      end
+
+      def shebang?(path)
+        File.open(path) { |file| file.gets(chomp: true) }&.match?(RUBY_SHEBANG) || false
+      rescue SystemCallError, ArgumentError
+        false
+      end
+
       def skip_dir?(entry, path) = entry.start_with?(".") || SKIP.include?(entry) || outputs.include?(path)
 
       # The generated directories a name check can't catch: a graph that sets

data/lib/graph_weaver/internal/values.rb

@@ -51,8 +51,16 @@ class GraphWeaver::Internal::Values
   UNREGISTERED = "T.untyped"
 
   # What JSON can hold. Anything else a pin offers is a Ruby object the
-  # registration has to serialize before it can stand in for a response.
-  WIRE = [NilClass, TrueClass, FalseClass, Numeric, String, Symbol, Array, Hash].freeze
+  # registration has to serialize before it can stand in for a response —
+  # Integer and Float, not Numeric, because a BigDecimal is a Numeric that
+  # JSON has no spelling for, and taking one as written sent 12.5 where the
+  # registration says the server writes "12.5".
+  WIRE = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol, Array, Hash].freeze
+
+  # Whether a value is already one of those. At a leaf it means the registry's
+  # serializer has nothing to do; at a composite position (FakeClient) it means
+  # the pin stands as written.
+  def self.wire?(value) = WIRE.any? { |klass| value.is_a?(klass) }
 
   # The fallback, for a scalar nobody registered: its prop is T.untyped, so
   # anything holds and a plausible shape beats a placeholder.
@@ -143,10 +151,10 @@ class GraphWeaver::Internal::Values
   # as written. Shared with the object-pin door, so both read a pin the same
   # way.
   def wire(type_name, value, coordinate = nil)
-    return value if WIRE.any? { |klass| value.is_a?(klass) }
+    return value if self.class.wire?(value)
 
     serialized = @registry.scalar(type_name, coordinate).serialize_value(value)
-    return serialized if WIRE.any? { |klass| serialized.is_a?(klass) }
+    return serialized if self.class.wire?(serialized)
 
     article = GraphWeaver::Internal::Util.article(value.class.to_s)
     raise GraphWeaver::Error, "the pin for #{type_name.inspect} is #{article} #{value.class}, and a pin " \

data/lib/graph_weaver/internal.rb

@@ -18,6 +18,11 @@ module GraphWeaver
   # lexical scope, so a private constant would be unreachable from exactly
   # the files that need it. The name and the surface lock carry the rule.
   module Internal
+    # The wire value the member register_enum fallback: true adds to a
+    # generated enum serializes to. The GraphQL spec reserves a leading `__`,
+    # so no schema can declare a value that collides with it.
+    ENUM_FALLBACK_WIRE = "__other__"
+
     # Odds and ends several files share. Each is here because more than one
     # caller needs it, not because it belongs together with the others.
     module Util
@@ -50,6 +55,18 @@ module GraphWeaver
         # "a" or "an" for a word an error message is about to name.
         def article(word) = word.downcase.start_with?(/[aeiou]/) ? "an" : "a"
 
+        # how many entries a message names before it says "and N more"
+        SAMPLE = 5
+        private_constant :SAMPLE
+
+        # A list a message names inline, held to a readable length — a wall
+        # of schema coordinates says less than the first few and a count.
+        def sample(list)
+          return list.join(", ") if list.size <= SAMPLE
+
+          "#{list.first(SAMPLE).join(", ")} and #{list.size - SAMPLE} more"
+        end
+
         # The module a .graphql file generates, and the basename of the file
         # it generates into: the camelized file name plus the operation's own
         # word. Every run of non-alphanumerics in the name is a word boundary,
@@ -299,6 +316,73 @@ module GraphWeaver
       end
     end
 
+    # One query, checked against one schema. Both doors onto it —
+    # GraphWeaver.check_queries (every file on disk) and Client#check_query
+    # (a string) — report the same hashes and brand subgraphs the same way,
+    # because the implementation lives here rather than once each.
+    module QueryCheck
+      class << self
+        # A query's schema-validation errors as JSON-ready hashes, with the
+        # source position graphql-ruby reports. Unparseable counts as an error
+        # too — it doesn't validate either, and inline_fragments (which parses
+        # first) has already branded it with its position.
+        def errors(schema, source, shared, table = nil)
+          # path omitted: check_queries keys its report by file, so branding the
+          # message with it too would just print the path twice
+          schema.validate(Codegen.inline_fragments(source, shared)).map do |error|
+            detail = error.to_h
+            location = detail["locations"]&.first || {}
+            subgraphs = table ? attribute(table, detail["extensions"]) : []
+            entry = {
+              "message" => subgraphs.empty? ? error.message : "#{error.message} (#{subgraphs.join(", ")})",
+              "line" => location["line"],
+              "column" => location["column"],
+            }
+            subgraphs.empty? ? entry : entry.merge("subgraphs" => subgraphs)
+          end
+        rescue GraphWeaver::QueryValidationError => e
+          # an unparseable query: codegen folds the position (and the file) into
+          # the message, and this report keeps them separate — same splitter the
+          # rendered error uses, so the two can't drift apart
+          e.errors.map do |detail|
+            _path, _position, message = GraphWeaver::QueryValidationError.split(detail)
+            detail.transform_keys(&:to_s).merge("message" => message)
+          end
+        end
+
+        # The routing table behind a dump path, when the dump is a composed
+        # supergraph: it says who resolves what, so a validation error can name
+        # the subgraph whose code to look at. nil for anything else — a plain
+        # schema, a url client, a live class are all unaffected.
+        def routing_table_for(path)
+          path = path.to_path if path.respond_to?(:to_path)
+          return unless path&.end_with?(".graphql", ".gql")
+
+          sdl = File.read(path)
+          SchemaLoader.routing_table(sdl) if SchemaLoader.federation_sdl?(sdl)
+        end
+
+        private
+
+        # Which subgraphs a validation error is about, on a federated schema:
+        # "Field 'weight' doesn't exist on type 'Product'" is much less useful
+        # than the same line plus "(products)" — whose code to look at, whose
+        # team to talk to. graphql-ruby reports the coordinate structurally, so
+        # this is a lookup rather than message parsing. Both halves of the
+        # coordinate are required: an argument error reports typeName "Field"
+        # (the AST node kind, not a type), and looking that up would attribute
+        # confidently and wrongly.
+        def attribute(table, extensions)
+          return [] unless extensions
+
+          type_name, field_name = extensions.values_at("typeName", "fieldName")
+          return [] unless type_name && field_name
+
+          table.responsible(type_name, field_name)
+        end
+      end
+    end
+
     # What makes two GraphQL requests the same request — and how one reads
     # when an error has to quote it. A cassette matches on this, so the
     # rules belong somewhere both the cassette and the error that reports a

data/lib/graph_weaver/logging.rb

@@ -101,7 +101,11 @@ module GraphWeaver
         # about the key the value arrived under, so it reads a filtered key one
         # level in as safe; this scrubs at every depth, like #value. The key is
         # optional because a coercer refusing a value hasn't been told one.
-        def shown(raw, key = nil) = filtered?(key) ? FILTERED : cap(value(key, raw).inspect)
+        def shown(raw, key = nil) = filtered?(key) ? FILTERED : cap(spell(value(key, raw)))
+
+        # How a value reads inside a sentence. inspect, except that
+        # BigDecimal#inspect is scientific ("0.25e1" for the 2.5 a caller wrote).
+        def spell(value) = defined?(BigDecimal) && value.is_a?(BigDecimal) ? value.to_s("F") : value.inspect
 
         # A short server-chosen string the library republishes inside its own
         # text — the APM's :code, the [CODE] in the one line info writes, a
@@ -215,36 +219,13 @@ module GraphWeaver
         end
 
         # What a Retry has already spent, read by the attempt it is about
-        # to make. A dynamic extent rather than a global: the count is only
-        # visible while the call it describes is on the stack, so a client
-        # that never reaches instrument can't leave a stale one behind.
-        def with_retries(count)
-          return yield unless GraphWeaver.instrumenter
-
-          previous = Thread.current[RETRIES]
-          Thread.current[RETRIES] = count
-          begin
-            yield
-          ensure
-            Thread.current[RETRIES] = previous
-          end
-        end
+        # to make.
+        def with_retries(count, &block) = during(RETRIES, count, &block)
 
         # The graph a generated module is dispatching, read by the request it
-        # is about to make. Same dynamic extent as with_retries, for the same
-        # reason — and instrument clears it for the duration of the request it
-        # labels, so exactly one request wears the label.
-        def with_graph(name)
-          return yield unless GraphWeaver.instrumenter
-
-          previous = Thread.current[GRAPH]
-          Thread.current[GRAPH] = name
-          begin
-            yield
-          ensure
-            Thread.current[GRAPH] = previous
-          end
-        end
+        # is about to make — and instrument clears it for the duration of the
+        # request it labels, so exactly one request wears the label.
+        def with_graph(name, &block) = during(GRAPH, name, &block)
 
         # The variables as one JSON line for a log: filtered, and unable to
         # raise. A value with no JSON form (NaN, binary) is the caller's bug
@@ -278,6 +259,22 @@ module GraphWeaver
 
         private
 
+        # One fiber-local, set for the length of one call. A dynamic extent
+        # rather than a global: the value is only visible while the call it
+        # describes is on the stack, so a client that never reaches instrument
+        # can't leave a stale one behind.
+        def during(key, value)
+          return yield unless GraphWeaver.instrumenter
+
+          previous = Thread.current[key]
+          Thread.current[key] = value
+          begin
+            yield
+          ensure
+            Thread.current[key] = previous
+          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

data/lib/graph_weaver/query_module.rb

@@ -7,8 +7,6 @@ require_relative "internal"
 require_relative "internal/test_clients"
 
 module GraphWeaver
-  # Called by generated code — not semver'd for direct use.
-  #
   # Runtime for generated query modules: the client plumbing, which is the
   # one part of a generated module that carries no per-query type
   # information — every module's copy was identical. `extend
@@ -16,6 +14,13 @@ module GraphWeaver
   # stay generated, since their sigs are the query's types and those are the
   # point.
   #
+  # It is also the type every generated module satisfies, so code that takes
+  # any of them says `GraphWeaver::QueryModule` and reads `query_string` /
+  # `operation_name` with a sig behind each — rather than `const_get(:QUERY)`
+  # on a Module, which is what rubocop-sorbet forbids (ConstantsFromStrings,
+  # and ForbidTUnsafe for the T.unsafe that gets around it). Those readers
+  # and `client` are the supported surface; the rest is generated code's.
+  #
   # Resolution order, per the docs: per call → a test mode's stand-in
   # (Internal::TestClients) → the client the module's graph names →
   # `GraphWeaver.client`. A module has no fifth slot you can set: a parsed
@@ -32,6 +37,18 @@ module GraphWeaver
       @client || default_client
     end
 
+    # The operation, verbatim — what goes on the wire as `query`.
+    sig { returns(String) }
+    def query_string
+      T.unsafe(self).const_get(:QUERY)
+    end
+
+    # What goes on the wire as `operationName`; nil for an anonymous operation.
+    sig { returns(T.nilable(String)) }
+    def operation_name
+      T.unsafe(self).const_get(:OPERATION_NAME)
+    end
+
     private
 
     # Bound by GraphWeaver.parse, which is the only caller: a parsed module
@@ -59,12 +76,10 @@ module GraphWeaver
       # comes through here.)
       GraphWeaver::Internal::Wire.check_variables!(variables)
 
-      mod = T.unsafe(self)
       # 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(mod.const_get(:QUERY), variables:,
-          operation_name: mod.const_get(:OPERATION_NAME))
+        client_for(client).execute(query_string, variables:, operation_name:)
       end
     end
 

data/lib/graph_weaver/railtie.rb

@@ -35,7 +35,7 @@ class GraphWeaver::Railtie < Rails::Railtie
     KEYS = %i[watch].freeze
 
     def method_missing(name, *args)
-      key = name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym
+      key = setting(name)
       return super if KEYS.include?(key)
 
       raise ArgumentError, refusal(key)
@@ -53,11 +53,16 @@ class GraphWeaver::Railtie < Rails::Railtie
     alias_method :store, :[]=
 
     def respond_to_missing?(name, _private = false)
-      KEYS.include?(name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym)
+      KEYS.include?(setting(name))
     end
 
     private
 
+    # the setting a reader, writer or predicate is about
+    def setting(name)
+      name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym
+    end
+
     def refusal(key)
       near = GraphWeaver::Internal::Util.did_you_mean(KEYS.map(&:to_s), key.to_s)
       fix =

data/lib/graph_weaver/rspec.rb

@@ -592,7 +592,6 @@ module GraphWeaver
           "may itself be a proc, so it can vary per request."
       end
       private_class_method :wire_context!
-
     end
   end
 end