graph_weaver 0.7.0 → 0.7.1

data/examples/github/queries/stargazers.graphql

@@ -0,0 +1,22 @@
+query($owner: String!, $name: String!, $first: Int!) {
+  repository(owner: $owner, name: $name) {
+    id
+    nameWithOwner
+    stargazerCount
+    stargazers(first: $first, orderBy: { field: STARRED_AT, direction: DESC }) {
+      edges {
+        starredAt
+        node {
+          login
+          name
+          repositories(first: 2, orderBy: { field: STARGAZERS, direction: DESC }) {
+            nodes {
+              nameWithOwner
+              stargazerCount
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/examples/github/queries/starred.graphql

@@ -0,0 +1,11 @@
+query($login: String!, $first: Int!) {
+  user(login: $login) {
+    starredRepositories(first: $first, orderBy: { field: STARRED_AT, direction: DESC }) {
+      totalCount
+      nodes {
+        nameWithOwner
+        stargazerCount
+      }
+    }
+  }
+}

data/examples/github/run.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# typed: false
+# frozen_string_literal: true
+
+# Star graph_weaver ⭐ (thanks!), then meet your fellow stargazers —
+# who they are, their biggest repos, and what else they've starred:
+#
+#      examples/github/run.rb
+require_relative "setup"
+
+# the checked-in typed modules (regenerate: examples/github/generate.rb)
+Dir[File.join(__dir__, "generated", "*.rb")].sort.each { |file| require file }
+
+OWNER = "dpep"
+NAME = "graph_weaver"
+
+repo = StargazersQuery.execute!(owner: OWNER, name: NAME, first: 1).repository
+abort "repository not found" unless repo
+
+# join the club (idempotent — starring twice is fine)
+starrable = StarMutation.execute!(id: repo.id).add_star&.starrable
+puts "⭐ starred #{repo.name_with_owner} — #{starrable&.stargazer_count} star(s). Thanks!"
+
+# refreshed, so the list includes you
+repo = StargazersQuery.execute!(owner: OWNER, name: NAME, first: 10).repository
+
+puts "\nThe stargazers:"
+repo.stargazers.edges&.each do |edge|
+  gazer = edge&.node
+  next unless gazer
+
+  who = gazer.name ? "#{gazer.login} (#{gazer.name})" : gazer.login
+  top = gazer.repositories.nodes&.compact&.map { |r| "#{r.name_with_owner} ⭐#{r.stargazer_count}" }
+  puts "  #{who} — starred #{edge.starred_at&.strftime("%Y-%m-%d")}"
+  puts "    top repos: #{top.join(", ")}" if top&.any?
+
+  # drill down: what else have they starred lately?
+  starred = StarredQuery.execute!(login: gazer.login, first: 3).user&.starred_repositories
+  next unless starred
+
+  also = starred.nodes&.compact&.reject { |r| r.name_with_owner == repo.name_with_owner }
+  puts "    also starred (#{starred.total_count} total): #{also.map(&:name_with_owner).join(", ")}" if also&.any?
+end

data/examples/github/setup.rb

@@ -0,0 +1,18 @@
+# typed: false
+# frozen_string_literal: true
+
+# Shared wiring for the GitHub example: auth and the client.
+require_relative "../../lib/graph_weaver"
+
+token = ENV["GITHUB_TOKEN"] || `gh auth token 2>/dev/null`.strip
+abort "need a token: `gh auth login`, or GITHUB_TOKEN=..." if token.empty?
+
+GraphWeaver.client = GraphWeaver.new(
+  "https://api.github.com/graphql",
+  auth: token,
+  # used by generate.rb (and any dynamic parse): the first introspection
+  # of GitHub's large schema dumps here — gitignored, a few seconds once,
+  # instant after. run.rb's checked-in generated modules never introspect,
+  # so running it alone won't create this file.
+  cache: File.join(__dir__, "schema.json"),
+)

data/examples/rick_and_morty.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# typed: false
+# frozen_string_literal: true
+
+# One notch up from countries.rb: filtered search, pagination, an aliased
+# field, and a block-built type helper — against the Rick and Morty API
+# (free, no auth, wubba lubba dub dub):
+#
+#      examples/rick_and_morty.rb [NAME]
+#      examples/rick_and_morty.rb morty
+require_relative "../lib/graph_weaver"
+
+api = GraphWeaver.new("https://rickandmortyapi.com/graphql")
+
+# decorate every Character struct generated from this type — derived values
+# live as methods, the wire data stays honest
+GraphWeaver.extend_type("Character") do
+  def emoji
+    { "Alive" => "🟢", "Dead" => "💀" }.fetch(status, "❓")
+  end
+end
+
+CharacterQuery = api.parse(<<~GRAPHQL)
+  query($name: String, $page: Int) {
+    characters(page: $page, filter: { name: $name }) {
+      # a GraphQL alias names the prop: `info.next_page`, not `info.next`
+      info { count pages nextPage: next }
+      results {
+        name
+        status
+        species
+        origin { name }
+        episode { name }
+      }
+    }
+  }
+GRAPHQL
+
+name = ARGV.first || "smith"
+page = 1
+total = nil
+
+loop do
+  characters = CharacterQuery.execute!(name:, page:).characters
+  abort "no characters match #{name.inspect}" if characters&.results.to_a.empty?
+
+  total ||= characters.info&.count
+  characters.results.compact.each do |character|
+    debut = character.episode.compact.first&.name
+    puts "#{character.emoji} #{character.name} — #{character.species} from #{character.origin&.name}, debuted in #{debut.inspect}"
+  end
+
+  page = characters.info&.next_page
+  break unless page
+end
+
+puts "\n#{total} character(s) matched #{name.inspect}"

data/graph_weaver.gemspec

@@ -10,9 +10,14 @@ Gem::Specification.new do |s|
   # CLAUDE.md/PLAN.md/REVIEW.md/NOTES.md/DECISIONS.md are written for whoever
   # works on the gem, not whoever installs it — and REVIEW.md carries examples
   # from before the API it describes was rewritten
-  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' ':!:examples' \
+  # examples/ ships (small plain text) so the README's links to it resolve for
+  # someone who only has the installed gem, not a checkout
+  # CHANGELOG.md doesn't (259 KB, ~16% of the package) — changelog_uri below
+  # points at the GitHub copy instead
+  s.files       = `git ls-files * ':!:spec' ':!:sorbet' ':!:bin' \
                      ':!:CLAUDE.md' ':!:PLAN.md' ':!:REVIEW.md' ':!:NOTES.md' \
-                     ':!:DECISIONS.md' ':!:Makefile' ':!:design'`.split("\n") + [".yardopts"]
+                     ':!:DECISIONS.md' ':!:CHANGELOG.md' ':!:Makefile' ':!:design' \
+                     ':!:research'`.split("\n") + [".yardopts"]
   s.homepage    = "https://github.com/dpep/graph_weaver"
   s.license     = "MIT"
   s.name        = "graph_weaver"
@@ -22,8 +27,12 @@ Gem::Specification.new do |s|
 
   s.metadata = {
     "bug_tracker_uri" => "#{s.homepage}/issues",
-    "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
+    # pinned to the release tag, not main — CHANGELOG.md isn't packaged, and
+    # main drifts ahead of whatever version this metadata shipped with
+    "changelog_uri" => "#{s.homepage}/blob/v#{s.version}/CHANGELOG.md",
     "documentation_uri" => "#{s.homepage}/tree/main/docs",
+    # no separate homepage_uri: identical to s.homepage, and `gem build` warns
+    # that rubygems.org only shows one of two metadata keys with the same uri
     "rubygems_mfa_required" => "true",
     "source_code_uri" => s.homepage,
   }

data/lib/graph_weaver/client.rb

@@ -128,6 +128,17 @@ class GraphWeaver::Client
       "this client has no transport (built from a schema dump) — pass a url or transport:"
   end
 
+  # How long a failed introspection answers for the threads behind it. The
+  # lock makes a cold schema one round trip at a time, so against a hung
+  # upstream every queued thread used to pay its own read_timeout in turn —
+  # 8 threads at the 30s default is four minutes of occupied worker, and the
+  # next wave paid it again. A second is enough to collapse a wave and the
+  # retry right behind it, and short enough that an upstream which comes back
+  # is tried again on the next request. Deliberately not a circuit breaker:
+  # nothing here counts failures or stays open.
+  FAILURE_TTL = 1.0
+  private_constant :FAILURE_TTL
+
   # The schema, introspecting through the transport on first use (cached
   # per the client's cache:/ttl:) unless one was given up front.
   #
@@ -136,7 +147,17 @@ class GraphWeaver::Client
   # in-flight thread, each of them also writing the cache file.
   def schema
     @schema_lock.synchronize do
-      @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+      next @schema if @schema
+      raise @schema_error if @schema_error && Process.clock_gettime(Process::CLOCK_MONOTONIC) < @schema_error_until
+
+      begin
+        @schema_error = nil
+        @schema = GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
+      rescue GraphWeaver::Error => e
+        @schema_error = e
+        @schema_error_until = Process.clock_gettime(Process::CLOCK_MONOTONIC) + FAILURE_TTL
+        raise
+      end
     end
   end
 

data/lib/graph_weaver/codegen.rb

@@ -1147,7 +1147,11 @@ class GraphWeaver::Codegen
   # about. Dispatch reads __typename, so the query must select it; for
   # interfaces the interface-level fields gather into every member.
   def union_members(type, selections)
-    raise ArgumentError, typename_refusal(type, selections) unless dispatchable_typename?(type, selections)
+    unless dispatchable_typename?(type, selections)
+      # a refusal about the query, like its siblings: branded and path-named,
+      # so generate! can collect it and rake names the file
+      raise GraphWeaver::Error, "#{@path ? "#{@path}: " : ""}#{typename_refusal(type, selections)}"
+    end
 
     selected_members(type, selections).sort_by(&:graphql_name).to_h do |possible|
       [possible.graphql_name, object_node(possible, selections, camelize(possible.graphql_name))]

data/lib/graph_weaver/context_seam.rb

@@ -0,0 +1,54 @@
+# typed: true
+# frozen_string_literal: true
+
+require "monitor"
+
+module GraphWeaver
+  # The settable GraphQL context, and the lock that guards it. {InProcess}
+  # and {Testing::Router} include it; so can any client of your own that
+  # wants the header seam.
+  #
+  # A `context:` proc is answered from one request's headers, which means
+  # assigning the client's context for the length of that dispatch — shared
+  # state, on the client. So the lock lives here, beside the field, rather
+  # than on whichever wrapper happens to be dispatching:
+  # {Testing::Endpoint} is built per request by `graphql: :wire`, and two of
+  # them over one client used to share nothing.
+  module ContextSeam
+    # the context handed to every query this client runs
+    attr_reader :context
+
+    def context=(value)
+      # Callability is settled by the field's owner, never by the
+      # per-request swap below — a resolved hash installed for one dispatch
+      # must not tell a concurrent one that this client has no seam.
+      @context_callable = value.respond_to?(:call)
+      @context = value
+    end
+
+    # Run the block with the context this request's headers mean — what
+    # {Testing::Endpoint} calls. A callable context is resolved and put back
+    # under the lock, so one request's identity can't leak into another's. A
+    # plain context has nothing to guard, so it is served concurrently.
+    def with_request_context(headers)
+      return yield unless @context_callable
+
+      @context_lock.synchronize do
+        seam = @context
+        @context = seam.call(headers)
+        begin
+          yield
+        ensure
+          @context = seam
+        end
+      end
+    end
+
+    # Call from your initializer. A Monitor rather than a Mutex: a resolver
+    # may re-enter the app.
+    private def init_context_seam(context)
+      @context_lock = Monitor.new
+      self.context = context
+    end
+  end
+end

data/lib/graph_weaver/errors.rb

@@ -5,6 +5,7 @@ require "sorbet-runtime"
 require "time" # Time.httpdate, for Retry-After
 
 require_relative "inflect"
+require_relative "internal/endpoint"
 require_relative "internal/headers"
 require_relative "logging"
 
@@ -125,15 +126,26 @@ module GraphWeaver
     attr_reader :url
 
     sig do
-      params(status: Integer, body: T.untyped, headers: T::Hash[String, String], url: T.nilable(String)).void
+      params(
+        status: Integer,
+        body: T.untyped,
+        headers: T::Hash[String, String],
+        url: T.nilable(String),
+        detail: T.nilable(String),
+      ).void
     end
-    def initialize(status:, body: nil, headers: {}, url: nil)
+    def initialize(status:, body: nil, headers: {}, url: nil, detail: nil)
       @status = status
       @body = body
       @url = url
       @headers = T.let(GraphWeaver::Internal::Headers.wrap(headers), T::Hash[String, String])
-      snippet = body.to_s.empty? ? "" : ": #{body.to_s[0, 500]}"
-      super("HTTP #{status}#{snippet}#{" — #{hint}" if hint}#{" — POST #{url}" if url}")
+      # A message never carries a body. `detail` is what WE say went wrong; the
+      # bytes the server sent stay on #body, the way #to_h already keeps the
+      # headers off — an error page that echoes the request (Rails' own dev
+      # page, many proxies) carries the caller's variables and our own
+      # Authorization header, and every raised error writes its message to the
+      # log at warn.
+      super("HTTP #{status}#{" — #{detail}" if detail}#{" — #{hint}" if hint}#{" — POST #{url}" if url}")
     end
 
     # What to do about this status, where the status says it. A redirect is
@@ -145,26 +157,22 @@ module GraphWeaver
     sig { returns(T.nilable(String)) }
     def hint
       if REDIRECTS.include?(status)
+        # the destination is a url the SERVER chose — said the way we say our
+        # own, and without the framing a header value could smuggle in
         location = headers["location"]
+        location &&= GraphWeaver::Internal::Redact.tag(GraphWeaver::Internal::Endpoint.safe(location))
         "redirects are not followed#{" — point the client at #{location}" if location}"
       elsif [401, 403].include?(status)
         "the server rejected the credentials — check auth: (the token, and its scopes)"
       end
     end
 
-    # Seconds to wait per the server's Retry-After, which is either a
-    # delay in seconds or an HTTP-date. nil when absent or unparseable;
-    # negative dates (already past) clamp to 0. See RFC 9110 §10.2.3.
+    # Seconds to wait per the server's Retry-After, or nil. Parsed off the
+    # headers, which is also where a returned envelope reads it — so one rule
+    # answers a rate limit however it arrived.
     sig { returns(T.nilable(Float)) }
     def retry_after
-      value = headers["retry-after"]&.strip
-      return if value.nil? || value.empty?
-      return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
-
-      seconds = Time.httpdate(value) - Time.now
-      [seconds, 0.0].max
-    rescue ArgumentError
-      nil
+      GraphWeaver::Internal::Headers.wrap(headers).retry_after
     end
 
     # True when the server said "you're going too fast" — 429, or the

data/lib/graph_weaver/federation.rb

@@ -142,7 +142,10 @@ module GraphWeaver
       def report
         return "#{@source} names no subgraphs" if @table.subgraphs.empty?
 
-        [headline, *section(STALE, @stale), *shape_section, *section(UNCOMPOSED, @uncomposed),
+        # the scope caveat rides with the verdict that overclaims without it;
+        # a drift report is already telling you to recompose
+        [headline, *(NOT_COMPARED unless drift? || vacuous?),
+          *section(STALE, @stale), *shape_section, *section(UNCOMPOSED, @uncomposed),
           *skipped_section, *faked_section].join("\n")
       end
       alias to_s report
@@ -154,6 +157,12 @@ module GraphWeaver
 
       private
 
+      # A pass says the supergraph still describes the fields these schemas
+      # have — not that the next composition would succeed. Both categories
+      # below are composition's business, and this reads neither.
+      NOT_COMPARED = "not compared: @key (added, removed, or made unresolvable), and one field " \
+        "two subgraphs define without @shareable — recompose to catch those"
+
       STALE = "stale — the supergraph carries these, no schema here defines them (recompose):"
       SHAPE = "shape — both carry these, with different types (recompose):"
       UNCOMPOSED = "not composed in — a schema here defines these, the supergraph doesn't carry them:"
@@ -298,7 +307,7 @@ module GraphWeaver
         verdict =
           if counts.any? then counts.join(", ")
           elsif vacuous? then "compared against nothing here"
-          else "matches the schemas here"
+          else "matches the schemas here, field for field and type for type"
           end
         "#{@source}: #{verdict} " \
           "(checked #{@checked.size} of #{@table.subgraphs.size} subgraphs)"

data/lib/graph_weaver/in_process.rb

@@ -5,6 +5,7 @@ require "json"
 
 require_relative "errors"
 require_relative "internal"
+require_relative "context_seam"
 require_relative "parsing"
 require_relative "transport"
 
@@ -32,13 +33,13 @@ require_relative "transport"
 # is usually the whole reason you're running in-process.
 class GraphWeaver::InProcess
   include GraphWeaver::Parsing
+  # #context/#context= plus the lock over them: Testing::Endpoint answers a
+  # `context:` proc from one request's headers by writing this field, so the
+  # field's owner owns the lock
+  include GraphWeaver::ContextSeam
 
-  # the schema queries run against, and the context handed to every one
-  attr_reader :schema, :context
-
-  # settable so Testing::Endpoint can answer a `context:` proc from the
-  # request's headers and put it back — the same seam Router#context= is
-  attr_writer :context
+  # the schema queries run against
+  attr_reader :schema
 
   def initialize(schema, context: {})
     unless schema.respond_to?(:execute)
@@ -46,12 +47,13 @@ class GraphWeaver::InProcess
     end
 
     @schema = schema
-    @context = context
+    init_context_seam(context)
   end
 
   def execute(query, variables: {}, operation_name: nil)
     operation_name ||= GraphWeaver::Internal::Wire.operation_name(query)
-    payload = { url: nil, schema: schema_label, operation: operation_name, client: self.class }
+    payload = { url: nil, schema: schema_label, operation: operation_name, client: self.class,
+                kind: GraphWeaver::Internal::Wire.kind(query) }
 
     GraphWeaver::Internal::Log.instrument(GraphWeaver::EXECUTE_EVENT, payload) do
       perform(query, variables, operation_name)
@@ -84,7 +86,11 @@ class GraphWeaver::InProcess
     # a resolver blew up. The same failure over HTTP arrives as a 500, so
     # raise what HTTP would — code that rescues GraphWeaver::Error, or
     # branches on ServerError#status, behaves the same either side.
-    raise GraphWeaver::ServerError.new(status: 500, body: "#{e.class}: #{e.message}")
+    # detail:, not body: — there was no response, so there are no bytes to
+    # hold, and the diagnosis is this process's own exception
+    raise GraphWeaver::ServerError.new(
+      status: 500, detail: "#{e.class}: #{GraphWeaver::Internal::Redact.cap(e.message)}",
+    )
   end
 
   # never leak the context (session tokens, current_user) through logs or

data/lib/graph_weaver/internal/endpoint.rb

@@ -54,20 +54,22 @@ module GraphWeaver
         def drop_secrets(query)
           kept = query.split("&").reject do |pair|
             name, value = pair.split("=", 2)
-            value && Redact.filtered?(URI.decode_www_form_component(name))
+            value && Redact.credential?(URI.decode_www_form_component(name))
           end
           kept.join("&") unless kept.empty?
         end
 
         # Which query parameters are secret is the same question
         # GraphWeaver.filter_parameters already answers for variables, so a
-        # scrubbed log reads the same either side of the seam. Split rather
-        # than decoded and re-encoded: every parameter that stays is printed
-        # exactly as it was sent.
+        # scrubbed log reads the same either side of the seam — widened by the
+        # default names, which apply here even when the app has emptied its
+        # list (see Redact.credential?). Split rather than decoded and
+        # re-encoded: every parameter that stays is printed exactly as it was
+        # sent.
         def scrub_query(query)
           query.split("&").map do |pair|
             name, value = pair.split("=", 2)
-            next pair if value.nil? || !Redact.filtered?(URI.decode_www_form_component(name))
+            next pair if value.nil? || !Redact.credential?(URI.decode_www_form_component(name))
 
             "#{name}=#{GraphWeaver::FILTERED}"
           end.join("&")

data/lib/graph_weaver/internal/headers.rb

@@ -1,6 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
+require "time" # Time.httpdate, for Retry-After
+
 module GraphWeaver
   module Internal
     # Response headers, as ServerError carries them. HTTP field names are
@@ -42,6 +44,23 @@ module GraphWeaver
         rest.empty? ? value : value&.dig(*rest)
       end
 
+      # Seconds to wait per the server's Retry-After, which is either a delay
+      # in seconds or an HTTP-date. nil when absent or unparseable; a date
+      # already past clamps to 0. See RFC 9110 §10.2.3.
+      #
+      # Here rather than on ServerError because a rate limit reaches a caller
+      # two ways — raised, and returned as the envelope a 4xx/5xx WITH a
+      # GraphQL errors body makes — and both have to read the one rule.
+      def retry_after
+        value = self["retry-after"]&.strip
+        return if value.nil? || value.empty?
+        return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
+
+        [Time.httpdate(value) - Time.now, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+
       def key?(name) = super(Headers.fold(name))
       alias_method :has_key?, :key?
       alias_method :include?, :key?

data/lib/graph_weaver/internal.rb

@@ -52,19 +52,29 @@ module GraphWeaver
 
         # The module a .graphql file generates, and the basename of the file
         # it generates into: the camelized file name plus the operation's own
-        # word.
+        # word. Every run of non-alphanumerics in the name is a word boundary,
+        # and a trailing extension naming the document's own operation kind is
+        # dropped rather than doubled.
         #
         #      person.graphql          => PersonQuery       (person_query.rb)
         #      save_list_entry.graphql => SaveListEntryMutation
         #                                 (save_list_entry_mutation.rb)
+        #      get-hello.graphql       => GetHelloQuery     (get_hello_query.rb)
+        #      hello.query.graphql     => HelloQuery        (hello_query.rb)
         #
         # Every naming site goes through here — generate!, parse(path), and
         # load_queries! — so the constant a file produces is the same one
         # whichever door you came in by, and the file it lands in matches it.
         def generated_names(path, source)
-          base = File.basename(path, ".*")
-          suffix = operation_suffix(source)
-          ["#{Inflect.camelize(base)}#{suffix}", "#{base}_#{suffix.downcase}.rb"]
+          kind = operation_kind(source)
+          base = strip_kind_extension(File.basename(path, ".*"), kind, path)
+          stem = base.gsub(/[^A-Za-z0-9]+/, "_")
+          suffix = (kind == "mutation") ? "Mutation" : "Query"
+          name = Inflect.camelize(stem)
+          # all punctuation camelizes to nothing, which would leave the suffix
+          # standing alone as the whole name — keep the base so it stays refusable
+          name = base if name.empty?
+          ["#{name}#{suffix}", "#{stem}_#{suffix.downcase}.rb"]
         end
 
         # just the module name — see generated_names
@@ -240,13 +250,36 @@ module GraphWeaver
           source
         end
 
-        # "Mutation" for a mutation document, "Query" for everything else.
-        def operation_suffix(source)
+        # The document's operation kind — "query", "mutation" or
+        # "subscription" — or nil when it holds no operation or won't parse.
+        # The one source of truth for the word a module name ends in AND for
+        # the file-name extension that word makes redundant.
+        def operation_kind(source)
           operation = GraphQL.parse(source).definitions
             .grep(GraphQL::Language::Nodes::OperationDefinition).first
-          (operation&.operation_type == "mutation") ? "Mutation" : "Query"
+          operation && (operation.operation_type || "query") # `{ hello }` is shorthand for a query
         rescue GraphQL::ParseError
-          "Query" # unparseable: codegen brands the real error a moment later
+          nil # unparseable: codegen brands the real error a moment later
+        end
+
+        # GraphQL's operation kinds, as a file name spells them. Apollo, Relay
+        # and GitLab's frontend all name a query file for its operation, so
+        # `blob_content.query.graphql` says in the extension exactly what the
+        # module's own suffix says — drop it rather than emit BlobContentQueryQuery.
+        # `_query` inside a snake_case name is a word OF the name, not this, so
+        # nothing that generates today is renamed.
+        OPERATION_EXTENSION = /\.(query|mutation|subscription)\z/i
+        private_constant :OPERATION_EXTENSION
+
+        def strip_kind_extension(base, kind, path)
+          declared = base[OPERATION_EXTENSION, 1]&.downcase
+          stem = declared && base[0...-(declared.length + 1)]
+          return base if stem.nil? || stem.empty?
+          return stem if kind.nil? || kind == declared
+
+          raise GraphWeaver::Error, "#{relative(path)}: the file name ends .#{declared}, but the " \
+            "document defines a #{kind} — rename it #{stem}.#{kind}#{File.extname(path)} " \
+            "or drop the .#{declared}"
         end
       end
     end
@@ -350,7 +383,8 @@ module GraphWeaver
       # every request, and the only way to be wrong (a field literally named
       # `mutation` opening a line) errs toward not retrying.
       MUTATION_PATTERN = /^[ \t]*mutation\b/
-      private_constant :MUTATION_PATTERN
+      SUBSCRIPTION_PATTERN = /^[ \t]*subscription\b/
+      private_constant :MUTATION_PATTERN, :SUBSCRIPTION_PATTERN
 
       REQUEST_MUTEX = Mutex.new
       private_constant :REQUEST_MUTEX
@@ -365,16 +399,35 @@ module GraphWeaver
 
         def mutation?(query) = MUTATION_PATTERN.match?(query)
 
+        # What this document runs, for the instrumentation payload — :query
+        # for the shorthand `{ ... }` document too, which is what it is.
+        # Built on mutation? rather than beside it, so an APM's write-failure
+        # rate and the decision not to retry can't come to disagree.
+        def kind(query)
+          return :mutation if mutation?(query)
+
+          SUBSCRIPTION_PATTERN.match?(query) ? :subscription : :query
+        end
+
         # one error in the shape a GraphQL response carries them
         def graphql_error(message, code)
           { "message" => message, "extensions" => { "code" => code } }
         end
 
-        # "[req 3 FilteredPokemon]" — a per-process request id plus the
-        # operation name, when there is one
+        # "[req 4123-3 FilteredPokemon]" — the pid, this process's own
+        # request count, and the operation name when there is one.
+        #
+        # Both halves, because a Puma cluster forks: the counter is inherited
+        # with everything else, so without the reset every worker continues
+        # the master's sequence, and without the pid two workers' "[req 3]"
+        # are two unrelated requests in one aggregated log.
         def log_tag(operation_name = nil)
-          id = REQUEST_MUTEX.synchronize { @request_count = (@request_count || 0) + 1 }
-          "[req #{id}#{" #{operation_name}" if operation_name}]"
+          pid = Process.pid
+          id = REQUEST_MUTEX.synchronize do
+            @request_pid, @request_count = pid, 0 unless @request_pid == pid
+            @request_count += 1
+          end
+          "[req #{pid}-#{id}#{" #{operation_name}" if operation_name}]"
         end
 
         def truncate_for_log(query)