graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/query_module.rb

@@ -3,6 +3,9 @@
 
 require "sorbet-runtime"
 
+require_relative "internal"
+require_relative "internal/test_clients"
+
 module GraphWeaver
   # Called by generated code — not semver'd for direct use.
   #
@@ -14,7 +17,8 @@ module GraphWeaver
   # those are the point.
   #
   # Resolution order, per the docs: per call → per module (`MyQuery.client =`)
-  # → the module's baked DEFAULT_CLIENT → `GraphWeaver.client`.
+  # → a test mode's stand-in (Internal::TestClients) → the module's baked
+  # DEFAULT_CLIENT → `GraphWeaver.client`.
   module QueryModule
     extend T::Sig
 
@@ -30,13 +34,43 @@ module GraphWeaver
 
     private
 
+    # 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.
+    #
+    # 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:)
+      # 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)
+
+      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
+      graph = mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
+
+      GraphWeaver::Internal::Log.with_graph(graph) do
+        client_for(client).execute(mod.const_get(:QUERY), variables:,
+          operation_name: mod.const_get(:OPERATION_NAME))
+      end
+    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
-    # inside the call.
+    # inside the call — and put through Client.instrumented, the one place a
+    # bare schema class gets the seam it has no way to carry itself.
     sig { params(override: T.untyped).returns(T.untyped) }
     def client_for(override)
-      target = override || client
+      target = GraphWeaver::Client.instrumented(override || client)
       return target if target.respond_to?(:execute)
 
       # Kernel.raise: this module is extended into another, so sorbet can't
@@ -48,9 +82,16 @@ module GraphWeaver
     # Codegen's `client:` constant, emitted as a DEFAULT_CLIENT lambda so the
     # constant it names is resolved on first use rather than at load — a
     # generated file may load before the initializer that builds the client.
+    #
+    # A test mode stands in for it: what codegen baked in is exactly what a
+    # `graphql:` tag means to replace, so a bound module is covered by the
+    # tag like every other one.
     sig { returns(T.untyped) }
     def default_client
       mod = T.unsafe(self)
+      stand_in = GraphWeaver::Internal::TestClients.for(mod)
+      return stand_in if stand_in
+
       mod.const_defined?(:DEFAULT_CLIENT, false) ? mod.const_get(:DEFAULT_CLIENT).call : GraphWeaver.client!
     end
   end

data/lib/graph_weaver/railtie.rb

@@ -19,36 +19,217 @@
 #   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
+  # Default: development only. Every other setting is a top-level one, and an
+  # OrderedOptions would take `config.graph_weaver.queries_paths = ...` without
+  # a word and do nothing with it, so this refuses what it doesn't read.
+  class Options < ActiveSupport::OrderedOptions
+    KEYS = %i[watch].freeze
+
+    def method_missing(name, *args)
+      key = name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym
+      return super if KEYS.include?(key)
+
+      raise ArgumentError, refusal(key)
+    end
+
+    # the other door: `config.graph_weaver[:queries_paths] = ...` reaches
+    # Hash#[]= without passing method_missing, and was the exact silent no-op
+    # the refusal exists to prevent. store is Hash's own synonym for it, so it
+    # stays one.
+    def []=(key, value)
+      raise ArgumentError, refusal(key) unless KEYS.include?(key.to_sym)
+
+      super
+    end
+    alias_method :store, :[]=
+
+    def respond_to_missing?(name, _private = false)
+      KEYS.include?(name.to_s.delete_suffix("=").delete_suffix("?").delete_suffix("!").to_sym)
+    end
+
+    private
+
+    def refusal(key)
+      near = GraphWeaver::Internal::Util.did_you_mean(KEYS.map(&:to_s), key.to_s)
+      fix =
+        if GraphWeaver.respond_to?(:"#{key}=") then " — GraphWeaver.#{key} = ... is the setting you want"
+        elsif near then " (did you mean #{near}?)"
+        end
+      "config.graph_weaver takes #{KEYS.join(", ")}, not #{key}#{fix}"
+    end
+  end
+
+  config.graph_weaver = Options.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
+
+    # What ignore_generated actually hid, resolved. Zeitwerk only reads its
+    # ignore list at setup, so anything that arrives later isn't hidden by
+    # calling ignore again — check_generated_ignored! refuses instead.
+    attr_accessor :ignored_dirs
   end
 
   rake_tasks do
     require "graph_weaver/tasks"
   end
 
