graph_weaver 0.6.0 → 0.7.0

data/lib/graph_weaver/internal/overrides.rb

@@ -10,6 +10,10 @@ module GraphWeaver
     # suite-wide ones while the block that set them is still on the stack,
     # and a fake built with its own checks them then.
     module Overrides
+      # The key a Hash `list_size:` says its fallback under — every list it
+      # doesn't name.
+      LIST_SIZE_DEFAULT = "default"
+
       class << self
         # A pin key names something in the schema: a type ("Money",
         # "Person"), a "Type.field" coordinate, or a bare field name
@@ -22,6 +26,44 @@ module GraphWeaver
           end
         end
 
+        # Whether `key` reads as a reference into the schema rather than a
+        # plain word — what tells a pin from an option at a fake's door, where
+        # both arrive as the same keywords. A "Type.field" coordinate can only
+        # be a pin; a bare word is one when the schema knows it. Whether the
+        # reference RESOLVES is validate!'s question, so a coordinate naming
+        # no type is still a pin and gets that refusal rather than "unknown
+        # option".
+        #
+        # Casing can't decide it: Hasura's types are lowercase, and
+        # `pokemon_v2_pokemon` read as a misspelled option.
+        def schema_reference?(schema, key)
+          key = key.to_s
+          return true if key.include?(".") || key.start_with?("__")
+
+          !schema.get_type(key).nil? || field_names(schema).include?(key)
+        end
+
+        # Every name a pin may be keyed by — the dictionary a refusal guesses
+        # from when a key is neither a pin nor an option.
+        def pin_names(schema) = schema.types.keys + field_names(schema)
+
+        # A Hash `list_size:` sizes one list at a time, keyed the way a pin is
+        # minus the bare type name: a type says nothing about how long any one
+        # of its fields is.
+        def validate_list_size!(schema, list_size)
+          return unless list_size.is_a?(Hash)
+
+          list_size.each do |key, value|
+            unless value.is_a?(Integer) || value.is_a?(Range)
+              raise GraphWeaver::Error, "list_size: #{key.to_s.inspect} must be an Integer or a " \
+                "Range — how long an unbounded list is — got #{value.inspect}"
+            end
+            next if key.to_s == LIST_SIZE_DEFAULT
+
+            validate_field_key!(schema, key.to_s, "list_size: key")
+          end
+        end
+
         # A pin that's a proc is handed the seeded Random when it takes one
         # and called bare when it doesn't, so a varying pin still reproduces
         # under `rspec --seed`.
@@ -55,16 +97,36 @@ module GraphWeaver
 
             # a leading capital names a type, as it does wherever a pin is written
             dictionary = type_name.match?(/\A[A-Z]/) ? schema.types.keys : known
-            bad!(key, "matches no type or field in this schema", dictionary, type_name)
+            bad!("override key", key, "matches no type or field in this schema", dictionary, type_name)
+          end
+
+          coordinate!(schema, "override key", key, type_name, field_name)
+        end
+
+        # A key naming one FIELD — a "Type.field" coordinate, or a bare field
+        # name matching that field on any type.
+        def validate_field_key!(schema, key, label)
+          type_name, field_name = key.split(".", 2)
+          return if (field_name || type_name).start_with?("__")
+
+          if field_name.nil?
+            known = field_names(schema)
+            return if known.include?(type_name)
+
+            bad!(label, key, "matches no field in this schema", known, type_name)
           end
 
+          coordinate!(schema, label, key, type_name, field_name)
+        end
+
+        def coordinate!(schema, label, key, type_name, field_name)
           type = schema.get_type(type_name)
           unless type.respond_to?(:fields)
-            bad!(key, "names no object type in this schema", schema.types.keys, type_name)
+            bad!(label, key, "names no object type in this schema", schema.types.keys, type_name)
           end
           return if type.fields.key?(field_name)
 
-          bad!(key, "is not a field of #{type_name}", type.fields.keys, field_name)
+          bad!(label, key, "is not a field of #{type_name}", type.fields.keys, field_name)
         end
 
         # A type pin says what every value of that type is, and the fake only
@@ -84,10 +146,10 @@ module GraphWeaver
             "#{type.graphql_name}, and a pin fabricates a scalar, enum or object: #{advice}"
         end
 
-        def bad!(key, problem, dictionary, term)
+        def bad!(label, key, problem, dictionary, term)
           suggestion = Util.did_you_mean(dictionary, term)
           hint = suggestion ? " — did you mean '#{suggestion}'?" : ""
