graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/schema_loader.rb

@@ -1,6 +1,7 @@
 # typed: true
 # frozen_string_literal: true
 
+require "digest"
 require "fileutils"
 require "graphql"
 require "json"
@@ -127,10 +128,30 @@ module GraphWeaver::SchemaLoader
   private_class_method :build_sdl
 
   def self.build_introspection(result)
-    build(:introspection) { GraphQL::Schema.from_introspection(result) }
+    build(:introspection) { GraphQL::Schema.from_introspection(result) }.tap do |schema|
+      restore_one_of!(schema, result)
+    end
   end
   private_class_method :build_introspection
 
+  # graphql-ruby's loader drops isOneOf, so an input object that arrived
+  # @oneOf comes back as an ordinary one — and ONE_OF, the only thing that
+  # enforces it, is never emitted. SDL dumps keep the directive themselves;
+  # this is the introspection path catching up. Applied after the load, which
+  # is when the arguments one_of validates against exist.
+  def self.restore_one_of!(schema, result)
+    types = result.dig("data", "__schema", "types")
+    return unless types
+
+    types.each do |type|
+      next unless type["isOneOf"]
+
+      loaded = schema.get_type(type["name"])
+      loaded.one_of if loaded.respond_to?(:one_of)
+    end
+  end
+  private_class_method :restore_one_of!
+
   # Which artifact an SDL string is — it decides both the normalizing it
   # needs and what to say when it won't build.
   def self.sdl_kind(sdl)
@@ -223,7 +244,6 @@ module GraphWeaver::SchemaLoader
     "@authenticated" => "directive @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM",
     "@requiresScopes" => "directive @requiresScopes(scopes: [[federation__Scope!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM",
     "@policy" => "directive @policy(policies: [[federation__Policy!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM",
-    "@link" => "directive @link(url: String!, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA",
   }.freeze
 
   # The types those definitions reference — injected only alongside a
@@ -234,45 +254,93 @@ module GraphWeaver::SchemaLoader
     "federation__FieldSet" => "scalar federation__FieldSet",
     "federation__Scope" => "scalar federation__Scope",
     "federation__Policy" => "scalar federation__Policy",
-    "link__Import" => "scalar link__Import",
-    "link__Purpose" => "enum link__Purpose { SECURITY EXECUTION }",
   }.freeze
   private_constant :SUBGRAPH_DIRECTIVE_DEFS, :SUBGRAPH_HELPER_TYPES
 