+  # The two auto-wires an app gets for free, and the only two it can turn off
+  # by assigning nil. They are declared FIRST, and `before:
+  # :load_config_initializers`, and both of those are load-bearing:
+  #
+  # Rails gives an initializer an implicit `after:` of the previous one in the
+  # same railtie (Initializable#initializer: `opts[:after] ||=
+  # initializers.last&.name`). Declared after ignore_generated, which is
+  # `after: :load_config_initializers`, these two inherited that position —
+  # they ran AFTER config/initializers, so the `if nil?` fallback overwrote an
+  # app that had just said nil and the documented PII opt-out did nothing,
+  # silently, while queries and variables kept reaching a debug Rails.logger.
+  # Adding the `before:` without moving them is a TSort::Cyclic at boot, since
+  # the implicit `after:` would then point through ignore_generated.
+  #
+  # Rails.logger, unless the app already chose one (set
+  # GraphWeaver.logger = nil in an initializer to silence)
+  initializer "graph_weaver.logger", before: :load_config_initializers do
+    GraphWeaver.logger = Rails.logger if GraphWeaver.logger.nil?
+  end
+
+  # An APM sees every GraphQL call without the app configuring anything:
+  # the ActiveSupport::Notifications adapter from docs/logging.md, plus the
+  # LogSubscriber that turns its event into one line. Measured at ~4.5µs per
+  # execution all told (0.13µs of that ActiveSupport::Notifications itself
+  # with nothing subscribed; the rest is its Event machinery) — 0.05% of a
+  # 10ms round trip, so there is nothing to weigh.
+  #
+  # An instrumenter the app set is never replaced: assigned before this (in
+  # config/application.rb) the nil check leaves it, and config/initializers now
+  # genuinely runs later, so one assigned there wins on its own — including
+  # `GraphWeaver.instrumenter = nil` to opt out.
+  initializer "graph_weaver.instrumentation", before: :load_config_initializers do
+    next unless defined?(ActiveSupport::Notifications)
+
+    if GraphWeaver.instrumenter.nil?
+      GraphWeaver.instrumenter = lambda do |event, payload, &block|
+        ActiveSupport::Notifications.instrument(event, payload, &block)
+      end
+    end
+
+    # ActiveSupport::LogSubscriber is one of ActiveSupport's own eager
+    # autoloads, so naming it is enough — no require of theirs needed
+    require "graph_weaver/log_subscriber"
+    # idempotent — Subscriber.add_event_subscriber skips a pattern it already has
+    GraphWeaver::LogSubscriber.attach_to :graph_weaver
+  end
+
   # generated/person_query.rb defines ::PersonQuery, but Zeitwerk infers
   # Generated::PersonQuery from the path — and app/graphql/generated is
   # inside an autoload root by default, so eager loading raised
   # "uninitialized constant Generated::PersonQuery" in production while
   # development (lazy) was fine. load_generated! below requires them.
-  initializer "graph_weaver.ignore_generated", before: :setup_main_autoloader do
-    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(GraphWeaver::Internal::Util.resolve(path)) }
+  #
+  # after: :load_config_initializers as well as before Zeitwerk's setup — a
+  # graph's output: is only known once the app has declared its graphs, and
+  # with only the `before:` constraint this ran ~20 initializers too early, so
+  # an output outside the conventional glob was eager loaded on top of
+  # load_generated! and died on a redefined enum.
+  initializer "graph_weaver.ignore_generated",
+    after: :load_config_initializers, before: :setup_main_autoloader do
+    # patterns, not paths — generated_paths may be globs, and Zeitwerk
+    # expands its own at setup (which is what this runs before)
+    dirs = GraphWeaver::Internal::Util.generated_dirs.map { GraphWeaver::Railtie.autoload_path(_1) }
+    GraphWeaver::Railtie.check_autoload_once!(dirs)
+    GraphWeaver::Railtie.ignored_dirs = dirs
+    Rails.autoloaders.each { |loader| dirs.each { |path| loader.ignore(path) } }
+  end
+
+  # The `once` autoloader is set up in bootstrap, and Zeitwerk reads its ignore
+  # list only at setup — so the `loader.ignore` above, which runs after
+  # config/initializers, hides nothing from it however the output is spelled.
+  # The generic advice ("name it in GraphWeaver.generated_paths from
+  # config/initializers") produced byte-identical output for this one, so it
+  # gets its own refusal, naming the place that is still early enough.
+  def self.check_autoload_once!(dirs)
+    return unless Rails.respond_to?(:autoloaders) && Rails.autoloaders.respond_to?(:once)
+
+    once = Rails.autoloaders.once
+    dirs.each do |dir|
+      next unless autoloaded?(once, dir)
+
+      subject, short = describe_output(dir)
+      raise GraphWeaver::Error,
+        "#{subject} is under config.autoload_once_paths, which Rails sets the `once` autoloader up on " \
+        "before config/initializers run — so nothing GraphWeaver can do from there hides it, and its " \
+        "modules can't load. Hide it in config/application.rb, which is still early enough: " \
+        "Rails.autoloaders.once.ignore(Rails.root.join(#{short.inspect})) — or generate somewhere that " \
+        "is not an autoload-once path."
     end
   end
 
