graph_weaver 0.5.0 → 0.6.0

data/lib/graph_weaver/internal.rb

@@ -0,0 +1,206 @@
+# typed: true
+# frozen_string_literal: true
+
+require "graphql"
+require "json"
+
+require_relative "inflect"
+
+module GraphWeaver
+  # Not API. Anything under GraphWeaver::Internal is the gem talking to
+  # itself and may change or vanish in any release — it is the home for a
+  # helper that would otherwise have to go public just because a second file
+  # needs it. bin/public-surface skips this namespace, so moving something
+  # here is how you take it off the locked public surface.
+  #
+  # Not private_constant: most of this gem defines its classes compactly
+  # (`class GraphWeaver::Codegen`), which puts GraphWeaver outside their
+  # 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
+    # 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
+      class << self
+        # Replace a file's contents in one step. The schema dump and a
+        # cassette are artifacts people commit, and File.write truncates
+        # before it writes — so an interrupted run, or a second writer (a
+        # rake task beside a running app, two Puma workers), can leave a
+        # half-written file that no longer parses. A rename is atomic on
+        # POSIX: a reader sees the old file or the new one, never a prefix.
+        def atomic_write(path, content)
+          tmp = File.join(File.dirname(path),
+            ".#{File.basename(path)}.#{Process.pid}.#{Thread.current.object_id}.tmp")
+          File.write(tmp, content)
+          File.rename(tmp, path)
+        ensure
+          File.unlink(tmp) if tmp && File.exist?(tmp)
+        end
+
+        # The closest entry in `dictionary` to `term` — a "did you mean"
+        # suggestion, or nil (also nil when did_you_mean isn't loadable). One
+        # home for the guard used by codegen validation, alias resolution,
+        # and the runtime prop hints.
+        def did_you_mean(dictionary, term)
+          return unless defined?(DidYouMean::SpellChecker)
+
+          DidYouMean::SpellChecker.new(dictionary: dictionary).correct(term).first
+        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.
+        #
+        #      person.graphql          => PersonQuery       (person_query.rb)
+        #      save_list_entry.graphql => SaveListEntryMutation
+        #                                 (save_list_entry_mutation.rb)
+        #
+        # Every naming site goes through here — generate!, parse(path), and
+        # load_queries! — so the constant a file produces is the same one
+        # whichever door you came in by, and the file it lands in matches it.
+        def generated_names(path, source)
+          base = File.basename(path, ".*")
+          suffix = operation_suffix(source)
+          ["#{Inflect.camelize(base)}#{suffix}", "#{base}_#{suffix.downcase}.rb"]
+        end
+
+        # just the module name — see generated_names
+        def module_name(path, source) = generated_names(path, source).first
+
+        # A path setting, as a real path: relative to GraphWeaver.root, which
+        # is the app root and not wherever the process was started. Every
+        # filesystem access on a configured path goes through here; the
+        # settings themselves keep returning what was configured, so an error
+        # message stays short and graphql.config.yml stays portable.
+        def resolve(path) = File.expand_path(path.to_s, GraphWeaver.root)
+
+        # The other half of that rule: a path this gem REPORTS — returned,
+        # logged, or quoted in an error — comes back in the short form the
+        # settings use, so a build log reads the same on the next machine and
+        # names something you can paste. A path outside the root (an absolute
+        # setting) is left as it is: relative to somewhere else it names no file.
+        def relative(path)
+          path = path.to_s
+          prefix = File.join(GraphWeaver.root, "") # trailing separator; "/" stays "/"
+          path.start_with?(prefix) ? path.delete_prefix(prefix) : path
+        end
+
+        # Every query document under these directories, sorted — the files
+        # generate!, verify_generated!, check_queries and load_queries! read.
+        def query_files(paths = GraphWeaver.queries_paths)
+          Array(paths).flat_map { |dir| Dir[File.join(resolve(dir), Codegen::DOCUMENT_GLOB)].sort }
+        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
+          # 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
+        end
+
+        private
+
+        # "Mutation" for a mutation document, "Query" for everything else.
+        def operation_suffix(source)
+          operation = GraphQL.parse(source).definitions
+            .grep(GraphQL::Language::Nodes::OperationDefinition).first
+          (operation&.operation_type == "mutation") ? "Mutation" : "Query"
+        rescue GraphQL::ParseError
+          "Query" # unparseable: codegen brands the real error a moment later
+        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
+    # miss can say, rather than on the class one of them happens to be.
+    module RequestKey
+      class << self
+        # The request's identity, exactly as the server sees it.
+        # operationName is part of that: it picks the operation the document
+        # runs, so two requests with identical text but different names are
+        # different requests. Derived, never stored — the file holds the
+        # request once, so a hand-edited entry can't disagree with what
+        # replay matches on.
+        def for(query, variables, operation_name = nil)
+          key = { "query" => normalize_query(query), "variables" => normalize_variables(variables) }
+          key["operationName"] = operation_name if operation_name
+          key
+        end
+
+        def for_entry(entry) = self.for(entry["query"], entry["variables"], entry["operationName"])
+
+        def normalize_query(query) = query.gsub(/\s+/, " ").strip
+
+        # JSON round-trip so symbol keys become strings — otherwise
+        # YAML.dump writes Ruby symbols the safe loader rejects on the next
+        # run, and lookup keys stay stable across processes
+        def normalize_variables(variables) = JSON.parse(JSON.generate(variables || {}))
+
+        # one readable line: an error naming a 60-line query is a wall, not a hint
+        def summarize(query, limit: 160)
+          normalized = normalize_query(query)
+          (normalized.length > limit) ? "#{normalized[0, limit]}…" : normalized
+        end
+      end
+    end
+
+    # The GraphQL wire format, either direction: what a request document
+    # says about itself, how the log refers to it, and the shape a response
+    # carries an error in. Lived on Transport and Router, both of which
+    # users touch — the worst place for it.
+    module Wire
+      # The name of the document's FIRST operation, nil when anonymous. Only
+      # the fallback for a raw query string handed straight to a transport —
+      # generated modules pass their OPERATION_NAME, parsed properly.
+      OPERATION_NAME_PATTERN = /\A\s*(?:query|mutation|subscription)\s+([A-Za-z_]\w*)/
+      private_constant :OPERATION_NAME_PATTERN
+
+      # Whether this document's operation writes — what Retry asks before
+      # repeating a request. Line-anchored rather than parsed: it runs on
+      # every request, and the only way to be wrong (a field literally named
+      # `mutation` opening a line) errs toward not retrying.
+      MUTATION_PATTERN = /^[ \t]*mutation\b/
+      private_constant :MUTATION_PATTERN
+
+      REQUEST_MUTEX = Mutex.new
+      private_constant :REQUEST_MUTEX
+
+      # keep debug readable: a 100-line introspection query would drown the
+      # log — the INFO introspection line already carries the timing
+      LOG_QUERY_LIMIT = 600
+      private_constant :LOG_QUERY_LIMIT
+
+      class << self
+        def operation_name(query) = query[OPERATION_NAME_PATTERN, 1]
+
+        def mutation?(query) = MUTATION_PATTERN.match?(query)
+
+        # one error in the shape a GraphQL response carries them
+        def graphql_error(message, code)
+          { "message" => message, "extensions" => { "code" => code } }
+        end
+
+        # "[req 3 FilteredPokemon]" — a per-process request id plus the
+        # operation name, when there is one
+        def log_tag(operation_name = nil)
+          id = REQUEST_MUTEX.synchronize { @request_count = (@request_count || 0) + 1 }
+          "[req #{id}#{" #{operation_name}" if operation_name}]"
+        end
+
+        def truncate_for_log(query)
+          return query if query.length <= LOG_QUERY_LIMIT
+
+          "#{query[0, LOG_QUERY_LIMIT]}... (truncated, #{query.bytesize} bytes total)"
+        end
+      end
+    end
+  end
+end