-          raise GraphWeaver::Error, "override key #{key.inspect} #{problem}#{hint}"
+          raise GraphWeaver::Error, "#{label} #{key.inspect} #{problem}#{hint}"
         end
 
         # Every output field name in the schema — walked only when a bare key

data/lib/graph_weaver/internal/planner.rb

@@ -3,6 +3,7 @@
 
 require "graphql"
 
+require_relative "selection"
 require_relative "subgraphs"
 
 module GraphWeaver
@@ -155,7 +156,20 @@ module GraphWeaver
           .map { |error| Wire.graphql_error(error.message, "GRAPHQL_VALIDATION_FAILED") }
       end
 
+      # @defer/@stream send the rest of the answer in later payloads over a
+      # multipart body; this router answers in one. Public and document-wide
+      # because the caller has to ask it BEFORE validation — the composed API
+      # schema usually doesn't declare the directives, so graphql-ruby's
+      # "Directive @defer is not defined" fires first and shadows this.
+      def refuse_incremental!(document)
+        node = Selection.incremental_directive(document) or return
+
+        refuse :incremental_delivery,
+          "this operation carries @#{node.name}, and the answer would arrive in more than one payload"
+      end
+
       def plan(document, operation_name: nil)
+        refuse_incremental!(document)
         operation = pick_operation(document, operation_name)
         refuse(:operation_type, "this document is a subscription") if
           operation.operation_type == "subscription"
@@ -178,7 +192,7 @@ module GraphWeaver
           return plan
         end
 
-        check_interface_objects!(root.graphql_name, selections, fragments) if @interface_objects.any?
+        check_reachable!(root.graphql_name, selections, fragments)
 
         entry = single_subgraph(root.graphql_name, selections, fragments)
         if entry
@@ -223,13 +237,14 @@ module GraphWeaver
 
       private
 
-      # Every type these selections reach, refused if one of them is an
-      # @interfaceObject: a subgraph resolves the whole interface there, so
-      # the supergraph records no per-field routing for it and every fetch
-      # planned against it would be a guess. Asked per query rather than at
-      # construction — one such directive shouldn't cost you the queries
-      # that never touch the type.
-      def check_interface_objects!(type_name, selections, fragments, depth = 0)
+      # Every position this operation reaches, refused if the supergraph says
+      # something about it no plan can honour — whatever plan it gets. It runs
+      # here, above the verbatim shortcut, because that is the only place
+      # every plan passes: a check that lives in {#plan_step} silently skips
+      # the query one subgraph answers whole. Asked per query rather than at
+      # construction — one such directive shouldn't cost you the queries that
+      # never touch it.
+      def check_reachable!(type_name, selections, fragments, depth = 0)
         return if depth > MAX_DEPTH
 
         selections.each do |node|
@@ -237,18 +252,20 @@ module GraphWeaver
           when GraphQL::Language::Nodes::Field
             next if node.name.start_with?("__")
 
+            contextual!(type_name, node)
+            progressive_override!(type_name, node)
             child = raw_child_type(type_name, node.name) or next
             interface_object!(child, "#{type_name}.#{node.name} returns #{child}")
-            check_interface_objects!(child, node.selections, fragments, depth + 1)
+            check_reachable!(child, node.selections, fragments, depth + 1)
           when GraphQL::Language::Nodes::InlineFragment
             condition = node.type&.name || type_name
             interface_object!(condition, "this operation selects ... on #{condition}")
-            check_interface_objects!(condition, node.selections, fragments, depth + 1)
+            check_reachable!(condition, node.selections, fragments, depth + 1)
           when GraphQL::Language::Nodes::FragmentSpread
             fragment = fragments[node.name] or next
             condition = fragment.type.name
             interface_object!(condition, "...#{node.name} is on #{condition}")
-            check_interface_objects!(condition, fragment.selections, fragments, depth + 1)
+            check_reachable!(condition, fragment.selections, fragments, depth + 1)
           end
         end
       end
@@ -352,7 +369,6 @@ module GraphWeaver
 
         here = step(subgraph, type_name)
         selections.each do |node|
-          contextual!(type_name, node)
           # a subtree that never leaves this subgraph goes over as written:
           # the boundary rules govern stitching, so they have no business
           # applying to a query that was never going to cross one
