graph_weaver 0.1.0 → 0.2.0

data/lib/graph_weaver/errors.rb

@@ -1,16 +1,27 @@
 # typed: true
 # frozen_string_literal: true
 
-require "set"
 require "sorbet-runtime"
 require_relative "inflect"
+require_relative "logging"
 
 module GraphWeaver
   # Base for every error GraphWeaver raises — rescue this to catch them
   # all. #message is the human-friendly side; #to_h is the machine side —
   # a JSON-ready Hash (string keys) for logging, agents, or surfacing
-  # structured failures to users. Subclasses merge in their specifics.
+  # structured failures to users. One subclass per failure site —
+  # {TransportError} (never reached the server), {ServerError} (non-2xx),
+  # {QueryError} (GraphQL-level errors), {TypeError} (response wouldn't
+  # cast), {ValidationError} (build time) — each merging its specifics
+  # into #to_h.
   class Error < StandardError
+    # every GraphWeaver error surfaces on the logger too (see
+    # GraphWeaver.logger) — construction here means a raise
+    def initialize(*args)
+      super
+      GraphWeaver.log(:warn) { "#{self.class.name}: #{message}" }
+    end
+
     def to_h
       { "error" => self.class.name, "message" => message }
     end
@@ -26,14 +37,14 @@ module GraphWeaver
   end
 
   class << self
-    # The exception classes the bundled executors reclassify as
+    # The exception classes the bundled transports reclassify as
     # TransportError — network-level failures where the request never
     # reached the server. A mutable Set: each transport contributes its own
     # on load (net/http adds Timeout/SSL, Faraday adds its ConnectionFailed,
     # …), and you can add more so they get the same handling:
     #
-    #   GraphWeaver.transport_errors << MyPool::TimeoutError
-    #   GraphWeaver.register_transport_error(Adapter::ResetError)
+    #      GraphWeaver.transport_errors << MyPool::TimeoutError
+    #      GraphWeaver.register_transport_error(Adapter::ResetError)
     #
     # SystemCallError covers every Errno::* (connection refused/reset, host
     # unreachable); SocketError covers DNS.
@@ -72,11 +83,12 @@ module GraphWeaver
   class GraphQLError
     attr_reader :message, :locations, :path, :extensions
 
-    def initialize(message:, locations: [], path: nil, extensions: {})
+    def initialize(message:, locations: [], path: nil, extensions: {}, type: nil)
       @message = message
       @locations = locations
       @path = path
       @extensions = extensions
+      @error_type = type
     end
 
     def self.from_h(hash)
@@ -85,13 +97,16 @@ module GraphWeaver
         locations: hash["locations"] || [],
         path: hash["path"],
         extensions: hash["extensions"] || {},
+        type: hash["type"],
       )
     end
 
     # The machine-readable error code, e.g. "THROTTLED" — the thing to
-    # branch on. nil when the server didn't set extensions.code.
+    # branch on. Read from extensions.code (the Apollo/spec-adjacent
+    # convention) or a top-level "type" (GitHub's dialect: NOT_FOUND,
+    # FORBIDDEN). nil when the server sent neither.
     def code
-      extensions["code"]
+      extensions["code"] || @error_type
     end
 
     # Message shapes servers use when they reject the *shape* of a query
@@ -166,8 +181,8 @@ module GraphWeaver
 
     # True when any error looks like the server rejected the query's
     # shape — the schema has likely changed since the module was
-    # generated. Regenerate (bin/generate) and/or refresh the schema
-    # cache (delete the cache: file, or wait out its ttl).
+    # generated. Refresh the schema dump and regenerate (rake
+    # graph_weaver:schema:refresh && rake graph_weaver:generate).
     def schema_stale?
       errors.any?(&:validation?)
     end
@@ -175,9 +190,9 @@ module GraphWeaver
     # Errors grouped by the field they point at (index-stripped dotted
     # path; nil key for global errors) — iterate with each_error:
     #