data/lib/graph_weaver/logging.rb

@@ -20,22 +20,25 @@ module GraphWeaver
     # carry PII. Auth headers never log.
     attr_accessor :logger
 
-    # Internal: level-gated and lazy — the block only runs when a logger
-    # is listening. Messages carry "graph_weaver" as progname.
-    def log(level, &block)
-      logger&.public_send(level, "graph_weaver", &block)
-    end
+    # What never reaches the log when variables are written at debug. A
+    # list of keys — Strings/Symbols match as case-insensitive substrings
+    # (`:token` covers `apiToken`), Regexps match themselves — applied at
+    # every depth, matched values replaced with "[FILTERED]":
+    #
+    #      GraphWeaver.filter_parameters = [:password, /token/]
+    #
+    # Rails apps need none of this: the railtie hands over the app's own
+    # config.filter_parameters. Anything answering #filter(hash) is taken
+    # as-is, which is how an ActiveSupport::ParameterFilter gets in.
+    attr_reader :filter_parameters
 
-    # Internal: run the block, logging "<label> (Nms)" at level — timing
-    # skipped entirely when no logger is set. Returns the block's value.
-    def log_timed(level, label)
-      return yield unless logger
+    def filter_parameters=(filters)
+      unless filters.nil? || filters.is_a?(Array) || filters.respond_to?(:filter)
+        raise ArgumentError,
+          "filter_parameters: takes a list of keys, or an object answering #filter — got #{filters.inspect}"
+      end
 
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = yield
-      ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
-      log(level) { "#{label} (#{ms}ms)" }
-      result
+      @filter_parameters = filters
     end
 
     # One callable wrapping every request GraphWeaver makes — over the