@@ -388,9 +404,9 @@ module GraphWeaver
 
       # A @fromContext argument is filled by the GATEWAY, out of a selection on
       # an ancestor — so a fetch this planner writes leaves it unset and the
-      # field resolves from nothing. Asked only of a field the planner routes
-      # itself: a subtree handed to one subgraph whole carries its own context,
-      # which is why the verbatim path never reaches here.
+      # field resolves from nothing. A subgraph's own resolver never fills one
+      # either, so handing it the subtree whole doesn't help: this is asked of
+      # every field the operation reaches, on every path.
       def contextual!(type_name, node)
         names = @table.field(type_name, node.name)&.contextual
         return if names.nil? || names.empty?
@@ -400,6 +416,20 @@ module GraphWeaver
           "on its own"
       end
 
+      # A progressive @override(label:) leaves BOTH subgraphs resolving the
+      # field — the label is the rollout rule the gateway evaluates per
+      # request to pick between them. A plain @override drops the losing copy
+      # at composition, so there is nothing to decide and nothing to refuse;
+      # a labelled one is a coin only the gateway can toss.
+      def progressive_override!(type_name, node)
+        field = @table.field(type_name, node.name)
+        label = field&.override_label or return
+
+        refuse :progressive_override, "#{type_name}.#{node.name} is mid-rollout under " \
+          "@override(label: #{label.inspect}) — #{field.graphs.join(" and ")} both resolve it, " \
+          "and a local router can't evaluate a rollout percentage"
+      end
+
       # The keys a fetch injects are stripped from the answer, so a caller's
       # alias spelling one is stripped with it — silently, since the two are
       # then indistinguishable. Asked of what this fetch actually injects

data/lib/graph_weaver/internal/refusal.rb

@@ -0,0 +1,49 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # The verdict a coercion refusal already reached, riding on the plain
+    # ::TypeError / ::ArgumentError Coerce raises rather than on a class of
+    # its own — so `rescue ::TypeError` still catches it and Coerce keeps
+    # complaining the way Kernel#Integer does.
+    #
+    # The layers that brand a failure (InputStruct.field, Coerce.variable)
+    # read it off the exception instead of deriving a kind from the message.
+    # A message is prose; reading a verdict back out of one would be a guess,
+    # and a wrong `kind` is worse than none — the app will have translated it
+    # into a confident sentence.
+    module Refusal
+      attr_accessor :graph_weaver_kind, :graph_weaver_details
+
+      class << self
+        # Tag an exception with its verdict; returns it, ready to raise.
+        def brand(error, kind, **details)
+          error.extend(Refusal)
+          error.graph_weaver_kind = kind
+          error.graph_weaver_details = details
+          error
+        end
+
+        # What a raised exception says went wrong, as an InputError kind.
+        # Coerce's own refusals carry their verdict; an app's `cast:` or
+        # `serialize:` raises whatever it likes, and Ruby's own convention
+        # splits the two it raises for a value it can't use: TypeError means
+        # the CLASS was wrong, ArgumentError the CONTENT — which is the
+        # difference between "send something else" and "fix the text".
+        # Anything else is :refused rather than a guess at what it meant.
+        def kind_of(error)
+          return error.graph_weaver_kind if error.is_a?(Refusal)
+
+          case error
+          when ::TypeError then :type_mismatch
+          when ::ArgumentError then :unparseable
+          else :refused
+          end
+        end
+
+        def details_of(error) = error.is_a?(Refusal) ? error.graph_weaver_details : {}
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/schemas.rb

@@ -27,20 +27,34 @@ module GraphWeaver
         end
 
         # Does this schema carry the coordinate — "Type", or "Type.field"?
-        def defines?(schema, coordinate)
-          type_name, field_name = coordinate.split(".", 2)
-          type = schema.get_type(type_name) or return false
-          return true unless field_name
-
-          return type.fields.key?(field_name) if type.respond_to?(:fields)
-          # an input object's members are arguments, not fields
-          return type.arguments.key?(field_name) if type.respond_to?(:arguments)
+        def defines?(schema, coordinate) = !member(schema, coordinate).nil?
 
-          false
+        # The type this schema gives "Type.field", printed the way SDL prints
+        # it — so it compares directly against a supergraph's own spelling.
+        # Presence is the cheaper question and answers a different one: a
+        # field that is still *there* can have been retyped underneath the
+        # composition, which reads as a match until the types are compared.
+        def signature(schema, coordinate)
+          member = member(schema, coordinate)
+          member.type.to_type_signature if member.respond_to?(:type)
         end
 
         private
 