-    #   response.each_error do |field, errors|
-    #     form.add_error(field, errors.map(&:message))
-    #   end
+    #      response.each_error do |field, errors|
+    #        form.add_error(field, errors.map(&:message))
+    #      end
     def errors_by_field
       errors.group_by(&:field)
     end
@@ -213,8 +228,8 @@ module GraphWeaver
     # actual records that failed inlined — "the 3 in people.3.email is
     # useless to a user; people.email plus which people is the answer".
     #
-    #   { "people.email" => { "messages" => [...], "codes" => [...],
-    #     "entity_ids" => ["7", "9"], "errors" => [full to_h...] } }
+    #      { "people.email" => { "messages" => [...], "codes" => [...],
+    #        "entity_ids" => ["7", "9"], "errors" => [full to_h...] } }
     def report
       errors_by_field.to_h do |field, field_errors|
         [field, {
@@ -264,7 +279,7 @@ module GraphWeaver
     def summary
       first = errors.first
       more = errors.size > 1 ? " (and #{errors.size - 1} more)" : ""
-      drift = schema_stale? ? " — the server rejected the query shape: the schema may have changed since generation; regenerate modules (bin/generate) and/or refresh the schema cache" : ""
+      drift = schema_stale? ? " — the server rejected the query shape: the schema may have changed since generation; refresh the schema dump and regenerate (rake graph_weaver:schema:refresh && rake graph_weaver:generate)" : ""
       "GraphQL query failed: #{first}#{more}#{drift}"
     end
   end
@@ -288,10 +303,11 @@ module GraphWeaver
     end
   end
 
-  # Build-time: the query didn't validate against the schema. Kept an
-  # ArgumentError for source compatibility, but carries the structured
-  # validation errors (message + line/column) rather than a joined string.
-  class ValidationError < ArgumentError
+  # Build-time: the query didn't validate against the schema. Carries the
+  # structured validation errors (message + line/column) rather than a
+  # joined string. Under the Error umbrella like everything else raised
+  # here (through 0.1.0 it was an ArgumentError instead).
+  class ValidationError < Error
     attr_reader :errors
 
     def initialize(errors)
@@ -300,11 +316,7 @@ module GraphWeaver
     end
 
     def to_h
-      {
-        "error" => self.class.name,
-        "message" => message,
-        "errors" => errors.map { |e| e.transform_keys(&:to_s) },
-      }
+      super.merge("errors" => errors.map { |e| e.transform_keys(&:to_s) })
     end
   end
 end

data/lib/graph_weaver/hints.rb

@@ -0,0 +1,63 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "inflect"
+
+module GraphWeaver
+  # Included in generated response structs. GraphQL's camelCase fields
+  # become snake_case props, and reaching for the wire name is a classic
+  # stumble — result.nameWithOwner instead of result.name_with_owner.
+  # Catch the miss and point at the prop that does exist ("use ..." when
+  # the mapping is exact, "did you mean ...?" for a near-miss typo).
+  # (Typed call sites get this hint earlier, from srb tc.)
+  module Hints
+    include Kernel # for sorbet: hosts are Objects
+
+    # Guard for generated input-struct .coerce: a hash key that matches
+    # no prop raises (spellchecked) instead of silently dropping — a
+    # typo'd filter key must not become "match everything" on the wire.
+    def self.validate_keys!(struct, hash)
+      known = struct.props.keys.map(&:to_s)
+      unknown = hash.keys.map(&:to_s) - known
+      return if unknown.empty?
+
+      hints = unknown.map do |key|
+        prop = GraphWeaver::Inflect.underscore(key)
+        suggestion = if known.include?(prop)
+          prop # a wire-cased key — the exact snake_case prop exists
+        elsif defined?(DidYouMean::SpellChecker)
+          DidYouMean::SpellChecker.new(dictionary: known).correct(prop).first
+        end
+        suggestion ? "#{key} (did you mean '#{suggestion}'?)" : key
+      end
+      raise ArgumentError, "unknown key(s) for #{struct}: #{hints.join(", ")}"
+    end
+
+    def method_missing(name, *args, &block)
+      if args.empty? && (hint = prop_hint(name.to_s))
+        raise NoMethodError, "undefined method '#{name}' for #{self.class} — #{hint}"
+      end
+
+      super
+    end
+
+    private
+
+    def prop_hint(name)
+      prop = GraphWeaver::Inflect.underscore(name)
+      if prop != name && respond_to?(prop)
+        return "GraphQL fields generate snake_case props; use '#{prop}'"
+      end
+
+      return unless defined?(DidYouMean::SpellChecker)
+
+      # a guess, not a mapping — spellcheck the (underscored) miss
+      # against the props that exist, so typos in either casing land
+      props = T.unsafe(self.class).props.keys.map(&:to_s)
+      suggestion = DidYouMean::SpellChecker.new(dictionary: props).correct(prop).first
+      "did you mean '#{suggestion}'?" if suggestion
+    end
+  end
+end

data/lib/graph_weaver/inflect.rb

@@ -12,7 +12,8 @@ module GraphWeaver
     end
 
     def camelize(name)
-      name.split("_").map { |part| "#{part[0].upcase}#{part[1..]}" }.join
+      # reject: leading underscores split into empty parts (_Service, _and)
+      name.split("_").reject(&:empty?).map { |part| "#{part[0].upcase}#{part[1..]}" }.join
     end
   end
 end

data/lib/graph_weaver/logging.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  class << self
+    # Where GraphWeaver narrates what it's doing — anything
+    # stdlib-Logger-compatible (Logger, Rails.logger, semantic_logger...).
+    # Silent by default; Rails apps get Rails.logger wired by the railtie.
+    #
+    #      GraphWeaver.logger = Logger.new($stdout, level: Logger::INFO)
+    #
+    # What logs where:
+    #   debug — full queries + variables on the wire, responses
+    #           (status/bytes/ms), connection lifecycle, parsed modules
+    #   info  — schema introspection and cache decisions, generated files
+    #           written, query modules loaded
+    #   warn  — every GraphWeaver error raised
+    #
+    # Queries, variables, and responses appear at debug ONLY — they can
+    # carry PII. Auth headers never log.
+    attr_accessor :logger
+
+    # Internal: level-gated and lazy — the block only runs when a logger
+    # is listening. Messages carry "graph_weaver" as progname.
+    def log(level, &block)
+      logger&.public_send(level, "graph_weaver", &block)
+    end
+
+    # Internal: run the block, logging "<label> (Nms)" at level — timing
+    # skipped entirely when no logger is set. Returns the block's value.
+    def log_timed(level, label)
+      return yield unless logger
+
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+      log(level) { "#{label} (#{ms}ms)" }
+      result
+    end
+  end
+end

data/lib/graph_weaver/railtie.rb

@@ -0,0 +1,29 @@
+# typed: ignore — Rails::Railtie DSL
+# frozen_string_literal: true
+
+# Rails wiring, so the conventional layout needs no ceremony:
+#
+# - rake tasks: Rails.application.load_tasks collects every Railtie's
+#   rake_tasks block, so graph_weaver:* tasks appear with no Rakefile
+#   edit. (Outside Rails there is no task-discovery hook — add
+#   `require "graph_weaver/tasks"` to your Rakefile.)
+# - generated modules: required at boot when generated_path exists,
+#   after config/initializers (registrations and GraphWeaver.client=
+#   run first — block-built type helpers must exist before the files
+#   that include them load). load_generated! stays idempotent, so
+#   calling it yourself too is harmless.
+class GraphWeaver::Railtie < Rails::Railtie
+  rake_tasks do
+    require "graph_weaver/tasks"
+  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?
+  end
+
+  initializer "graph_weaver.load_generated", after: :load_config_initializers do
+    GraphWeaver.load_generated! if Dir.exist?(GraphWeaver.generated_path)
+  end
+end

data/lib/graph_weaver/retry.rb

@@ -0,0 +1,97 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "errors"
+
+# Wraps any client/transport with configurable retries — it satisfies
+# the same execute contract, so it layers over HTTP, Faraday, or
+# anything else:
+#
+#      client = GraphWeaver::Retry.new(
+#        GraphWeaver::Transport::HTTP.new(url),
+#        tries: 5,                        # total attempts, first included
+#        on: [GraphWeaver::TransportError, GraphWeaver::ServerError],
+#        backoff: :exponential,           # or :linear, or ->(attempt) { seconds }
+#        base: 0.5, max: 30,              # seconds; delays clamp at max:
+#        jitter: true,                    # randomize each delay by 50-100%
+#        retry_codes: ["THROTTLED"],      # also retry GraphQL errors by code
+#      )
+#
+# What retries, by default:
+#   - TransportError: always (the request never arrived)
+#   - ServerError: only 5xx — a 4xx is a bug in the request, retrying
+#     won't fix it. Override with retry_if: ->(error) { ... }
+#   - responses whose GraphQL error codes intersect retry_codes: (off by
+#     default — pass the codes your API uses for transient failures)
+#
+# Exhausting tries re-raises the last error (or returns the last
+# code-matched response).
+class GraphWeaver::Retry
+  BACKOFFS = {
+    exponential: ->(base, attempt) { base * (2**(attempt - 1)) },
+    linear: ->(base, attempt) { base * attempt },
+  }.freeze
+
+  # retry 5xx, not 4xx; everything else listed in on: retries
+  DEFAULT_RETRY_IF = lambda do |error|
+    !error.is_a?(GraphWeaver::ServerError) || error.status >= 500
+  end
+
+  def initialize(client, tries: 3, on: [GraphWeaver::TransportError, GraphWeaver::ServerError],
+    backoff: :exponential, base: 0.5, max: 30, jitter: true, retry_if: DEFAULT_RETRY_IF,
+    retry_codes: [], sleeper: nil)
+    raise ArgumentError, "tries: must be >= 1" unless tries >= 1
+
+    @client = client
+    @tries = tries
+    @on = on
+    @backoff = if backoff.is_a?(Proc)
+      ->(_base, attempt) { backoff.call(attempt) } # custom: ->(attempt) { seconds }
+    else
+      BACKOFFS.fetch(backoff) {
+        raise ArgumentError, "backoff: must be :exponential, :linear, or a Proc, got #{backoff.inspect}"
+      }
+    end
+    @base = base
+    @max = max
+    @jitter = jitter
+    @retry_if = retry_if
+    @retry_codes = retry_codes
+    @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+  end
+
+  # surface the wrapped transport's endpoint (schema-dump provenance)
+  def url
+    @client.url if @client.respond_to?(:url)
+  end
+
+  def execute(query, variables: {})
+    attempt = 0
+
+    loop do
+      attempt += 1
+      begin
+        response = @client.execute(query, variables:)
+        return response unless attempt < @tries && retryable_response?(response)
+      rescue *@on => e
+        raise if attempt >= @tries || !@retry_if.call(e)
+      end
+
+      @sleeper.call(delay(attempt))
+    end
+  end
+
+  private
+
+  def retryable_response?(response)
+    return false if @retry_codes.empty?
+
+    codes = (response.to_h["errors"] || []).filter_map { |error| error.dig("extensions", "code") }
+    codes.intersect?(@retry_codes)
+  end
+
+  def delay(attempt)
+    seconds = [@backoff.call(@base, attempt), @max].min.to_f
+    @jitter ? seconds * (0.5 + rand * 0.5) : seconds
+  end
+end

data/lib/graph_weaver/rspec.rb

@@ -6,23 +6,28 @@ require_relative "testing"
 # RSpec integration — require from your spec helper instead of
 # "graph_weaver/testing":
 #
-#   require "graph_weaver/rspec"
+#      require "graph_weaver/rspec"
 #
-#   GraphWeaver::Testing.configure do |config|
-#     config.schema = MySchema
-#     config.auto_fake = true   # every example runs against a FakeExecutor
-#   end
+# That one line is the whole setup in a conventional app: the schema
+# auto-locates from the committed dump (GraphWeaver.schema_path) and
+# auto_fake defaults on, so every example runs against a schema-correct
+# fake. Configure to override:
+#
+#      GraphWeaver::Testing.configure do |config|
+#        config.schema = MySchema     # instead of the located dump
+#        config.auto_fake = false     # opt out of per-example fakes
+#      end
 #
 # What it wires up:
 #   - seed: defaults to rspec's --seed, so `rspec --seed 1234` reproduces
 #     fake data along with test order
-#   - auto_fake: when on (and schema is set), each example gets a fresh
-#     seeded FakeExecutor installed as GraphWeaver.executor — generated
-#     modules run in test mode with zero per-test setup. The prior
-#     executor is restored after each example.
+#   - auto_fake: when on (and a schema resolves), each example gets a
+#     fresh seeded FakeClient installed as GraphWeaver.client —
+#     generated modules run in test mode with zero per-test setup. The
+#     prior client is restored after each example.
 #
-# note: modules generated with a baked-in executor: constant don't consult
-# GraphWeaver.executor — generate without executor: to make them fakeable.
+# note: modules generated with a baked-in client: constant don't consult
+# GraphWeaver.client — generate without client: to make them fakeable.
 module GraphWeaver
   module Testing
     module RSpecIntegration
@@ -36,15 +41,15 @@ module GraphWeaver
           config = GraphWeaver::Testing.config
           next unless config.auto_fake && config.schema
 
-          @__graph_weaver_prior_executor = GraphWeaver.instance_variable_get(:@executor)
-          GraphWeaver.executor = FakeExecutor.new(schema: config.schema)
+          @__graph_weaver_prior_client = GraphWeaver.client
+          GraphWeaver.client = FakeClient.new(schema: config.schema)
         end
 
         rspec_config.after(:each) do
           config = GraphWeaver::Testing.config
           next unless config.auto_fake && config.schema
 
-          GraphWeaver.executor = @__graph_weaver_prior_executor
+          GraphWeaver.client = @__graph_weaver_prior_client
         end
       end
     end

data/lib/graph_weaver/schema_loader.rb

@@ -15,7 +15,7 @@ module GraphWeaver::SchemaLoader
   #   - a file path — .json (introspection) or .graphql/.gql (SDL)
   #   - raw content — introspection JSON (starts with "{") or SDL
   # so a cache round-trip is symmetrical with introspect:
-  #   SchemaLoader.load(cached_json)  # from Rails.cache/redis/...
+  #      SchemaLoader.load(cached_json)  # from Rails.cache/redis/...
   def self.load(source)
     return GraphQL::Schema.from_introspection(source) if source.is_a?(Hash)
 
@@ -39,43 +39,179 @@ module GraphWeaver::SchemaLoader
     end
   end
 
-  # Run the standard introspection query through an executor and build a
+  # Run the standard introspection query through a transport and build a
   # schema from the result:
   #
-  #   executor = GraphWeaver::HttpExecutor.new(url, headers: { ... })
-  #   schema = GraphWeaver::SchemaLoader.introspect(executor)
+  #      transport = GraphWeaver::Transport::HTTP.new(url, headers: { ... })
+  #      schema = GraphWeaver::SchemaLoader.introspect(transport)
   #
-  # Introspecting a large API takes seconds, so cache: (a file path)
-  # stores the raw introspection JSON and reuses it until ttl: seconds
-  # elapse (no ttl = until the file is deleted). GraphQL has no standard
-  # schema-version signal to invalidate on — a stale cache surfaces as
-  # server-side validation errors (see QueryError#schema_stale?), so pick
-  # a ttl that matches how fast the API moves, or delete the file.
+  # Introspecting a large API takes seconds, so cache: dumps the schema
+  # to a file and reuses it until ttl: seconds elapse (no ttl = until the
+  # file is deleted). cache: takes
+  #   - true — GraphWeaver.schema_path, the file the generation workflow
+  #     reads (its extension picks the format)
+  #   - a path — the extension picks the format: .json is the verbatim
+  #     introspection result, .graphql/.gql is SDL (human-readable,
+  #     PR-reviewable diffs); both load back identically
+  #   - :json / :graphql / :gql — GraphWeaver.schema_path's location, in
+  #     that format
+  # Reading is format-agnostic: any fresh sibling dump counts, whatever
+  # its format — an existing schema.graphql is reused rather than
+  # re-introspecting to write schema.json.
+  # GraphQL has no standard schema-version signal to invalidate on — a
+  # stale cache surfaces as server-side validation errors (see
+  # QueryError#schema_stale?), so pick a ttl that matches how fast the
+  # API moves, or delete the file.
   #
   # To cache anywhere else (Rails.cache, redis, ...), serialize the schema
   # itself — schemas round-trip through their introspection JSON:
   #
-  #   json = Rails.cache.fetch("gh_schema", expires_in: 12.hours) do
-  #     GraphWeaver::SchemaLoader.introspect(executor).to_json
-  #   end
-  #   schema = GraphWeaver::SchemaLoader.load(json)
-  def self.introspect(executor, cache: nil, ttl: nil)
-    if cache && fresh?(cache, ttl)
-      return GraphQL::Schema.from_introspection(JSON.parse(File.read(cache)))
+  #      json = Rails.cache.fetch("gh_schema", expires_in: 12.hours) do
+  #        GraphWeaver::SchemaLoader.introspect(transport).to_json
+  #      end
+  #      schema = GraphWeaver::SchemaLoader.load(json)
+  def self.introspect(transport, cache: nil, ttl: nil)
+    cache = cache_path(cache)
+
+    if cache
+      # reuse whatever fresh dump is present, regardless of format —
+      # don't re-introspect to write schema.json when a usable
+      # schema.graphql already sits there
+      existing = cache_candidates(cache).find { |candidate| fresh?(candidate, ttl) }
+      if existing
+        GraphWeaver.log(:info) { "schema cache hit: #{existing}#{" (ttl #{ttl}s)" if ttl}" }
+        return load(existing)
+      end
+
+      GraphWeaver.log(:info) { "schema cache miss: #{cache}" }
     end
 
-    result = executor.execute(GraphQL::Introspection.query, variables: {}).to_h
+    result = GraphWeaver.log_timed(:info, "introspected #{transport.respond_to?(:url) ? transport.url : transport.class}") do
+      transport.execute(GraphQL::Introspection.query, variables: {}).to_h
+    end
     if (errors = result["errors"])
       raise GraphWeaver::Error, "introspection failed: #{errors.inspect}"
     end
 
+    schema = GraphQL::Schema.from_introspection(result)
+
     if cache
       FileUtils.mkdir_p(File.dirname(cache))
-      File.write(cache, JSON.generate(result))
+      # the extension picks the format: .json is the verbatim wire
+      # artifact; .graphql/.gql is SDL — human-readable, PR-reviewable
+      # diffs (both generate byte-identical code)
+      meta = stamp(transport)
+      content = if cache.end_with?(".json")
+        JSON.generate(meta ? result.merge("graph_weaver" => meta) : result)
+      else
+        header = meta && "# graph_weaver: #{JSON.generate(meta)}\n\n"
+        "#{header}#{schema.to_definition}"
+      end
+      File.write(cache, content)
+      GraphWeaver.log(:info) { "wrote schema cache: #{cache} (#{content.bytesize} bytes)" }
     end
 
-    GraphQL::Schema.from_introspection(result)
+    schema
+  end
+
+  # The conventional schema dump, whatever its format: schema_path or the
+  # first sibling extension that exists. nil when none is on disk.
+  def self.locate_path(path = GraphWeaver.schema_path)
+    cache_candidates(path).find { |candidate| File.exist?(candidate) }
+  end
+
+  # locate_path, loaded.
+  def self.locate(path = GraphWeaver.schema_path)
+    found = locate_path(path)
+    found && load(found)
+  end
+
+  # The provenance recorded in a dump ({"url" => ..., "introspected_at"
+  # => ...}), whichever format holds it; nil for local/unannotated dumps.
+  def self.provenance(path)
+    content = File.read(path)
+    if path.end_with?(".json")
+      JSON.parse(content)["graph_weaver"]
+    elsif (meta = content[/\A# graph_weaver: (\{.*\})$/, 1])
+      JSON.parse(meta)
+    end
+  end
+
+  # Re-introspect a dump's source and compare — true when the server has
+  # drifted from what's on disk. transport: overrides the transport (auth
+  # etc); by default one is built from the dump's recorded url. Wired up
+  # as `rake graph_weaver:schema:verify` / `:refresh`.
+  def self.stale?(path, transport: nil)
+    transport ||= source_transport(path)
+    fresh = introspect(transport)
+
+    fresh.to_definition != load(path).to_definition
+  end
+
+  # a transport to the dump's recorded url (GRAPHWEAVER_AUTH supplies a
+  # token when set)
+  def self.source_transport(path)
+    meta = provenance(path)
+    unless meta&.key?("url")
+      raise GraphWeaver::Error, "#{path} records no source url — pass transport:"
+    end
+
+    GraphWeaver.new(meta["url"], auth: ENV["GRAPHWEAVER_AUTH"]).transport
+  end
+  private_class_method :source_transport
+
+  # Where a dump came from, recorded into the file so it can be
+  # re-verified later — a parsable header comment in SDL, a
+  # "graph_weaver" sibling key in introspection JSON (from_introspection
+  # reads only "data"). nil when the transport has no url (schema
+  # classes, fakes).
+  def self.stamp(transport)
+    return unless transport.respond_to?(:url) && transport.url
+
+    require "time"
+    { "url" => transport.url, "introspected_at" => Time.now.utc.iso8601 }
+  end
+  private_class_method :stamp
+
+  CACHE_EXTENSIONS = %w[.json .graphql .gql].freeze
+
+  # cache: true / :json / :graphql / :gql / a path => the file to write
+  # (nil for no caching). Symbols and true anchor at GraphWeaver.schema_path —
+  # the schema dump the generation workflow reads, so one file serves both
+  # (introspect caches it, rake generate loads it).
+  def self.cache_path(cache)
+    case cache
+    when nil, false
+      nil
+    when true
+      GraphWeaver.schema_path
+    when Symbol
+      unless CACHE_EXTENSIONS.include?(".#{cache}")
+        raise ArgumentError, "cache: format must be :json, :graphql, or :gql, got #{cache.inspect}"
+      end
+
+      "#{strip_extension(GraphWeaver.schema_path)}.#{cache}"
+    else
+      unless cache.end_with?(*CACHE_EXTENSIONS)
+        raise ArgumentError, "cache: must be a .json or .graphql/.gql path, got #{cache}"
+      end
+
+      cache
+    end
+  end
+  private_class_method :cache_path
+
+  # the requested path first, then its siblings in the other formats
+  def self.cache_candidates(path)
+    base = strip_extension(path)
+    [path, *CACHE_EXTENSIONS.map { |ext| base + ext }].uniq
+  end
+  private_class_method :cache_candidates
+
+  def self.strip_extension(path)
+    path.delete_suffix(File.extname(path))
   end
+  private_class_method :strip_extension
 
   def self.fresh?(path, ttl)
     File.exist?(path) && (ttl.nil? || Time.now - File.mtime(path) < ttl)