@@ -53,18 +56,103 @@ module GraphWeaver
     # 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
+  end
 
-    # 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
+  module Internal
+    # The message side of filter_parameters. One rule: a message the library
+    # composes about a value the caller supplied names that value only when
+    # the key it arrived under isn't filtered — so a password's rejection
+    # reads "[FILTERED]" in the exception, and in the warn line Error#initialize
+    # writes, exactly as it does in the debug log.
+    module Redact
+      class << self
+        # True when a value under this key must not appear in a message.
+        # Asked of filter_variables rather than of the list, so the
+        # ActiveSupport::ParameterFilter a Rails app hands over answers too.
+        def filtered?(key)
+          !key.nil? && Log.filter_variables({ key.to_s => nil })[key.to_s] == FILTERED
+        end
 
-      hook.call(event, payload) { yield }
+        # `detail` unless the key is filtered — free text a coercer or sorbet
+        # wrote can spell a value any way, so for a filtered key none of it
+        # survives, not the parts that would have been safe.
+        def detail(key, detail) = filtered?(key) ? FILTERED : detail
+      end
     end
   end
 
+  # Rails' spelling, so a scrubbed log reads the same either side of the seam
+  FILTERED = "[FILTERED]"
+
+  # Safe before anyone configures anything; substring matching means these
+  # already cover apiToken, client_secret, password_confirmation…
+  DEFAULT_FILTER_PARAMETERS = %i[password token secret authorization].freeze
+
+  self.filter_parameters = DEFAULT_FILTER_PARAMETERS
+
   # The one instrumentation event: a single GraphQL request, start to
   # parsed response, whichever client slot served it.
   EXECUTE_EVENT = "graph_weaver.execute"