-  # Rails.logger, unless the app already chose one (set
-  # GraphWeaver.logger = nil in an initializer to silence)
-  initializer "graph_weaver.logger" do
-    GraphWeaver.logger = Rails.logger if GraphWeaver.logger.nil?
+  # A generated path as ZEITWERK sees it: resolved, and with symlinks followed,
+  # because Zeitwerk walks real directories. Ignoring a symlinked output hid it
+  # under a name Zeitwerk never visits, and the refusal below compared that same
+  # name against real autoload roots and so never fired — including for an
+  # absolute output through a symlinked ancestor, the Capistrano current/ shape.
+  # Only this seam needs it: everywhere else a path stays the setting expanded,
+  # so what the gem reports is what you wrote.
+  def self.autoload_path(path)
+    resolved = GraphWeaver::Internal::Util.resolve(path)
+    File.exist?(resolved) ? File.realpath(resolved) : resolved
+  end
+
+  # Whether this loader would actually try to load `dir`: one of its roots
+  # contains it and its own ignore list doesn't cover it. Asking only about the
+  # roots refused an app that had called Rails.autoloaders.main.ignore(dir)
+  # itself, and told it the directory couldn't be hidden — when it already was.
+  #
+  # Zeitwerk answers that question under two names: `ignores?` was public until
+  # 2.6.1 made it internal, which publishes it as `__ignores?`. Neither present
+  # (some other loader in the slot) falls back to refusing, which is what this
+  # did for everyone before.
+  IGNORES = %i[__ignores? ignores?].freeze
+
+  def self.autoloaded?(loader, dir)
+    return false unless loader.dirs.any? { |root| dir.start_with?("#{root}/") }
+
+    asked = IGNORES.find { |name| loader.respond_to?(name) }
+    asked.nil? || !loader.public_send(asked, dir)
+  end
+
+  # How a refusal names a generated directory: what writes it, and the path the
+  # way the graph itself spells it — not the symlink target autoload_path
+  # resolved to, since the advice has to name something the reader can find in
+  # their own config.
+  def self.describe_output(dir)
+    graph = GraphWeaver.graphs.find { autoload_path(_1.output) == dir }
+    short = GraphWeaver::Internal::Util.relative(GraphWeaver::Internal::Util.resolve(graph&.output || dir))
+    ["#{graph ? "graph :#{graph.name}'s output" : "generated path"} #{short}", short]
+  end
+
+  # A graph declared from to_prepare — what the docs say to do when its block
+  # names an autoloaded constant — is declared after Zeitwerk is set up, and
+  # Zeitwerk reads its ignore list only then. So an output that arrives that
+  # late can't be hidden: its files load as ordinary autoloads and raise on the
+  # constant they don't define, in a Zeitwerk error that blames a dropped
+  # extend_type. Refuse, and name what actually happened.
+  def self.check_generated_ignored!
+    # no autoloaders, no Zeitwerk, nothing to refuse
+    return unless Rails.respond_to?(:autoloaders)
+
+    late = GraphWeaver::Internal::Util.generated_dirs.map { autoload_path(_1) } - Array(ignored_dirs)
+    return if late.empty?
+
+    late.each do |dir|
+      next unless Rails.autoloaders.any? { |loader| autoloaded?(loader, dir) }
+
+      subject, short = describe_output(dir)
+      raise GraphWeaver::Error,
+        "#{subject} was declared after Rails " \
+        "set Zeitwerk up on it, so it can't be hidden from autoloading and its modules can't load. Declare " \
+        "the graph in config/initializers (schema -> { MyApp::Schema } resolves an autoloaded class when " \
+        "generation asks), or name #{short.inspect} in GraphWeaver.generated_paths there."
+    end
   end
 
   # The app already declared what is sensitive, so variables logged at debug
@@ -71,8 +252,25 @@ class GraphWeaver::Railtie < Rails::Railtie
   #
   # after: :load_config_initializers — that's where an app moves
   # queries_paths, and the finisher that reads app.reloaders runs later still.
+  #
+  # to_prepare, not the initializer itself: a graph declared from one of those
+  # (what the docs say to do when its block names an autoloaded constant) isn't
+  # declared until every initializer has run, and a watcher built before it
+  # watched the default queries_paths — an edit to that graph's .graphql
+  # silently never regenerated. to_prepare blocks run in registration order and
+  # an app registers its own during :load_config_initializers, which this is
+  # `after:`, so every graph is in by the time this runs; app.reloaders is read
+  # per request, so joining it this late still counts. Once, though: a dev
+  # reload re-runs to_prepare, and a second watcher is a second reloader over
+  # the same files.
   initializer "graph_weaver.watch", after: :load_config_initializers do |app|
-    GraphWeaver::Railtie.watch!(app)
+    watched = false
+    app.config.to_prepare do
+      next if watched
+
+      watched = true
+      GraphWeaver::Railtie.watch!(app)
+    end
   end
 
   # Registers the watcher, and says so: this is the one thing GraphWeaver does
@@ -87,7 +285,7 @@ class GraphWeaver::Railtie < Rails::Railtie
 
     # 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
+    watched = GraphWeaver.graphs.flat_map(&:queries) | GraphWeaver.fragments_paths
     # the dump codegen would read, or where it goes once someone takes one
     dump = GraphWeaver::SchemaLoader.locate_path || GraphWeaver.schema_path
 
@@ -96,7 +294,7 @@ class GraphWeaver::Railtie < Rails::Railtie
     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 " \
+        "#{GraphWeaver.graphs.map(&:output).uniq.join(", ")} before the next request " \
         "(config.graph_weaver.watch = false to stop)"
     end
     watcher
@@ -109,13 +307,15 @@ class GraphWeaver::Railtie < Rails::Railtie
   # one error per save, and the next save that compiles takes.
   def self.regenerate!
     GraphWeaver.generate!
-    GraphWeaver.reload_generated!
     changed = GraphWeaver.changed_files
+    # before reloading, not after: reloading logs a line of its own, and
+    # "loaded 4 generated module(s)" ahead of "regenerated ..." reads backwards
     GraphWeaver::Internal::Log.log(:info) do
       next "generated modules already up to date" if changed.empty?
 
       "regenerated #{changed.join(", ")}"
     end
+    GraphWeaver.reload_generated!
   rescue GraphWeaver::Error => e
     GraphWeaver::Internal::Log.log(:error) { "keeping the modules already loaded — #{e.message}" }
   end
@@ -136,6 +336,10 @@ class GraphWeaver::Railtie < Rails::Railtie
       # :environment, so boot failed before the task that would regenerate it.
       next if GraphWeaver.skip_generated_load
 
+      # the app's own to_prepare blocks have run by now, so this is the first
+      # point that sees every graph — and the last before one of them loads
+      GraphWeaver::Railtie.check_generated_ignored!
+
       # 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
@@ -144,8 +348,24 @@ class GraphWeaver::Railtie < Rails::Railtie
       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
+      generated = GraphWeaver::Internal::Util.generated_dirs.any? do |dir|
+        Dir[GraphWeaver::Internal::Util.resolve(dir)].any?
+      end
+      next unless generated
+
+      # `require` no-ops on a file it has already read — which is what we want,
+      # except when the constant that file defined is gone. A graph's
+      # `namespace:` is normally a module Zeitwerk owns (app/graphql/accounts/
+      # implies Accounts), and unloading it on a dev reload takes the generated
+      # module nested inside it with it; require then restores nothing and every
+      # request 500s on "uninitialized constant Accounts::PersonQuery" until a
+      # .graphql edit happens to trigger the watcher. An un-namespaced module
+      # defines a top-level constant Zeitwerk never manages, so it survives.
+      if GraphWeaver.graphs.any?(&:namespace)
+        GraphWeaver.reload_generated!
+      else
+        GraphWeaver.load_generated!
+      end
     end
   end
 end

data/lib/graph_weaver/representation.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "internal/refusal"
 
 module GraphWeaver
   # Called by generated code — not semver'd for direct use.
@@ -20,6 +21,12 @@ module GraphWeaver
   # representation is a Hash a module function builds, so there is no generated
   # struct to name.
   module Representation
+    # Marks a key path hop the schema declares as a list: `@key(fields: "id
+    # lineItems { sku }")` over a `[LineItem!]!` flattens to
+    # "lineItems[].sku". A representation is built from these paths and
+    # nothing else, so this is the only place list-ness is written down.
+    LIST_HOP = "[]"
+
     # `key_sets` is the entity's @key field sets as dotted paths, in
     # declaration order — [["upc", "sku"], ["id"]] for a type keyed either
     # way. The first fully-supplied one wins; the wire hash carries exactly
@@ -29,7 +36,7 @@ module GraphWeaver
       raise incomplete(type_name, values, key_sets) unless satisfied
 
       satisfied.each_with_object({ "__typename" => type_name }) do |path, wire|
-        assign(wire, path.split("."), dig(values, path))
+        graft(wire, values, path.split("."))
       end
     end
 
@@ -44,11 +51,13 @@ module GraphWeaver
 
       yield value
     rescue StandardError => e
-      shown = value.inspect
+      shown = Internal::Redact.shown(value)
       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,
+        kind: Internal::Refusal.kind_of(e), path: [name], coordinate: "#{type_name}.#{name}",
+        value: Internal::Redact.value(name, value), details: Internal::Refusal.details_of(e),
+        struct: type_name,
       )
     end
 