+        # The field (or, on an input object, the argument — its members are
+        # arguments, not fields) at "Type.field", or the type itself for a
+        # bare coordinate.
+        def member(schema, coordinate)
+          type_name, field_name = coordinate.split(".", 2)
+          type = schema.get_type(type_name) or return
+          return type unless field_name
+
+          return type.fields[field_name] if type.respond_to?(:fields)
+          return type.arguments[field_name] if type.respond_to?(:arguments)
+
+          nil
+        end
+
         def descendants(klass)
           klass.subclasses.flat_map { |subclass| [subclass] + descendants(subclass) }
         end

data/lib/graph_weaver/internal/selection.rb

@@ -12,6 +12,40 @@ module GraphWeaver
     module Selection
       include Kernel # for sorbet: hosts are Objects
 
+      # The directives that ask for the answer in instalments. Neither the
+      # generated code nor the local router reads a multipart body, and both
+      # have to say so BY NAME: whether the schema in hand declares @defer is
+      # graphql-ruby's business, so "Directive @defer is not defined" is an
+      # accident that happens to refuse — and it stops happening the day a
+      # supergraph @links the defer spec.
+      INCREMENTAL = %w[defer stream].freeze
+
+      # The first @defer/@stream node anywhere in a parsed document, or nil.
+      # A module function rather than part of the walk below: the callers ask
+      # before they have a schema, an operation, or a host to walk with.
+      def self.incremental_directive(node)
+        if node.respond_to?(:directives)
+          # a spread carries directives and no selections (`...Frag @defer`),
+          # so this is asked of every node rather than only of the ones below
+          applied = node.directives.find { |d| INCREMENTAL.include?(d.name) }
+          return applied if applied
+        end
+
+        children = if node.is_a?(GraphQL::Language::Nodes::Document)
+          node.definitions
+        elsif node.respond_to?(:selections)
+          node.selections
+        else
+          []
+        end
+
+        children.each do |child|
+          nested = incremental_directive(child)
+          return nested if nested
+        end
+        nil
+      end
+
       # Every method here becomes an instance method of its host (Codegen,
       # FakeClient, the cassette Anonymizer) — private so the walk stays the
       # host's own business rather than part of its API.

data/lib/graph_weaver/internal/server_input.rb