+
+  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
+    # two read as a pair when they sit on the same object.
+    module Log
+      class << self
+        # Level-gated and lazy — the block only runs when a logger is
+        # listening. Messages carry "graph_weaver" as progname.
+        def log(level, &block)
+          GraphWeaver.logger&.public_send(level, "graph_weaver", &block)
+        end
+
+        # Run the block, logging "<label> (Nms)" at level — timing skipped
+        # entirely when no logger is set. Returns the block's value.
+        def log_timed(level, label)
+          return yield unless GraphWeaver.logger
+
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = yield
+          ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+          log(level) { "#{label} (#{ms}ms)" }
+          result
+        end
+
+        # 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 = GraphWeaver.instrumenter
+          return yield unless hook
+
+          hook.call(event, payload) { yield }
+        end
+
+        # variables with the filtered keys blanked out
+        def filter_variables(variables)
+          filters = GraphWeaver.filter_parameters
+          # Array before the duck-type check: Array#filter is Enumerable's, not ours
+          return filters.empty? ? variables : scrub(variables, filters) if filters.is_a?(Array)
+
+          filters.nil? ? variables : filters.filter(variables)
+        end
+
+        private
+
+        def scrub(value, filters)
+          case value
+          when Hash then value.to_h { |k, v| [k, filtered?(k, filters) ? FILTERED : scrub(v, filters)] }
+          when Array then value.map { |v| scrub(v, filters) }
+          else value
+          end
+        end
+
+        def filtered?(key, filters)
+          name = key.to_s
+          filters.any? do |filter|
+            filter.is_a?(Regexp) ? name.match?(filter) : name.downcase.include?(filter.to_s.downcase)
+          end
+        end
+      end
+    end
+  end
 end

data/lib/graph_weaver/parsing.rb

@@ -4,6 +4,7 @@
 require "sorbet-runtime"
 
 require_relative "codegen"
+require_relative "internal"
 
 module GraphWeaver
   # Anything that holds a schema parses against it. That's a Client, an
@@ -27,7 +28,7 @@ module GraphWeaver
     def parse(query, name: nil)
       # #schema is the mixin's one requirement of its includer, and a module
       # has no way to declare that short of an abstract interface
-      GraphWeaver.parse(schema: T.unsafe(self).schema, query:, name:, client: parse_client)
+      GraphWeaver.parse(schema: T.unsafe(self).schema, query:, name:, client: self)
     end
 
     # Parse every query in a directory (subdirectories included) into typed
@@ -41,27 +42,19 @@ module GraphWeaver
     # Reloadable (constants are replaced), so it suits consoles and dev.
     # Returns the modules.
     def load_queries!(dir = nil, namespace: Object)
-      GraphWeaver.query_files(dir || GraphWeaver.queries_paths).map do |path|
-        name = GraphWeaver.module_name(path, File.read(path))
+      GraphWeaver::Internal::Util.query_files(dir || GraphWeaver.queries_paths).map do |path|
+        name = GraphWeaver::Internal::Util.module_name(path, File.read(path))
         if namespace.const_defined?(name, false)
           # the constant moves, its instances don't — a struct built before the
           # reload keeps failing is_a? against the new module, silently
-          GraphWeaver.log(:info) do
+          GraphWeaver::Internal::Log.log(:info) do
             "replacing #{name} — objects built from the previous module stay instances of it"
           end
           namespace.send(:remove_const, name)
         end
-        GraphWeaver.log(:info) { "loaded #{name} from #{path}" }
+        GraphWeaver::Internal::Log.log(:info) { "loaded #{name} from #{GraphWeaver::Internal::Util.relative(path)}" }
         namespace.const_set(name, parse(path))
       end
     end
-
-    private
-
-    # What a parsed module executes through: this object, which holds the
-    # schema and runs queries. Client is the one that overrides it — its own
-    # #execute is the one-shot parse-and-run, not the client contract, so it
-    # bakes the transport it wraps.
-    def parse_client = self
   end
 end

data/lib/graph_weaver/query_module.rb

@@ -4,6 +4,8 @@
 require "sorbet-runtime"
 
 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

data/lib/graph_weaver/railtie.rb

@@ -7,15 +7,27 @@
 #   rake_tasks block, so graph_weaver:* tasks appear with no Rakefile
 #   edit. (Outside Rails there is no task-discovery hook — add
 #   `require "graph_weaver/tasks"` to your Rakefile.)