@@ -57,32 +66,61 @@ module GraphWeaver
 
     # Nested key values arrive as a caller-built hash, so accept either key
     # flavour at every hop — a literal `{ id: "1" }` reads the same as a hash
-    # round-tripped through JSON.
-    def self.dig(values, path)
-      path.split(".").reduce(values) do |scope, name|
-        return unless scope.is_a?(Hash)
+    # round-tripped through JSON. A LIST_HOP has to BE a list, and the rest of
+    # the path reads through every element: supplied only if all of them are,
+    # so one object where the schema says list reads as absent rather than
+    # going onto the wire misshapen.
+    def self.dig(scope, hops)
+      hops = hops.split(".") if hops.is_a?(String)
+      return scope if hops.empty?
+      return unless scope.is_a?(Hash)
 
-        scope.key?(name) ? scope[name] : scope[name.to_sym]
-      end
+      hop, *rest = hops
+      value = fetch(scope, hop.delete_suffix(LIST_HOP))
+      return dig(value, rest) unless hop.end_with?(LIST_HOP)
+      return unless value.is_a?(Array)
+      return value if rest.empty?
+
+      each = value.map { |item| dig(item, rest) }
+      each unless each.any?(&:nil?)
     end
     private_class_method :dig
 
-    def self.assign(wire, path, value)
-      *parents, leaf = path
-      target = parents.reduce(wire) { |scope, name| scope[name] ||= {} }
-      target[leaf] = value
+    def self.fetch(hash, name) = hash.key?(name) ? hash[name] : hash[name.to_sym]
+    private_class_method :fetch
+
+    # One key path, copied onto the wire in the shape the path declares — a
+    # LIST_HOP stays a list of objects, one per element, rather than
+    # collapsing into the single object a subgraph would read as one entity.
+    def self.graft(wire, source, hops)
+      hop, *rest = hops
+      name = hop.delete_suffix(LIST_HOP)
+      value = fetch(source, name)
+      return wire[name] = value if rest.empty?
+
+      if hop.end_with?(LIST_HOP)
+        elements = (wire[name] ||= Array.new(value.size) { {} })
+        value.each_with_index { |item, index| graft(elements[index], item, rest) }
+      else
+        graft(wire[name] ||= {}, value, rest)
+      end
     end
