graph_weaver 0.6.1 → 0.7.0

data/lib/graph_weaver/internal/test_clients.rb

@@ -0,0 +1,276 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # The client a generated module runs against while a test mode is
+    # installed — the slot `graphql: :fake` and its siblings fill, and the one
+    # a `graphql_*` helper writes to.
+    #
+    # A tag used to work by swapping GraphWeaver.client, which is the LAST
+    # place a module looks: one generated with `client:` reads its baked
+    # DEFAULT_CLIENT first and never got there, so the tag quietly didn't
+    # apply. The mode installs itself here instead, and QueryModule asks
+    # before it reads that constant — so a tag reaches every module the
+    # example runs, bound or not.
+    #
+    # Keyed by the graph a module was generated from (its baked GRAPH), since
+    # the honest answer varies: :fake for a billing module has to fabricate
+    # billing's shapes, not the other schema's. A helper names its graphs the
+    # same way and lands in the same table, so what an example says applies to
+    # the modules it runs.
+    #
+    # Test-time only. Nothing installs a mode in production, where #for is an
+    # ivar read that returns nil.
+    module TestClients
+      # The app client slot under a mode in an app with several graphs. It
+      # fills the duck-typed slot the same way every other client does, and
+      # answers the one question asked of it with the reason there is no
+      # answer — the alternative is the real endpoint, silently.
+      class NoAppClient
+        def initialize(mode) = @mode = mode
+
+        def execute(_query, **)
+          graphs = GraphWeaver.graphs
+          raise GraphWeaver::Error, "#{@mode.inspect} stands in for a graph's modules, and this " \
+            "app has #{graphs.size} graphs (#{graphs.map { |g| g.name.inspect }.join(", ")}) — so " \
+            "GraphWeaver.client has no one right answer, and this request would have gone to the " \
+            "real endpoint. A generated module runs against its own graph's stand-in; to reach one " \
+            "directly, call the client a helper returns (graphql_fake(graph: #{graphs.first.name.inspect}), " \
+            "graphql_in_process(graph: #{graphs.first.name.inspect})). Tag the example graphql: :live " \
+            "for the app's own client."
+        end
+
+        def inspect = "#<#{self.class} #{@mode.inspect}>"
+      end
+
+      class << self
+        # Install `mode` for one example — the example's mode, which is what
+        # a graph no helper named runs against.
+        #
+        # Only the rspec hook installs, once per example after reset!. A
+        # helper doesn't: what a helper says is ONE graph's stand-in, written
+        # to the table by override!, so no helper can reset another graph's —
+        # which is how two graphs run in two modes in one example.
+        def install(mode)
+          @mode = mode
+          @clients = {}
+          @context = nil
+        end
+
+        # Back to no mode: every module resolves its own client again.
+        def reset!
+          @mode = nil
+          @clients = nil
+          @context = nil
+        end
+
+        # Whether an example is running under a mode — what tells suite setup
+        # apart from an example changing it out from under itself.
+        def installed? = !@mode.nil?
+
+        # Whether this example's stand-ins are already built — which is what
+        # makes a config setting they were built FROM too late to change.
+        def built? = !(@clients.nil? || @clients.empty?)
+
+        # The GraphQL context every stand-in runs with: this example's, else
+        # the suite baseline. graphql_context writes it, and the stand-ins
+        # already built take it in place — a :wire example's are built before
+        # the example body runs.
+        def context = @context || GraphWeaver::Testing.config.context
+
+        def context=(values)
+          @context = values
+          @clients&.each_value { |client| client.context = values if client.respond_to?(:context=) }
+        end
+
+        # `client` stands in for every graph in `graphs`, in place of the one
+        # the mode would build. This is a helper called in an example saying
+        # what the modules it names run against.
+        def override!(client, graphs)
+          graphs.each { |graph| @clients[graph&.name] = client }
+          client
+        end
+
+        # The stand-in for `mod`, or nil when there is nothing to stand in for.
+        def for(mod)
+          return unless @mode
+          # :wire takes no client slot: it serves the resolvers at the
+          # endpoint each client already posts to — the transport you ship,
+          # running unchanged, is the whole point
+          return if @mode == :wire
+          # :live is the app's own clients, untouched — so with nothing
+          # standing in there is nothing to look up
+          return if @mode == :live && !built?
+
+          # a helper's entry wins whatever the example's mode is, and :live
+          # builds nothing of its own, so an untagged example's other graphs
+          # still resolve their own clients
+          standin(graph_for!(mod))
+        end
+
+        # The stand-in `graph`'s modules run against under the installed mode,
+        # built once per example. :wire reaches it too — its clients sit
+        # behind the served endpoints rather than in the client slot, but they
+        # are the same objects graphql_context has to reach.
+        #
+        # `mode` is how a helper under a :wire tag asks for the client its own
+        # name means rather than the one :wire would have picked.
+        def standin(graph, mode = @mode)
+          @clients[graph&.name] ||= client_for(mode, graph)
+        end
+
+        # The client `mode` runs `graph` against — the one answer to "what
+        # does this tag mean", asked per module here and once per example by
+        # the rspec hook. nil for the two modes that take no client slot:
+        # :live is the app's own clients, untouched, and :wire serves the
+        # resolvers at the endpoint each client already posts to.
+        def client_for(mode, graph = app_graph)
+          config = GraphWeaver::Testing.config
+          case mode
+          when :fake
+            GraphWeaver::Testing::FakeClient.new(schema: config.reference_schema!(graph),
+              registry: graph&.registry)
+          when :in_process
+            GraphWeaver::InProcess.new(config.schema_class!(graph), context:)
+          when :router
+            router = config.built_router(graph)
+            router.context = context
+            # a router is built once per supergraph, so it has to be told
+            # where this example starts — the trace, and any faked subgraph's
+            # fabricated data. Once per router, not once per graph: two
+            # graphs naming one supergraph share it, and resetting again when
+            # the second's first module resolved wiped what the first had
+            # already accumulated, mid-example.
+            router.reset! unless @clients&.value?(router)
+            router
+          when :wire
+            # what sits behind the wire is decided the way the other tags
+            # already decide it, per graph — the most faithful thing that
+            # graph has, in the order the other tags rank them
+            client_for(wire_mode(config, graph), graph)
+          end
+        end
+
+        # What :wire serves for `graph`: its router when it is in a composed
+        # supergraph, its live schema class when it has one, else a fake of
+        # its schema — which is what an app that is a pure client of someone
+        # else's API has, and the only mode it could be.
+        #
+        # The one candidate the other modes have and :wire doesn't is
+        # GraphWeaver.client's own schema: reading it introspects the very
+        # endpoint :wire is about to stub, so it is a refusal here rather than
+        # a request into a stub that doesn't exist yet.
+        def wire_mode(config, graph)
+          return :router if config.supergraph?(graph)
+          return :in_process if config.schema_class?(graph)
+          return :fake if config.schema || graph&.named_schema?
+
+          raise GraphWeaver::Error, ":wire serves your schema at the endpoint your client posts " \
+            "to, and #{graph&.name ? "graph #{graph.name.inspect}" : "this app"} has none to " \
+            "serve — no live GraphQL::Schema class, no composed supergraph, and no type " \
+            "information (nothing at #{GraphWeaver.schema_path}, and " \
+            "GraphWeaver::Testing.config.schema is unset). Your client's own schema can't stand " \
+            "in here: reading it introspects the endpoint :wire has stubbed. Commit a dump " \
+            "(rake graph_weaver:schema:refresh URL=…), or tag the example graphql: :live."
+        end
+
+        # The graph a mode builds for when no module named one: this app's
+        # only graph. With several the honest answer varies per module, so
+        # there is no app-wide one and each module resolves its own.
+        def app_graph
+          graphs = GraphWeaver.graphs
+          graphs.first if graphs.one?
+        end
+
+        # What GraphWeaver.client holds while a mode is installed, or nil for
+        # the modes that leave the app's own there (:live, and :wire, which
+        # serves at each client's endpoint instead).
+        #
+        # One graph has one answer, so the app slot holds the same stand-in
+        # its modules resolve. With several there is none — and leaving the
+        # app's real client in the slot let a stray GraphWeaver.client.execute
+        # reach the production endpoint from an example whose tag promised no
+        # request, so the slot refuses by name instead.
+        def app_client
+          return if @mode.nil? || @mode == :live || @mode == :wire
+
+          graph = app_graph
+          graph ? standin(graph) : NoAppClient.new(@mode)
+        end
+
+        # The graphs a helper stands in for: the one `graph:` names, else the
+        # ones `schema` names, else this app's only graph. A helper that
+        # reaches no module is the silent pass this slot exists to stop, so
+        # nothing to reach is a refusal — and `advice` is what THIS helper
+        # does once it knows which graph.
+        #
+        # `graph:` leads because a graph's name is its identity everywhere
+        # else in the gem, and it is the only spelling that reaches every
+        # graph: `schema` is matched by object identity, which a graph whose
+        # schema is a dump has nothing to match with.
+        def targets!(helper, schema, advice, graph: nil)
+          return [graph!(helper, graph)] if graph
+
+          named = named_graphs(schema)
+          return named if named.any?
+
+          graphs = GraphWeaver.graphs
+          return graphs if graphs.one?
+
+          raise GraphWeaver::Error, "#{helper} stands in for the modules of one graph, and " \
+            "#{schema ? "#{schema} names none of this app's graphs" : "this app has #{graphs.size}"} " \
+            "(#{declared_names}) — say which: #{helper}(graph: #{graphs.first.name.inspect}). #{advice}"
+        end
+
+        private
+
+        # The graph `graph:` names. Its name, not its schema: that is what
+        # `rake graph_weaver:graphs` prints, what codegen bakes into a
+        # module's GRAPH, and the one handle a dump-backed graph has.
+        def graph!(helper, name)
+          found = GraphWeaver.graphs.find { |graph| graph.name == name }
+          return found if found
+
+          near = Util.did_you_mean(GraphWeaver.graphs.map { |graph| graph.name.to_s }, name.to_s)
+          raise GraphWeaver::Error, "#{helper}(graph: #{name.inspect}) names none of this app's " \
+            "graphs (#{declared_names})#{" — did you mean #{near.to_sym.inspect}?" if near}"
+        end
+
+        # The graphs `schema` names: a schema class is matched against what
+        # each graph runs in-process, which is the only thing that ties a
+        # class to a graph. A graph named by a dump can't be named this way,
+        # and correctly isn't.
+        def named_graphs(schema)
+          return [] unless schema
+
+          GraphWeaver.graphs.select { |graph| graph.live_schema.equal?(schema) }
+        end
+
+        def declared_names = GraphWeaver.graphs.map { |graph| graph.name.inspect }.join(", ")
+
+        # The graph `mod` was generated from, by the name codegen baked in.
+        # An app with several graphs and a module that names none was
+        # generated before its graph was declared, or by an older release —
+        # and guessing would fake one schema's shapes at another's module.
+        def graph_for!(mod)
+          graphs = GraphWeaver.graphs
+          return graphs.first if graphs.one?
+
+          name = mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
+          found = graphs.find { |graph| graph.name == name }
+          return found if found
+
+          # Two doors produce a module, so the fix has two spellings: a file
+          # gets its GRAPH back by being regenerated, and a GraphWeaver.parse
+          # module — which generates no file, so regenerating cannot reach it
+          # — is told where it is parsed.
+          raise GraphWeaver::Error, "#{mod} doesn't say which of this app's graphs " \
+            "(#{declared_names}) it was generated from, so #{@mode.inspect} has nothing to run " \
+            "it against — regenerate it (rake graph_weaver:generate), or, if it came from " \
+            "GraphWeaver.parse, say which there (graph: #{graphs.first.name.inspect})."
+        end
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/unused.rb