-# - generated modules: required at boot when a generated_paths entry exists,
-#   after config/initializers (registrations and GraphWeaver.client=
-#   run first — block-built type helpers must exist before the files
-#   that include them load). load_generated! stays idempotent, so
-#   calling it yourself too is harmless.
+# - generated modules: required at boot once every registration has run —
+#   both the initializer kind and the to_prepare kind, since a generated
+#   file `include`s the type helper it was generated with and that
+#   constant must resolve. load_generated! stays idempotent, so calling
+#   it yourself too is harmless.
 # - Zeitwerk: the generated directory is hidden from it, since the
 #   default one lives under app/ and its files define top-level
 #   constants.
+# - watch mode: in development, editing a .graphql regenerates before the
+#   next request, the way editing a route or a locale takes effect.
 class GraphWeaver::Railtie < Rails::Railtie
+  # config.graph_weaver.watch — false to never regenerate during a request.
+  # Default: development only.
+  config.graph_weaver = ActiveSupport::OrderedOptions.new
+
+  class << self
+    # The file watcher, so the to_prepare block below can ask it whether a
+    # query changed. nil when not watching.
+    attr_accessor :watcher
+  end
+
   rake_tasks do
     require "graph_weaver/tasks"
   end
@@ -29,7 +41,7 @@ class GraphWeaver::Railtie < Rails::Railtie
     Rails.autoloaders.each do |loader|
       # patterns, not paths — generated_paths may be globs, and Zeitwerk
       # expands its own at setup (which is what this runs before)
-      GraphWeaver.generated_paths.each { |path| loader.ignore(Rails.root.join(path).to_s) }
+      GraphWeaver.generated_paths.each { |path| loader.ignore(GraphWeaver::Internal::Util.resolve(path)) }
     end
   end
 
@@ -39,14 +51,101 @@ class GraphWeaver::Railtie < Rails::Railtie
     GraphWeaver.logger = Rails.logger if GraphWeaver.logger.nil?
   end
 
-  initializer "graph_weaver.load_generated", after: :load_config_initializers do
-    # The graph_weaver tasks write these files and need none of them loaded.
-    # Loading them would let a stale one block its own repair: a dropped
-    # extend_type leaves a dangling include, and generate depends on
-    # :environment, so boot failed before the task that would regenerate it.
-    next if GraphWeaver.skip_generated_load
+  # The app already declared what is sensitive, so variables logged at debug
+  # honour the same list as its request logs — including the Procs and dotted
+  # paths only ParameterFilter understands. after: :load_config_initializers,
+  # since filter_parameter_logging.rb is where an app adds to it.
+  initializer "graph_weaver.filter_parameters", after: :load_config_initializers do |app|
+    filters = app.config.filter_parameters
+    next if filters.empty? || GraphWeaver.filter_parameters != GraphWeaver::DEFAULT_FILTER_PARAMETERS
+
+    GraphWeaver.filter_parameters = ActiveSupport::ParameterFilter.new(filters)
+  end
+
+  # Watch mode. A .graphql edit should reach the next request the way a route
+  # or a locale change does, so the query directories and the schema dump
+  # become one of Rails' own reloaders: a change there alone triggers a reload
+  # cycle, and the to_prepare below regenerates before it loads. Off with
+  #
+  #      config.graph_weaver.watch = false
+  #
+  # after: :load_config_initializers — that's where an app moves
+  # queries_paths, and the finisher that reads app.reloaders runs later still.
+  initializer "graph_weaver.watch", after: :load_config_initializers do |app|
+    GraphWeaver::Railtie.watch!(app)
+  end
+
+  # Registers the watcher, and says so: this is the one thing GraphWeaver does
+  # that writes a checked-in file outside a rake task. Returns it, or nil when
+  # nothing is being watched.
+  def self.watch!(app)
+    watch = app.config.graph_weaver.watch
+    watch = Rails.env.development? if watch.nil?
+    # with reloading off nothing re-runs to_prepare, so a watcher could only
+    # promise something it can't do
+    return self.watcher = nil unless watch && app.config.reloading_enabled?
 