-  # A fed-2 subgraph that @links the spec under a namespace — `as: "fed"`,
-  # and "federation" is the default — applies every non-imported directive
-  # under it: @federation__key rather than @key.
-  def self.subgraph_namespace(sdl)
-    sdl[/#{SUBGRAPH_LINK}[^)]*\bas:\s*"([^"]+)"/, 1] || "federation"
+  # A fed-2 subgraph's federation @link, as a plain argument hash. One header
+  # settles both spellings a directive can arrive under: `as:` namespaces the
+  # whole spec (@fed__key), each `import:` entry binds one directive in the
+  # root namespace, possibly renamed. Read rather than matched — an
+  # `import: [{name: "@key", as: "@primaryKey"}]` entry has an `as:` of its
+  # own, which a regex over the header can't tell from the spec's.
+  def self.federation_link(doc)
+    link_declarations(doc).find { |args| spec_name(args["url"] || args["feature"]) == "federation" }
   end
-  private_class_method :subgraph_namespace
+  private_class_method :federation_link
+
+  # What this subgraph calls each federation directive: the local name it
+  # imported it under, else the namespace's (@federation__key), else the bare
+  # spec name, which is fed-1 and a fed-2 plain `import: ["@key"]` alike.
+  # Ordered — the first spelling the file actually applies wins.
+  def self.subgraph_spellings(doc)
+    link = federation_link(doc)
+    namespace = (link && link["as"].is_a?(String)) ? link["as"] : "federation"
+    aliases = imports(link && link["import"]).to_h
+
+    SUBGRAPH_DIRECTIVE_DEFS.keys.to_h do |name|
+      [name, [aliases[name], name, "@#{namespace}__#{name.delete_prefix("@")}"].compact.uniq]
+    end
+  end
+  private_class_method :subgraph_spellings
 
   # Prepend the definitions this subgraph applies but doesn't declare, under
   # whichever name it applies them by. Only the missing ones — a duplicate
   # definition is a hard error in graphql-ruby, and a subgraph spelling out
   # its own @key (fed-1 style, or a differing shape) must win.
   def self.add_subgraph_definitions(sdl)
-    defined = GraphQL.parse(sdl).definitions.filter_map do |defn|
+    doc = GraphQL.parse(sdl)
+    defined = doc.definitions.filter_map do |defn|
       next unless defn.respond_to?(:name)
 
       defn.is_a?(GraphQL::Language::Nodes::DirectiveDefinition) ? "@#{defn.name}" : defn.name
     end.to_set
-    namespace = subgraph_namespace(sdl)
+    spellings = subgraph_spellings(doc)
 
     directives = SUBGRAPH_DIRECTIVE_DEFS.filter_map do |name, defn|
-      applied = [name, "@#{namespace}__#{name.delete_prefix("@")}"]
-        .find { |as| !defined.include?(as) && sdl.match?(/#{as}\b/) }
+      applied = spellings.fetch(name).find { |as| !defined.include?(as) && sdl.match?(/#{as}\b/) }
       applied && defn.sub(name, applied)
     end
     types = SUBGRAPH_HELPER_TYPES
       .select { |name, _| !defined.include?(name) && directives.any? { |defn| defn.include?(name) } }
       .values
 
-    added = types + directives + entity_plumbing(sdl, namespace, defined)
-    added.empty? ? sdl : "#{added.join("\n")}\n\n#{sdl}"
+    added = types + directives + entity_plumbing(doc, defined, spellings.fetch("@key"))
+    body = strip_link_header(sdl, doc)
+    added.empty? ? body : "#{added.join("\n")}\n\n#{body}"
   end
   private_class_method :add_subgraph_definitions
 
+  # The composition header says which spec a file's directives come from and
+  # under what names. That's metadata about the FILE, not part of the graph it
+  # describes — it is read (see subgraph_spellings) and then dropped, as the
+  # supergraph path drops its own. Dropping it is also what makes the spec's
+  # own aliasing loadable: `import:` is a `scalar link__Import`, and
+  # graphql-ruby's schema builder walks an object entry
+  # (`{name: "@key", as: "@primaryKey"}`) into a type that has no arguments.
+  #
+  # The original text is returned untouched when there's no header, so a
+  # fed-1 subgraph and a plain schema are never reprinted.
+  def self.strip_link_header(sdl, doc)
+    headers = doc.definitions.select do |defn|
+      (defn.is_a?(GraphQL::Language::Nodes::SchemaDefinition) ||
+        defn.is_a?(GraphQL::Language::Nodes::SchemaExtension)) &&
+        defn.directives.any? { |d| LINK_DIRECTIVES.include?(d.name) }
+    end
+    return sdl if headers.empty?
+
+    definitions = doc.definitions.filter_map do |defn|
+      next defn unless headers.include?(defn)
+
+      kept = defn.directives.reject { |d| LINK_DIRECTIVES.include?(d.name) }
+      # `extend schema` with nothing left in it isn't a definition any more
+      next if kept.empty? && [defn.query, defn.mutation, defn.subscription].all?(&:nil?)
+
+      defn.merge(directives: kept)
+    end
+    GraphQL::Language::Nodes::Document.new(definitions:).to_query_string
+  end
+  private_class_method :strip_link_header
+
   # The entity resolver every subgraph serves — and which no subgraph SDL
   # contains: `_service { sdl }` and `rover subgraph fetch` both print the
   # published schema, where the plumbing is implicit. Supply it so an
@@ -280,10 +348,9 @@ module GraphWeaver::SchemaLoader
   # (a supergraph doesn't describe `_entities` at all). `_Entity` is the
   # union of the file's own @key'd types, so it stays accurate per subgraph.
   # https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-spec
-  def self.entity_plumbing(sdl, namespace, defined)
-    doc = GraphQL.parse(sdl)
+  def self.entity_plumbing(doc, defined, key_spellings)
     root = query_root_name(doc)
-    entities = entity_names(doc, namespace)
+    entities = entity_names(doc, key_spellings)
     return [] if entities.empty? || root.nil? || defined.include?("_Any")
 
     [
@@ -300,10 +367,11 @@ module GraphWeaver::SchemaLoader
 
   # The object types this subgraph resolves as entities: the ones it applies
   # @key to, under whichever name it applies it by (@federation__key when the
-  # spec is linked under a namespace). Type extensions count — fed-1 spells an
-  # entity it doesn't own as `extend type User @key(...)`.
-  def self.entity_names(doc, namespace)
-    key_names = ["key", "#{namespace}__key"]
+  # spec is linked under a namespace, @primaryKey when it was imported under
+  # that name). Type extensions count — fed-1 spells an entity it doesn't own
+  # as `extend type User @key(...)`.
+  def self.entity_names(doc, key_spellings)
+    key_names = key_spellings.map { |name| name.delete_prefix("@") }
 
     doc.definitions.filter_map do |defn|
       next unless defn.is_a?(GraphQL::Language::Nodes::ObjectTypeDefinition) ||
@@ -615,7 +683,7 @@ module GraphWeaver::SchemaLoader
   #      end
   #      schema = GraphWeaver::SchemaLoader.load(json)
   def self.introspect(transport, cache: nil, ttl: nil, auth_env: nil)
-    cache = cache_path(cache)
+    cache = cache_path(cache, (transport.url if transport.respond_to?(:url)))
 
     if cache
       # reuse whatever fresh dump is present, regardless of format —
@@ -631,7 +699,7 @@ module GraphWeaver::SchemaLoader
     end
 
     result = GraphWeaver::Internal::Log.log_timed(:info, "introspected #{endpoint(transport)}") do
-      transport.execute(GraphQL::Introspection.query, variables: {}).to_h
+      ask(transport)
     end
     if (errors = result["errors"])
       raise GraphWeaver::Error, "introspection failed: #{errors.inspect}"
@@ -646,7 +714,10 @@ module GraphWeaver::SchemaLoader
         "endpoint? got: #{result.inspect[0, 200]}"
     end
 
-    schema = GraphQL::Schema.from_introspection(result)
+    # the same door a dump read back off disk comes in by, so a schema
+    # introspected now and one loaded from the file this writes are the same
+    # schema — @oneOf included
+    schema = build_introspection(result)
 
     if cache
       # the extension picks the format: .json is the verbatim wire
@@ -659,6 +730,10 @@ module GraphWeaver::SchemaLoader
         header = meta && "# graph_weaver: #{JSON.generate(meta)}\n\n"
         "#{header}#{schema.to_definition}"
       end
+      # the one place a dump is overwritten, so the one place that can stop a
+      # supergraph being traded for the API schema behind it
+      raise GraphWeaver::Error, recompose_hint(cache) if composed_dump?(cache) && !federation_sdl?(content)
+
       begin
         FileUtils.mkdir_p(File.dirname(cache))
         GraphWeaver::Internal::Util.atomic_write(cache, content)
@@ -675,12 +750,44 @@ module GraphWeaver::SchemaLoader
     schema
   end
 
+  # The introspection result, asking for the newer fields and falling back
+  # without them.
+  #
+  # isOneOf is the only thing that says an input object is @oneOf, and
+  # specifiedByURL the only thing that says what a scalar's format is;
+  # graphql-ruby leaves both out unless asked — but they are newer than
+  # plenty of servers, and one that doesn't define them REFUSES the query
+  # outright (Hasura: "field 'isOneOf' not found in type: '__Type'"). So ask,
+  # and ask the baseline query rather than give up. The second request costs
+  # one round trip on exactly the servers whose answer was going to be an
+  # error anyway.
+  def self.ask(transport)
+    query = GraphQL::Introspection.query(include_is_one_of: true, include_specified_by_url: true)
+    result = transport.execute(query, variables: {}).to_h
+    return result if result["errors"].nil? && result.dig("data", "__schema")
+
+    transport.execute(GraphQL::Introspection.query, variables: {}).to_h
+  end
+  private_class_method :ask
+
   # What to call the thing we introspected, for a log line or an error: its
-  # url when it has one, else the class (a schema class, a fake).
+  # url when it has one, else the class (a schema class, a fake). A
+  # graphql-ruby schema class fills the same slot a transport does, and its
+  # own name is what a report has to say — `.class` answers "Class".
   def self.endpoint(transport)
-    (transport.respond_to?(:url) && transport.url) || transport.class
+    return GraphWeaver::Internal::Endpoint.safe(transport.url) if transport.respond_to?(:url) && transport.url
+
+    transport.is_a?(Module) ? (transport.name || transport.to_s) : transport.class
+  end
+
+  # Whether `source` names a dump file rather than being SDL or introspection
+  # content — by extension, which is how load_path reads one anyway. The only
+  # form of the question askable before the file exists, which is what
+  # `schema:refresh` needs to write the first one.
+  def self.dump_path?(source)
+    source = source.to_path if source.respond_to?(:to_path)
+    CACHE_EXTENSIONS.include?(File.extname(source.to_s))
   end
-  private_class_method :endpoint
 
   # The conventional schema dump, whatever its format: schema_path or the
   # first sibling extension that exists. nil when none is on disk.
@@ -726,9 +833,11 @@ module GraphWeaver::SchemaLoader
   private_class_method :auth_env
 
   # Re-introspect a dump's source and compare — a {SchemaDiff} naming what
-  # moved, empty when the server still matches 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:diff`.
+  # moved, empty when the source still matches what's on disk. transport:
+  # overrides what to ask (auth etc); by default one is built from the
+  # dump's recorded url. A graphql-ruby schema class fills that slot too,
+  # which is how an app that serves its own schema diffs the dump against
+  # the code behind it. Wired up as `rake graph_weaver:schema:diff`.
   def self.diff(path, transport: nil)
     transport ||= source_transport(path)
     fresh = introspect(transport)
@@ -736,34 +845,77 @@ module GraphWeaver::SchemaLoader
     GraphWeaver::SchemaDiff.new(load(path), fresh, source: path, target: endpoint(transport).to_s)
   end
 
-  # Re-introspect and rewrite the local dump, returning [path, url].
+  # Rewrite the local dump from the source behind it, returning
+  # [path, source]. The dump is the contract generation reads; this rewrites
+  # it from whatever the schema actually is — re-introspecting a url, or
+  # rebuilding from schema:, a graphql-ruby class this process runs (the
+  # same duck-typed slot a transport fills, so introspection asks it
+  # directly and nothing touches the network).
+  #
   # url: defaults to the one the dump recorded, so a refresh needs no
   # arguments once a dump exists — and passing one bootstraps the first
   # dump, which is what `rails g graph_weaver:install` does.
+  # path: the dump to rewrite, defaulting to the conventional one — a graph
+  # that names its own dump passes it.
   # auth_env: the ENV var holding the token — defaults to whichever the
   # dump recorded, so `--auth MY_TOKEN` keeps working on every later
   # refresh without being repeated. auth: passes a token directly.
-  def self.refresh!(url: nil, auth_env: nil, auth: nil)
-    path = locate_path
+  def self.refresh!(url: nil, auth_env: nil, auth: nil, schema: nil, path: nil)
+    path ||= locate_path
+
+    # ttl: 0 throughout — an existing dump never counts as fresh, a refresh
+    # always rebuilds. The extension picks the format, so a repo that keeps
+    # SDL keeps SDL.
+    if schema
+      introspect(schema, cache: path || GraphWeaver.schema_path, ttl: 0)
+      return [path || GraphWeaver.schema_path, endpoint(schema)]
+    end
+
     url ||= path && provenance(path)&.dig("url")
     raise GraphWeaver::Error, refresh_hint(path) unless url
 
     path ||= GraphWeaver.schema_path
     auth_env ||= self.auth_env(path)
     auth ||= ENV[auth_env]
-    # ttl: 0 — an existing dump never counts as fresh, a refresh always refetches
     introspect(GraphWeaver.new(url, auth:).transport, cache: path, ttl: 0, auth_env:)
     [path, url]
   end
 
   def self.refresh_hint(path)
+    # a supergraph records no url because none could serve it — saying
+    # "pass one" sends a federated app to the overwrite composed_dump? stops
+    return recompose_hint(path) if composed_dump?(path)
+
     missing = path ? "#{path} records no source url" : "no schema dump at #{GraphWeaver.schema_path}"
     "#{missing} — pass one: rake graph_weaver:schema:refresh URL=https://api.example.com/graphql " \
-      "(a dump taken from a schema class is rebuilt from code, not re-fetched — see " \
-      "docs/getting_started.md#your-apps-own-schema-in-process)"
+      "(if this app serves the schema itself, point GraphWeaver.client at the class and the dump is " \
+      "rebuilt from it — see docs/getting_started.md#your-apps-own-schema-in-process)"
   end
   private_class_method :refresh_hint
 
+  # A dump that carries the @join__* routing table: what `rover supergraph
+  # compose` emits, and the only artifact that says which subgraph resolves
+  # what. Asked of the bytes on disk, which is the only form of the question
+  # available before something overwrites them.
+  def self.composed_dump?(path)
+    return false unless path
+
+    resolved = GraphWeaver::Internal::Util.resolve(path)
+    File.exist?(resolved) && federation_sdl?(File.read(resolved))
+  end
+  private_class_method :composed_dump?
+
+  # Composition is the only thing that rebuilds a supergraph: introspection
+  # answers with the API schema, which is the merged shape minus the routing
+  # table, so refreshing one from a url replaces the contract with a strictly
+  # smaller artifact and reports success.
+  def self.recompose_hint(path)
+    "#{GraphWeaver::Internal::Util.relative(path)} is a composed supergraph; introspection returns " \
+      "the API schema, not the @join__* routing table — recompose it (rover supergraph compose) " \
+      "and check the result in, instead of refreshing it"
+  end
+  private_class_method :recompose_hint
+
   # A transport to the dump's recorded url, authenticated from whichever ENV
   # var the dump named (else DEFAULT_AUTH_ENV). The single way to reach a
   # dump's own server — building one at a call site is how `--auth MY_TOKEN`
@@ -783,12 +935,13 @@ module GraphWeaver::SchemaLoader
   # 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).
+  # classes, fakes). The url is recorded bare: a dump is committed, and
+  # re-introspection authenticates from auth_env, not from the url.
   def self.stamp(transport, auth_env = nil)
     return unless transport.respond_to?(:url) && transport.url
 
     require "time"
-    meta = { "url" => transport.url, "introspected_at" => Time.now.utc.iso8601 }
+    meta = { "url" => GraphWeaver::Internal::Endpoint.bare(transport.url), "introspected_at" => Time.now.utc.iso8601 }
     # only the non-default var is worth recording — auth_env falls back to
     # DEFAULT_AUTH_ENV, so an unannotated dump reads the same either way
     meta["auth_env"] = auth_env if auth_env && auth_env != DEFAULT_AUTH_ENV
@@ -800,23 +953,24 @@ module GraphWeaver::SchemaLoader
   private_constant :CACHE_EXTENSIONS
 
   # 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)
+  # (nil for no caching). A path is taken as given. 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) —
+  # unless that dump belongs to a different endpoint; see {conventional_dump}.
+  def self.cache_path(cache, url = nil)
     # Rails.root.join(...) hands you a Pathname, as schema: and query: already take
     cache = cache.to_path if cache.respond_to?(:to_path)
     path = case cache
     when nil, false
       nil
     when true
-      GraphWeaver.schema_path
+      conventional_dump(File.extname(GraphWeaver.schema_path), url)
     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}"
+      conventional_dump(".#{cache}", url)
     else
       unless cache.end_with?(*CACHE_EXTENSIONS)
         raise ArgumentError, "cache: must be a .json or .graphql/.gql path, got #{cache}"
@@ -828,6 +982,38 @@ module GraphWeaver::SchemaLoader
   end
   private_class_method :cache_path
 
+  # Where an unnamed `cache:` lands. One rule: **the conventional dump, unless
+  # the dump there came from a different endpoint** — then a file of this
+  # client's own, named by a digest of its url and sitting beside it. A dump
+  # records the url it was introspected from, so this is answerable; without
+  # it, two clients at two origins both saying `cache: true` read and
+  # overwrote one file, and each was silently served the other's schema.
+  #
+  # A dump that records no url is nobody's in particular — hand-written, or
+  # committed by an older version — so it stays a hit for whoever asks.
+  def self.conventional_dump(extension, url)
+    base = strip_extension(GraphWeaver.schema_path)
+    conventional = base + extension
+    url = url && GraphWeaver::Internal::Endpoint.bare(url) # what a dump records
+    return conventional if url.nil? || !someone_elses?(conventional, url)
+
+    "#{base}-#{Digest::SHA256.hexdigest(url)[0, 8]}#{extension}"
+  end
+  private_class_method :conventional_dump
+
+  # Whether a dump already at `path` (or a sibling format) says it came from
+  # somewhere other than `url`. Nothing there yet is nobody's, so a cold
+  # client still writes the conventional dump — which is what the documented
+  # bootstrap does, and what an app with one client wants.
+  def self.someone_elses?(path, url)
+    existing = cache_candidates(path).find { |candidate| File.exist?(candidate) }
+    return false unless existing
+
+    recorded = provenance(existing)&.dig("url")
+    !recorded.nil? && recorded != url
+  end
+  private_class_method :someone_elses?
+
   # the requested path first, then its siblings in the other formats
   def self.cache_candidates(path)
     path = GraphWeaver::Internal::Util.resolve(path)
@@ -868,6 +1054,15 @@ module GraphWeaver::SchemaLoader
     RoutingTable.new(sdl)
   end
 
+  # Whether this source carries a routing table — the question
+  # {routing_table} answers by refusing when it doesn't. A predicate rather
+  # than a rescue, because every GraphWeaver::Error writes a warn line as it
+  # is *constructed*: asking by exception made every non-federated app log
+  # "no routing table here" once per process, about a table it never wanted.
+  def self.routing_table?(source)
+    !source.is_a?(Hash) && federation_sdl?(supergraph_sdl(source))
+  end
+
   def self.supergraph_sdl(source)
     if source.is_a?(Hash)
       raise GraphWeaver::Error,
@@ -894,7 +1089,11 @@ module GraphWeaver::SchemaLoader
     # the migration marker verbatim. `contextual` names the arguments a
     # @fromContext fills from an ancestor selection (federation 2.8) — a fetch
     # has to supply them, so whoever plans one needs to know they exist.
-    Field = Struct.new(:graphs, :external, :requires, :provides, :override, :contextual)
+    # `override_label` is federation 2.7's progressive @override(label:): both
+    # subgraphs stay resolvable and the label is the rollout rule that decides
+    # between them, so a router that can't evaluate it has to know it's there.
+    Field = Struct.new(:graphs, :external, :requires, :provides, :override, :contextual,
+      :override_label)
 
     # Every @join__ directive this table understands. One it doesn't is a
     # federation construct nobody has taught it to read, and it lands in
@@ -928,6 +1127,7 @@ module GraphWeaver::SchemaLoader
       @keys = {}         # "User" => { "accounts" => [["id"]] }
       @fields = {}       # "User" => { "reviews" => Field }
       @field_names = {}  # "User" => Set["id", "username"]
+      @signatures = {}   # "User" => { "reviews" => "[Review!]!" }
       @abstract = {}     # "FeedItem" => ["Announcement", "Review"]
       @possible = {}     # "FeedItem" => { "reviews" => ["Announcement", "Review"] }
       @unsupported = []
@@ -939,17 +1139,20 @@ module GraphWeaver::SchemaLoader
       @subgraphs = @names.values.freeze
     end
 
-    # Which subgraphs can resolve Type.field, by name. A field with no
-    # @join__field at all lives wherever its type does — the composer omits
-    # the directive when it has nothing to say, and that omission is the
-    # supergraph spec's way of saying "everywhere".
+    # Which subgraphs can resolve Type.field, by name: exactly the ones its
+    # @join__field names. A field with no @join__field at all lives wherever
+    # its type does — the composer omits the directive when it has nothing to
+    # say, and that omission is the supergraph spec's way of saying
+    # "everywhere".
+    #
+    # One directive naming no subgraph therefore routes to none. Apollo
+    # writes that on an @external/@usedOverridden copy — a reference, not a
+    # resolver — and bare, with no arguments at all, on a concrete
+    # implementer's copy of a field really contributed through
+    # @interfaceObject elsewhere.
     def owners(type_name, field_name)
       field = self.field(type_name, field_name)
-      return declared_in(type_name) if field.nil?
-      return field.graphs if field.graphs.any?
-
-      # declared only as @external/@usedOverridden: a reference, not a resolver
-      field.external.any? ? [] : declared_in(type_name)
+      field.nil? ? declared_in(type_name) : field.graphs
     end
 
     # The routing for Type.field, or nil when the supergraph says nothing
@@ -973,6 +1176,11 @@ module GraphWeaver::SchemaLoader
     # there.
     def declared_fields(type_name) = @field_names[type_name]&.to_a || []
 
+    # The type the supergraph gives Type.field, printed the way SDL prints it
+    # ("String!", "[Review!]!") — so it compares directly against a loaded
+    # schema's `to_type_signature`. nil for a coordinate it doesn't carry.
+    def signature(type_name, field_name) = @signatures.dig(type_name, field_name)
+
     # Whether the supergraph carries this coordinate at all — a type, or a
     # field on it. `owners`/`fields` answer who resolves what the supergraph
     # has; this answers whether it has it, which is the question a local
@@ -1151,6 +1359,7 @@ module GraphWeaver::SchemaLoader
       return unless defn.respond_to?(:fields) && defn.fields
 
       @field_names[defn.name] = defn.fields.map(&:name).to_set
+      @signatures[defn.name] = defn.fields.to_h { |field| [field.name, field.type.to_query_string] }
       @fields[defn.name] = defn.fields.filter_map do |field|
         note_unknown(field, "#{defn.name}.#{field.name}")
         applied = field.directives.select { |d| d.name == "join__field" }
@@ -1167,6 +1376,7 @@ module GraphWeaver::SchemaLoader
           resolvable.filter_map { |d| argument(d, "provides") }.first,
           applied.filter_map { |d| argument(d, "override") }.first,
           applied.flat_map { |d| context_arguments(d) },
+          applied.filter_map { |d| argument(d, "overrideLabel") }.first,
         )]
       end.to_h
     end