-    private_class_method :assign
+    private_class_method :graft
 
     # Name the type and what it's short of, per @key — with a single key
-    # there's one answer, so it also fills InputError#field.
+    # there's one answer, so it also fills InputError#path.
     def self.incomplete(type_name, values, key_sets)
       gaps = key_sets.map { |paths| missing(values, paths) }
 
       if key_sets.one?
+        # a nested @key reads "organization.id"; #path is that route, without
+        # the list markers the message keeps
+        path = gaps.first.one? ? gaps.first.first.split(".").map { |hop| hop.delete_suffix(LIST_HOP) } : []
         InputError.new(
           "#{type_name} representation is missing @key #{gaps.first.map(&:inspect).join(", ")}",
-          field: gaps.first.one? ? gaps.first.first : nil, struct: type_name,
+          kind: :missing, path:,
+          coordinate: ("#{type_name}.#{path.first}" if path.one?),
+          struct: type_name,
         )
       else
         alternatives = key_sets.zip(gaps).map do |paths, gap|
@@ -93,7 +131,7 @@ module GraphWeaver
         end
         InputError.new(
           "#{type_name} representation satisfies none of its @keys — supply #{alternatives.join(", or ")}",
-          struct: type_name,
+          kind: :missing, struct: type_name,
         )
       end
     end