@@ -0,0 +1,251 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # A server's rejection of the input, read back into InputError values —
+    # the same value object the client-side refusal is, so an app renders one
+    # form the same way whichever side said no.
+    #
+    # Four shapes, most specific first: the `extensions.input` convention
+    # (docs/errors.md), graphql-ruby's variable-coercion `problems` array, a
+    # recognized `extensions.code`, and Hasura's argument path. Everything
+    # else is nobody's input error and stays out — and an explanation with no
+    # table entry becomes `:refused` carrying the server's own sentence,
+    # because a wrong `kind` is worse than no kind: the app will have
+    # translated it into a confident sentence.
+    #
+    # One rule for #path throughout: it is the INPUT path the server stated,
+    # or empty. A GraphQL error's own path names a selection rather than an
+    # input slot, so it is never stood in for one.
+    module ServerInput
+      # graphql-ruby names the variable only in the error's message; the
+      # problems underneath are relative to it (measured against 2.6.10).
+      VARIABLE = /\AVariable \$([A-Za-z_]\w*) /
+
+      # The explanations graphql-ruby writes for a variable that wouldn't
+      # coerce. A closed table, not a parser: anything else is :refused.
+      COERCE = /\ACould not coerce value .* to (\S+)\z/
+      NOT_A_MEMBER = /\AExpected .* to be one of: (.*)\z/
+      NOT_NULL = /\AExpected value to not be null\z/
+      NOT_DEFINED = /\AField is not defined on (\S+)\z/
+
+      # Hasura states no input code — it stamps one code on a whole class of
+      # rejections and says what the error is about in `extensions.path`, a
+      # dotted string rather than an array. So the path is the test, not the
+      # code: only one that reaches a field's arguments is about the input.
+      # "$", "$.query" and "$.selectionSet.<field>" are the query itself — a
+      # .graphql file that doesn't parse, or names an argument the schema
+      # hasn't got, is nothing a form can highlight.
+      HASURA_CODES = %w[validation-failed parse-failed].freeze
+      # lazily, so an argument of its own named `args` doesn't win the split
+      HASURA_ARGUMENT = /\A\$\.selectionSet\..+?\.args\.(.+)\z/
+      HASURA_SEGMENT = /\A([_A-Za-z]\w*)((?:\[\d+\])*)\z/
+
+      # The explanations Hasura writes that name a kind on their own (measured
+      # against Hasura v2, one curl per entry — spec/input_errors_spec.rb
+      # holds the verbatim JSON). Its scalar family, "expected <description>
+      # for type 'T', but found <json type>", is deliberately absent: one
+      # sentence covers both `limit: -5` (out of range) and `limit: "lots"`
+      # (wrong type), and telling them apart means parsing the English
+      # description rather than reading a table.
+      HASURA_NOT_A_MEMBER = /\Aexpected one of the values \[(.*)\] for type '[^']*', but found /
+      HASURA_NOT_DEFINED = /\Afield '([^']*)' not found in type: '([^']*)'\z/
+      HASURA_NULL = /\Aunexpected null value for type '[^']*'\z/
+      QUOTED = /'([^']*)'/
+
+      # InputError::DETAILS closes the key set; this closes the types, because
+      # a right key with the wrong type under it is the same smuggling. An app
+      # is entitled to errors.rb's promise that members stays an Array —
+      # details[:members].join(", ") must not raise on what a server sent.
+      # (spec/input_errors_spec.rb holds these keys to DETAILS.)
+      DETAIL_TYPES = {
+        "type" => String, "members" => Array, "min" => Numeric,
+        "max" => Numeric, "pattern" => String, "suggestion" => String,
+      }.freeze
+
+      private_constant :VARIABLE, :COERCE, :NOT_A_MEMBER, :NOT_NULL, :NOT_DEFINED,
+        :HASURA_CODES, :HASURA_ARGUMENT, :HASURA_SEGMENT, :QUOTED,
+        :HASURA_NOT_A_MEMBER, :HASURA_NOT_DEFINED, :HASURA_NULL
+
+      class << self
+        def read(error)
+          extensions = error.extensions
+          stated = extensions["input"]
+          return [convention(error.message, stated, [], nil)] if stated.is_a?(Hash)
+          return problems(error, extensions) if extensions["problems"].is_a?(Array)
+
+          kind = GraphWeaver::GraphQLError::INPUT_CODES[error.code.to_s]
+          return [coded(error, kind)] if kind
+
+          hasura(error, extensions)
+        end
+
+        private
+
+        # The convention: taken verbatim, after checking `kind` is one this
+        # version knows and `details` carries only keys a kind can mean.
+        def convention(message, stated, path, value)
+          kind = stated["kind"].to_s.to_sym
+          kind = :refused unless GraphWeaver::InputError::KINDS.include?(kind)
+          coordinate = stated["coordinate"]
+
+          build(
+            message,
+            kind:,
+            path: input_path(stated["path"]) || path,
+            coordinate: (coordinate if coordinate.is_a?(String)),
+            value: stated.key?("value") ? stated["value"] : value,
+            details: details_of(stated),
+          )
+        end
+
+        # A path a server stated for the INPUT, or nil: field names and list
+        # indices, nothing else. There is no floor under it — a GraphQL error's
+        # own path names a selection ("createOrder"), and standing that in gives
+        # #field a plausible-looking name for a slot the input hasn't got.
+        def input_path(stated)
+          return unless stated.is_a?(Array)
+
+          stated if stated.all? { |segment| segment.is_a?(String) || segment.is_a?(Integer) }
+        end
+
+        # the details a server stated that a kind can actually mean, both key
+        # and type — anything else is dropped rather than passed through
+        def details_of(stated)
+          DETAIL_TYPES.each_with_object({}) do |(key, type), out|
+            value = stated[key]
+            out[key.to_sym] = value if value.is_a?(type)
+          end
+        end
+
+        # One InputError per problem — a single coercion error routinely
+        # carries several, and they are about different fields.
+        def problems(error, extensions)
+          root = (match = error.message.match(VARIABLE)) ? [match[1]] : []
+
+          extensions["problems"].filter_map do |problem|
+            next unless problem.is_a?(Hash)
+
+            within = Array(problem["path"])
+            path = root + within
+            value = dig(extensions["value"], within)
+            message = problem["explanation"].to_s
+            stated = problem.dig("extensions", "input")
+            next convention(message, stated, path, value) if stated.is_a?(Hash)
+
+            explained(message, path, value, within)
+          end
+        end
+
+        def explained(message, path, value, within)
+          case message
+          when COERCE
+            # text that didn't parse, vs a thing that was never that type
+            build(message, kind: value.is_a?(String) ? :unparseable : :type_mismatch,
+              path:, value:, details: { type: $1 })
+          when NOT_A_MEMBER
+            build(message, kind: :not_a_member, path:, value:, details: { members: $1.split(", ") })
+          when NOT_NULL
+            build(message, kind: :missing, path:, value:)
+          when NOT_DEFINED
+            # the one explanation that names the input type, so the one that
+            # can give a coordinate — but only from the problem's OWN path.
+            # #path is the variable plus that, so its last segment is the
+            # variable name when the problem states none, and "RangeInput.range"
+            # is a slot the schema doesn't have.
+            type = $1
+            field = within.last
+            build(message, kind: :unknown, path:, value:,
+              coordinate: ("#{type}.#{field}" if field.is_a?(String)))
+          else
+            build(message, kind: :refused, path:, value:)
+          end
+        end
+
+        # Hasura: the argument is in extensions.path or this is not about the
+        # input. No value either — Hasura never echoes back what it rejected.
+        def hasura(error, extensions)
+          return [] unless HASURA_CODES.include?(error.code.to_s)
+
+          stated = extensions["path"]
+          match = stated.is_a?(String) ? stated.match(HASURA_ARGUMENT) : nil
+          path = hasura_path(match[1]) if match
+          path ? [hasura_explained(error.message, path)] : []
+        end
+
+        # "order_by[0].name" => ["order_by", 0, "name"]. nil rather than a
+        # partial read: a path this can't spell points a form at a field the
+        # server never named.
+        def hasura_path(stated)
+          stated.split(".").flat_map do |segment|
+            match = segment.match(HASURA_SEGMENT) or return nil
+            [match[1], *match[2].scan(/\d+/).map(&:to_i)]
+          end
+        end
+
+        def hasura_explained(message, path)
+          case message
+          when HASURA_NOT_A_MEMBER
+            build(message, kind: :not_a_member, path:, details: { members: $1.scan(QUOTED).flatten })
+          when HASURA_NOT_DEFINED
+            build(message, kind: :unknown, path:, coordinate: "#{$2}.#{$1}")
+          when HASURA_NULL
+            # :missing is "wasn't supplied, or was null" (docs/i18n.md)
+            build(message, kind: :missing, path:)
+          else
+            build(message, kind: :refused, path:)
+          end
+        end
+
+        # A recognized validation code. `argumentName` is the input coordinate;
+        # a code that names none names no slot, and the error's own path is a
+        # QUERY path ("query", "rangeThing", …) rather than an input one.
+        def coded(error, kind)
+          extensions = error.extensions
+          argument = extensions["argumentName"]
+          # inputObjectType is stated outright; argumentNotAccepted says which
+          # kind of thing `name` is instead. A field argument has no schema
+          # coordinate here — nothing names the field's parent type.
+          type = extensions["inputObjectType"] ||
+            (extensions["name"] if extensions["typeName"] == "InputObject")
+
+          build(
+            error.message,
+            kind:,
+            path: argument.is_a?(String) ? [argument] : [],
+            coordinate: ("#{type}.#{argument}" if type.is_a?(String) && argument.is_a?(String)),
+            value: extensions["value"],
+          )
+        end
+
+        # raised: false — this is a value read off a response, and the warn
+        # line Error#initialize writes would claim a raise that never happened.
+        #
+        # The message goes through the same filter the client side puts its own
+        # messages through: a server quotes the value it rejected as a matter of
+        # course ('Could not coerce value "hunter2" to Int'), so redacting only
+        # #value would leave half the promise kept. It is capped for the same
+        # reason — the sentence is the server's, and so is its length.
+        def build(message, kind:, path:, value: nil, coordinate: nil, details: {})
+          redact = GraphWeaver::Internal::Redact
+          GraphWeaver::InputError.new(
+            redact.cap(redact.detail(path.last, message)), kind:, path:, coordinate:, details:, raised: false,
+            value: redact.value(path.last, value),
+          )
+        end
+
+        # the problem's path walked into the variable the server echoed back
+        def dig(value, path)
+          path.reduce(value) do |node, segment|
+            case node
+            when Hash then node[segment.to_s]
+            when Array then segment.is_a?(Integer) ? node[segment] : nil
+            else return nil
+            end
+          end
+        end
+      end
+    end
+  end
+end