-    # entries may be globs, so Dir[] rather than Dir.exist?
-    GraphWeaver.load_generated! if GraphWeaver.generated_paths.any? { |path| Dir[path].any? }
+    # a directory that doesn't exist yet is still watched — FileUpdateChecker
+    # re-globs on every check, and its keys may themselves be globs
+    watched = GraphWeaver.queries_paths + GraphWeaver.fragments_paths
+    # the dump codegen would read, or where it goes once someone takes one
+    dump = GraphWeaver::SchemaLoader.locate_path || GraphWeaver.schema_path
+
+    dirs = watched.to_h { |path| [GraphWeaver::Internal::Util.resolve(path), %w[graphql gql]] }
+    self.watcher = app.config.file_watcher.new([GraphWeaver::Internal::Util.resolve(dump)], dirs) { regenerate! }
+    app.reloaders << watcher
+    GraphWeaver::Internal::Log.log(:info) do
+      "watching #{(watched << GraphWeaver::Internal::Util.relative(dump)).join(", ")} — an edit regenerates " \
+        "#{GraphWeaver.generated_paths.first} before the next request " \
+        "(config.graph_weaver.watch = false to stop)"
+    end
+    watcher
+  end
+
+  # Regenerate in place, and keep serving when a query doesn't compile: a file
+  # saved mid-edit shouldn't take the dev server down, and the modules already
+  # loaded are the ones that worked a keystroke ago. Nothing is half-written on
+  # that path — generation validates every query before it writes any file — so
+  # one error per save, and the next save that compiles takes.
+  def self.regenerate!
+    GraphWeaver.generate!
+    GraphWeaver.reload_generated!
+    changed = GraphWeaver.changed_files
+    GraphWeaver::Internal::Log.log(:info) do
+      next "generated modules already up to date" if changed.empty?
+
+      "regenerated #{changed.join(", ")}"
+    end
+  rescue GraphWeaver::Error => e
+    GraphWeaver::Internal::Log.log(:error) { "keeping the modules already loaded — #{e.message}" }
+  end
+
+  # A generated file `include`s the type helper it was generated with, so it
+  # can't load until that constant resolves — and both Zeitwerk's setup and
+  # the app's own to_prepare blocks (where extend_type/register_enum are told
+  # to register, Codegen::AUTOLOAD_HINT) happen after config/initializers.
+  # to_prepare, not `after:` a finisher initializer: naming one there makes
+  # tsort hoist it ahead of the app's own config/initializers. Re-running on
+  # each dev reload is free — require is idempotent — and picks up a module
+  # generated since boot.
+  initializer "graph_weaver.load_generated", after: :load_config_initializers do |app|
+    app.config.to_prepare do
+      # The graph_weaver tasks write these files and need none of them loaded.
+      # Loading them would let a stale one block its own repair: a dropped
+      # extend_type leaves a dangling include, and generate depends on
+      # :environment, so boot failed before the task that would regenerate it.
+      next if GraphWeaver.skip_generated_load
+
+      # Regenerate first, then load — and here rather than in the watcher's own
+      # to_run, so an extend_type or register_enum the app registers in its own
+      # to_prepare is already in place (that block was registered at
+      # :load_config_initializers, so it has run by now). A run that
+      # regenerated has already reloaded what it wrote.
+      next if GraphWeaver::Railtie.watcher&.execute_if_updated
+
+      # entries may be globs, so Dir[] rather than Dir.exist?
+      generated = GraphWeaver.generated_paths.any? { |dir| Dir[GraphWeaver::Internal::Util.resolve(dir)].any? }
+      GraphWeaver.load_generated! if generated
+    end
   end
 end