@@ -0,0 +1,287 @@
+# typed: true
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "../internal"
+
+module GraphWeaver
+  module Internal
+    # Which generated props no code in the app reads — the over-fetch that
+    # collects when a template stops using a field and nobody edits the
+    # .graphql. graphql-client catches it at runtime by masking the data it
+    # didn't declare; the structs are checked in here, so it can be recovered
+    # without running anything.
+    #
+    # Name-based on purpose. The generated structs say which props exist; one
+    # sweep of the app's own source says which names it mentions. That makes
+    # this a lint rather than a proof — #report says so in its own footer,
+    # because a finding is a prompt to look, never a verdict.
+    class Unused
+      # Where a prop shows up when it is READ: a method call, a pattern-match
+      # or hash key, a symbol, a string. A bare word in prose matches none of
+      # them, which is what keeps comments and locals out.
+      READ = /[.:"']([a-z_]\w*)|\b([a-z_]\w*):/
+      # Hand a struct to one of these and every prop is read at once, by a
+      # call that names none of them. Caught where the sink line carries the
+      # module's own name, or a local a line above assigned from it.
+      SINKS = /\b(?:to_h|to_json|as_json|serialize|deconstruct_keys)\b|render\s+json:/
+      # `result = PersonQuery.execute!(...)` — the local a response lands in.
+      # Following one is what lets the sink be on the NEXT line, which is how
+      # anyone actually writes a controller. Excludes == and =~.
+      ASSIGN = /\b([a-z_]\w*)\s*=[^=~]/
+      # A graphql-ruby TYPE class NAMES every field the server offers, as
+      # `field :sku` and as a resolver method — which is the server answering,
+      # not this app reading a prop back. Without this an app that serves the
+      # graph it consumes (graphql_in_process) marks every prop read, and the
+      # task reports nothing however much it over-fetches.
+      #
+      # Type kinds only: GraphQL::Schema::Resolver and ::Mutation hold
+      # application logic — in a BFF that is exactly where an upstream graph
+      # gets read — and skipping those files lost every read in them. Both
+      # spellings, because graphql-ruby's own generator emits the app-owned
+      # base class (`< Types::BaseObject`), not the gem's.
+      TYPE_KINDS = "Object|Interface|Union|Enum|Scalar|InputObject"
+      SCHEMA = /^[ \t]*(?:class \w+ < (?:GraphQL::Schema::|Types::Base)(?:#{TYPE_KINDS})\b|include GraphQL::Schema::Interface\b)/
+      # What the sweep can read. A prop read from anywhere else — a .vue, a
+      # .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
+      # 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.
+      SKIP = Set["vendor", "node_modules", "tmp", "log", "generated"].freeze
+      # enough of the quoted line to judge it by, without wrapping a terminal
+      SNIPPET = 100
+
+      # Measured against real corpora (actionview, activesupport, graphql and
+      # six Rails gems swept together): half to two thirds of genuinely unread
+      # selections go unreported, rising with corpus size. Saying so is the
+      # 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."
+
+      # query: the .graphql that selected it. struct/prop: where it landed.
+      # wire: how the query spells that prop, when it differs.
+      Selection = Struct.new(:query, :module_name, :struct, :prop, :wire) do
+        # The GraphQL-side name, which is what you go and delete: the struct's
+        # own name is the response key, so `Person.birthday` reads the way the
+        # query does — and a camelCase field, an alias or a reserved rename
+        # reads the way the query spells it, not the way the prop does.
+        def coordinate = "#{struct.name.split("::").last}.#{wire || prop}"
+
+        # …and the Ruby side, so the report is greppable both ways.
+        def constant = "#{struct.name}##{prop}"
+      end
+
+      # Why a module's props were all counted read, and on what evidence. Via
+      # is the local the value was standing in when it reached the serializer,
+      # nil when the sink line named the module itself.
+      Excuse = Struct.new(:path, :number, :source, :via) do
+        def reason
+          where = "handed whole to a serializer at #{path}:#{number}"
+          via ? "#{where}, as `#{via}`" : where
+        end
+      end
+
+      # What one pass over the files answers.
+      Sweep = Struct.new(:names, :wholly_used, :files)
+
+      # paths: the directories to sweep, defaulting to the whole root. Narrowed
+      # here rather than by the caller, so an empty PATHS= sweeps everything
+      # instead of nothing — nothing would report every prop unread.
+      def initialize(graphs: GraphWeaver.graphs, paths: nil)
+        @graphs = graphs
+        given = Array(paths).map { |path| path.to_s.strip }.reject(&:empty?)
+        @roots = (given.empty? ? ["."] : given).map { |path| Util.resolve(path) }
+        # A root that isn't there sweeps nothing, and sweeping nothing reports
+        # every prop unread — under STRICT, a red build demanding you delete
+        # fields you use. `0 files swept` was the only tell, printed beneath
+        # the accusations.
+        missing = @roots.reject { |root| Dir.exist?(root) }
+        return if missing.empty?
+
+        raise GraphWeaver::Error,
+          "no directory at #{missing.map { |root| Util.relative(root) }.join(", ")} — " \
+          "PATHS= names directories under #{GraphWeaver.root}"
+      end
+
+      # Every selection nothing reads, grouped the way the report prints them.
+      def findings
+        @findings ||= selections
+          .reject { |selection| read?(selection) }
+          .sort_by { |selection| [Util.relative(selection.query), selection.coordinate] }
+      end
+
+      def report
+        # The evidence, not just the verdict: name-matching a serializer call
+        # is the mushiest thing here, and a suppression that was wrong should
+        # be obvious at a glance rather than silently eating the report.
+        lines = wholly_used.flat_map do |name, excuse|
+          ["#{name}: every prop counted as read — #{excuse.reason}", "  #{excuse.source[0, SNIPPET]}"]
+        end
+        lines += findings.map do |selection|
+          "#{Util.relative(selection.query)}: #{selection.coordinate} — selected, never read " \
+            "(#{selection.constant})"
+        end
+        # a run that checked nothing would report "0 unread" whatever the
+        # queries said, which is worse than saying so
+        lines << nothing_loaded if selections.empty?
+        [*lines, "", summary, "", FOOTER].join("\n")
+      end
+
+      # What the summary counts, so the task can phrase its own STRICT abort.
+      def summary
+        "#{selections.size} selections, #{findings.size} unread — " \
+          "#{count(selections.map(&:query).uniq.size, "query", "queries")}, " \
+          "#{count(swept, "file", "files")} swept under #{where}"
+      end
+
+      def count(number, one, many) = "#{number} #{(number == 1) ? one : many}"
+
+      private
+
+      def read?(selection)
+        wholly_used.key?(selection.module_name) || names.include?(selection.prop.to_s)
+      end
+
+      def names = sweep.names
+      def wholly_used = sweep.wholly_used
+      def swept = sweep.files
+
+      # One pass over the files for all three answers — the names anything
+      # reads, the modules something serializes whole, and how many files that
+      # took. Per-prop searching is what makes a tool like this too slow to run.
+      def sweep
+        @sweep ||= begin
+          read = Set.new
+          whole = {}
+          short = selections.to_h { |selection| [selection.module_name, selection.module_name.split("::").last] }
+          files.each do |path|
+            # scrub: a stray non-UTF-8 byte in a template is not a reason to
+            # refuse to lint the other 500 files
+            body = File.read(path).scrub
+            next if SCHEMA.match?(body)
+
+            body.scan(READ) { |method, key| read << (method || key) }
+            next unless SINKS.match?(body)
+
+            # Both substring checks before walking the lines: `to_h` is in
+            # most files and a query module's name is in almost none, so this
+            # is what keeps the line pass off the other 95%.
+            candidates = short.reject { |name, base| whole.key?(name) || !body.include?(base) }
+            next if candidates.empty?
+
+            # ONE line has to carry the module — itself, or a local a line
+            # above assigned from it. Anywhere-in-the-file was the first cut
+            # and it suppressed this gem's whole report: a doc comment naming
+            # PersonQuery three hundred lines above an unrelated to_h counted
+            # as serializing it. Following the local is what the line rule
+            # missed, and it is the shape every Rails controller has:
+            # `result = Q.execute!(...)`, then `render json: result.person`.
+            locals = Hash.new { |hash, key| hash[key] = [] }
+            body.each_line.with_index(1) do |line, number|
+              candidates.each do |name, base|
+                locals[name] << Regexp.last_match(1) if line.include?(base) && ASSIGN.match(line)
+              end
+              next unless SINKS.match?(line)
+
+              candidates.each do |name, base|
+                # the line naming the module is the better evidence; the local
+                # is what it falls back to
+                via = locals[name].find { |local| line.match?(/\b#{Regexp.escape(local)}\b/) } \
+                  unless line.include?(base)
+                next unless via || line.include?(base)
+
+                whole[name] ||= Excuse.new(Util.relative(path), number, line.strip, via)
+              end
+            end
+          end
+          Sweep.new(read, whole, files.size)
+        end
+      end
+
+      # Every generated prop, per query file. Query-driven like everything
+      # else: a struct exists because a query selected it.
+      def selections
+        @selections ||= @graphs.flat_map do |graph|
+          Util.query_files(graph.queries).flat_map do |path|
+            source = File.read(path)
+            name = graph.generated_names(path, source).first
+            next [] unless Object.const_defined?(name)
+
+            result = Object.const_get(name)
+            next [] unless result.const_defined?(:Result, false)
+
+            words = source.scan(/[A-Za-z_]\w*/).uniq
+            props(result.const_get(:Result, false))
+              .map { |struct, prop| Selection.new(path, name, struct, prop, wire_word(words, prop)) }
+          end
+        end
+      end
+
+      # How the query spells a prop, when that isn't the prop's own name — a
+      # camelCase field, an alias, a reserved rename. Read back off the query
+      # text rather than derived from the prop, since no rule inverts an
+      # alias; nil when the query spells it the same way, which is most of
+      # the time.
+      def wire_word(words, prop)
+        words.find { |word| word != prop.to_s && GraphWeaver::Codegen.prop_name(word) == prop.to_s }
+      end
+
+      # Nested structs are nested constants, so the props of a whole response
+      # are one walk down. Reported flat: a parent nothing reads makes its
+      # children unread too, and saying both is the honest count.
+      def props(struct, found = [])
+        struct.props.each_key { |prop| found << [struct, prop] }
+        struct.constants(false).each do |const|
+          nested = struct.const_get(const, false)
+          props(nested, found) if nested.is_a?(Class) && nested < T::Struct
+        end
+        found
+      end
+
+      def files
+        @files ||= @roots.flat_map { |root| collect(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)
+        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))
+            found << path
+          end
+        end
+        found
+      rescue SystemCallError
+        found
+      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
+      # `output` somewhere of its own.
+      def outputs
+        @outputs ||= (Util.generated_dirs + @graphs.map(&:output))
+          .flat_map { |pattern| Dir.glob(Util.resolve(pattern), File::FNM_PATHNAME) }
+          .to_set
+      end
+
+      def where
+        @roots.map { |root| (root == GraphWeaver.root) ? "." : Util.relative(root) }.join(", ")
+      end
+
+      def nothing_loaded
+        "nothing to check: no generated module is loaded for any query here (rake graph_weaver:generate)"
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/values.rb

@@ -50,6 +50,10 @@ class GraphWeaver::Internal::Values
   # What Codegen.scalar reports for a scalar nobody registered
   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
+
   # The fallback, for a scalar nobody registered: its prop is T.untyped, so
   # anything holds and a plausible shape beats a placeholder.
   NAMED_SHAPES = {
@@ -71,7 +75,13 @@ class GraphWeaver::Internal::Values
   # pin is resolved against the query, which is the fake's job. Left unsaid
   # they are the suite's, so a scalar only the app can write for is
   # fabricable from the cassette anonymizer too.
-  def initialize(seed: nil, values: nil, pins: nil)
+  # schema: which server is being faked. registry: the registrations the
+  # values have to satisfy — a Money registered for one graph is not a Money
+  # for the next, and only a caller holding the graph can say which. Left
+  # unsaid they are read back off the schema, which is the answer for every
+  # app with one graph running a live class.
+  def initialize(seed: nil, values: nil, pins: nil, schema: nil, registry: nil)
+    @registry = registry || GraphWeaver::Internal::Util.registry_for(schema)
     @rng = Random.new(seed || GraphWeaver::Testing.config.seed || Random.new_seed)
     @pins = (pins || GraphWeaver::Testing.config.overrides).transform_keys(&:to_s)
     @style = resolve_style(values)
@@ -86,7 +96,9 @@ class GraphWeaver::Internal::Values
   # alone. at: where the walk is ("reader.orders.0.total"), for that refusal;
   # a walk that doesn't track one leaves it unsaid.
   def scalar(type_name, field_name, coordinate = nil, at: nil)
-    return GraphWeaver::Internal::Overrides.resolve(@pins[type_name], rng) if @pins.key?(type_name)
+    if @pins.key?(type_name)
+      return wire(type_name, GraphWeaver::Internal::Overrides.resolve(@pins[type_name], rng), coordinate)
+    end
 
     registered, shape = resolve(type_name, coordinate)
     prop = underscore(field_name)
@@ -117,12 +129,31 @@ class GraphWeaver::Internal::Values
     # the plain-notation string BigDecimal() reads and #to_s("F") writes
     when :decimal then format("%.2f", @rng.rand(0.0..10_000.0))
     when :date then (Date.new(2020, 1, 1) + @rng.rand(0..2_000)).iso8601
-    when :time then Time.at(1_600_000_000 + @rng.rand(0..100_000_000)).utc.iso8601
+    # a fraction a quarter of the time: a JS/Apollo server writes milliseconds
+    # on every timestamp, and whole seconds alone can't show a lossy round trip
+    when :time then fake_time.then { |t| t.iso8601(t.subsec.zero? ? 0 : 3) }
     when :unregistered then "#{type_name}-#{@sequence += 1}" # nobody registered it: prop is T.untyped
     else unfakeable!(type_name, field_name, registered, coordinate, at)
     end
   end
 
+  # What the wire would carry for a pinned scalar. A pin may be written as the
+  # Ruby object an app reads back — a Time, a Money — and the registration
+  # says what the server sends for one; a value JSON can already hold stands
+  # 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) }
+
+    serialized = @registry.scalar(type_name, coordinate).serialize_value(value)
+    return serialized if WIRE.any? { |klass| serialized.is_a?(klass) }
+
+    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 " \
+      "is what the wire carries — register_scalar(#{type_name.inspect}) has no serialize: that can run " \
+      "against a value (a Proc builds source), so write the pin as the value the server would send"
+  end
+
   # same original id => same fake id, so relationships survive anonymization
   def mapped_id(original)
     @id_map[original] ||= (@sequence += 1).to_s
@@ -130,11 +161,16 @@ class GraphWeaver::Internal::Values
 
   private
 
+  def fake_time
+    usec = @rng.rand(0..3).zero? ? @rng.rand(1..999) * 1_000 : 0
+    Time.at(1_600_000_000 + @rng.rand(0..100_000_000), usec).utc
+  end
+
   # The registration in play and the shape it wants, memoized per scalar (or
   # per coordinate, where a field-level registration overrides it).
   def resolve(type_name, coordinate)
     @resolved[coordinate || type_name] ||= begin
-      registered = GraphWeaver::Codegen.scalar(type_name, coordinate)
+      registered = @registry.scalar(type_name, coordinate)
       [registered, shape_of(type_name, registered.type)]
     end
   end