data/lib/graph_weaver/result_struct.rb

@@ -0,0 +1,90 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module GraphWeaver
+  # Included in every generated result struct — the twin of InputStruct on
+  # the way out. T::Struct compares by identity, has no #to_h and can't be
+  # destructured, so two results parsed from the same response come back
+  # unequal, `result.to_h` raises, and `case result in {person:}` raises
+  # NoMatchingPatternError. A struct the library hands you should behave
+  # like an ordinary Ruby object; this is that behaviour, in one place.
+  module ResultStruct
+    extend T::Sig
+    include Kernel # for sorbet: hosts are T::Structs
+
+    # Value equality over the struct's props. Nested structs compare
+    # through their own copy of this, so a whole result tree compares.
+    # eql? on the props hash rather than ==, so that this and #hash agree
+    # on what "same" means (1 and 1.0 hash differently).
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      other.instance_of?(self.class) && deconstruct_keys(nil).eql?(other.deconstruct_keys(nil))
+    end
+    alias_method :eql?, :==
+
+    # eql? and hash move together, or a struct is a broken Hash key.
+    sig { returns(Integer) }
+    def hash = [self.class, *deconstruct_keys(nil).values].hash
+
+    # Pattern matching: `case result in {person: {name:}}`. Every prop,
+    # always — the pattern binds the ones it names, and a nested struct
+    # destructures through its own copy. Values stay as they are, so
+    # `in {person: Person => p}` binds the struct rather than a hash.
+    sig { params(_keys: T.nilable(T::Array[Symbol])).returns(T::Hash[Symbol, T.untyped]) }
+    def deconstruct_keys(_keys)
+      self.class.props.keys.to_h { |prop| [prop, public_send(prop)] }
+    end
+
+    # The Ruby-side view of the result: snake_case prop names as Symbols,
+    # nils kept, nested structs and arrays followed, enums left as their
+    # T::Enum members.
+    #
+    # Deliberately NOT the wire shape, and not an inverse of .from_h — a
+    # registered scalar keeps whatever Ruby object its codec built. That
+    # is the same objection Response#to_h raises against re-serializing
+    # its data, and it doesn't apply here: this hash is Symbol-keyed and
+    # Ruby-cased, so it can't be mistaken for the server's response.
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      deconstruct_keys(nil).transform_values { |value| unwrap_value(value) }
+    end
+
+    # JSON is the wire's shape, not Ruby's: `to_json` is the generated
+    # `as_json` encoded, so it carries the response keys and each leaf back
+    # through its scalar registration's `serialize:`, and
+    # `.from_h(JSON.parse(result.to_json))` gives an equal struct. That is
+    # the opposite of #to_h, deliberately — a Symbol-keyed Ruby hash can't be
+    # mistaken for a response, and a JSON string can, so the string is the
+    # one that has to be true. (A registration with no `serialize:` has no
+    # wire form; its value passes through, exactly as it does on the way in.)
+    #
+    # Defined here rather than left to Ruby: Object#to_json writes the
+    # #inspect string, quoted, and ActiveSupport's Object#as_json writes the
+    # ivars — a result's snake_cased props, `class_` and all.
+    sig { params(options: T.untyped).returns(String) }
+    def to_json(options = nil) = as_json.to_json(options)
+
+    # Only reached by a struct generated before as_json existed — the
+    # generated override otherwise wins, being defined on the struct itself.
+    sig { params(_options: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def as_json(*_options)
+      raise GraphWeaver::Error,
+        "#{self.class} was generated before #as_json — regenerate (rake graph_weaver:generate)"
+    end
+
+    private
+
+    # Follows a value into nested result structs and lists (which nest, for
+    # a `[[Pet!]!]!`); everything else is already Ruby-side.
+    sig { params(value: T.untyped).returns(T.untyped) }
+    def unwrap_value(value)
+      case value
+      when ResultStruct then value.to_h
+      when Array then value.map { |item| unwrap_value(item) }
+      else value
+      end
+    end
+  end
+end