data/lib/graph_weaver/representation.rb

@@ -4,6 +4,8 @@
 require_relative "errors"
 
 module GraphWeaver
+  # Called by generated code — not semver'd for direct use.
+  #
   # Runtime for the generated `Representations` builders — the entity
   # references a federation `_entities(representations:)` query takes.
   #
@@ -13,6 +15,10 @@ module GraphWeaver
   # resolves it, neither is individually required) and a nested key set
   # (`organization { id }`, a sub-hash the kwarg's Hash type doesn't pin
   # down). Both land here.
+  #
+  # `InputError#struct` is the entity's GraphQL type name here, not a class: a
+  # representation is a Hash a module function builds, so there is no generated
+  # struct to name.
   module Representation
     # `key_sets` is the entity's @key field sets as dotted paths, in
     # declaration order — [["upc", "sku"], ["id"]] for a type keyed either
@@ -27,6 +33,25 @@ module GraphWeaver
       end
     end
 
+    # One key field's trip onto the wire: normalize whatever arrived into the
+    # type the sig promises — the sig itself is `.checked(:never)`, so this is
+    # the check — then serialize. A cast complains about the value alone
+    # ("expected an Int"), and a query can build several representations, so
+    # the refusal names this one and the field. nil passes through untouched:
+    # a missing key is `build`'s complaint to make, and it says more.
+    def self.field(type_name, name, value)
+      return if value.nil?
+
+      yield value
+    rescue StandardError => e
+      shown = value.inspect
+      got = " (got #{shown})" unless e.message.include?(shown)
+      raise InputError.new(
+        "#{type_name} representation #{name}: #{Internal::Redact.detail(name, "#{e.message}#{got}")}",
+        field: name, struct: type_name,
+      )
+    end
+
     def self.missing(values, paths) = paths.select { |path| dig(values, path).nil? }
     private_class_method :missing
 
@@ -57,7 +82,7 @@ module GraphWeaver
       if key_sets.one?
         InputError.new(
           "#{type_name} representation is missing @key #{gaps.first.map(&:inspect).join(", ")}",
-          field: gaps.first.one? ? gaps.first.first : nil,
+          field: gaps.first.one? ? gaps.first.first : nil, struct: type_name,
         )
       else
         alternatives = key_sets.zip(gaps).map do |paths, gap|
@@ -66,7 +91,10 @@ module GraphWeaver
           supplied = gap.size < paths.size
           "#{paths.map(&:inspect).join(" + ")}#{" (missing #{gap.map(&:inspect).join(", ")})" if supplied}"
         end
-        InputError.new("#{type_name} representation satisfies none of its @keys — supply #{alternatives.join(", or ")}")
+        InputError.new(
+          "#{type_name} representation satisfies none of its @keys — supply #{alternatives.join(", or ")}",
+          struct: type_name,
+        )
       end
     end
     private_class_method :incomplete

data/lib/graph_weaver/response.rb

@@ -51,6 +51,21 @@ module GraphWeaver
     sig { returns(T::Boolean) }
     def success? = errors.empty?
 
+    # The envelope decomposed, string-keyed like the error classes' #to_h:
+    # errors become JSON-ready hashes, extensions pass through, and data
+    # stays the typed struct.
+    #
+    # Data is NOT re-serialized: T::Struct#serialize is the wrong inverse
+    # here — props are snake_case where the wire is camelCase, nil fields
+    # drop out, and a registered scalar keeps whatever Ruby object its codec
+    # built. The result would look like the server's response and not be one.
+    # Serialize the typed data yourself, or keep the raw hash and hand it to
+    # .from_response when you need both.
+    sig { returns(T::Hash[String, T.untyped]) }
+    def to_h
+      { "data" => data, "errors" => errors.map(&:to_h), "extensions" => extensions }
+    end
+
     # The typed result, or raise QueryError if the response carried top-level
     # errors (partial data and extensions ride along on the error).
     sig { returns(Data) }