extend semantic introspection with __coordinates

rfcs/semantic-introspection.md

@@ -90,7 +90,7 @@ across all conforming implementations.
 
 ### 1. Semantic Search Introspection
 
-A new introspection field that enables semantic search over schema members:
+A new introspection field that enables semantic search over schema definitions:
 
 ```graphql
 extend type Query {
@@ -130,27 +130,27 @@ extend type Query {
 
 ```graphql
 """
-Represents a schema member matched by semantic search.
+Represents a schema definition matched by semantic search.
 """
 type __SearchResult {
   """
-  Schema coordinate identifying the matched member.
+  Schema coordinate identifying the matched definition.
   For example: "Query.user" or "Mutation.createPost(input: )"
   """
   coordinate: String!
 
   """
-  The matched schema member.
+  The matched schema definition.
   """
-  member: __SchemaMember!
+  definition: __SchemaDefinition!
 
   """
-  Paths from the matched member to a root type, aiding query construction.
+  Paths from the matched definition to a root type, aiding query construction.
 
-  Each path is a sequence of schema coordinates, starting from the matched member and ending at a
+  Each path is a sequence of schema coordinates, starting from the matched definition and ending at a
   root type.
 
-  Implementations MAY return multiple paths if the member is reachable via different routes. This
+  Implementations MAY return multiple paths if the definition is reachable via different routes. This
   list is not guaranteed to be exhaustive.
   """
   pathsToRoot: [String!]!
@@ -164,26 +164,155 @@ type __SearchResult {
 }
 ```
 
-> **Editor's Note:** The `pathsToRoot` field is placed on `__SearchResult`, but
-> it arguably belongs on the schema member types themselves (e.g., `__Field`,
-> `__Type`). This placement warrants further discussion.
+> **Editor's Note:** The `pathsToRoot` field is placed on `__SearchResult`, but it
+> arguably belongs on the schema definition types themselves (e.g., `__Field`, `__Type`).
+> This placement warrants further discussion.
 
-#### Schema Member Union
+#### Schema Definition Union
 
 ```graphql
 """
-Union of all introspectable schema members that can be discovered
+Union of all introspectable schema definitions that can be discovered
 through semantic search.
 """
-union __SchemaMember =
+union __SchemaDefinition =
   | __Type
   | __Field
   | __InputValue
   | __EnumValue
   | __Directive
 ```
 
-### 2. Indexing Requirements
+### 2. Coordinate Lookup Introspection
+
+Schema coordinates (e.g. `Query.user`, `User.email`, `@deprecated(reason:)`) are the natural way to
+reference specific definitions of a GraphQL schema. Today, resolving a coordinate to its full definition
+requires traversing the introspection graph via `__schema`, `__type`, and so forth.
+
+The `__definitions` field provides direct lookup by schema coordinate, eliminating this traversal.
+While it naturally complements `__search` for agentic workflows, coordinate lookup is independently
+useful for any tool or client that works with schema coordinates.
+
+```graphql
+extend type Query {
+  """
+  Resolves schema definitions by their schema coordinates.
+
+  Returns the resolved definitions in the same order as the input coordinates.
+  """
+  __definitions(
+    """
+    List of schema coordinates to resolve.
+    """
+    coordinates: [String!]!
+  ): [__SchemaDefinition!]!
+}
+```
+
+#### Example Usage
+
+An agent resolving coordinates discovered via `__search`, or a developer tool
+inspecting specific schema definitions:
+
+```graphql
+query {
+  __definitions(coordinates: ["Query.userByEmail", "User"]) {
+    ... on __Type {
+      name
+      kind
+      fields {
+        name
+        type {
+          name
+          kind
+          ofType {
+            name
+          }
+        }
+      }
+    }
+    ... on __Field {
+      name
+      description
+      type {
+        name
+        kind
+        ofType {
+          name
+        }
+      }
+      args {
+        name
+        type {
+          name
+          kind
+        }
+        defaultValue
+      }
+    }
+  }
+}
+```
+
+Example response:
+
+```json
+{
+  "data": {
+    "__definitions": [
+      {
+        "name": "userByEmail",
+        "description": "Retrieve a user by their email address",
+        "type": {
+          "name": null,
+          "kind": "NON_NULL",
+          "ofType": { "name": "User" }
+        },
+        "args": [
+          {
+            "name": "email",
+            "type": { "name": "String", "kind": "SCALAR" },
+            "defaultValue": null
+          }
+        ]
+      },
+      {
+        "name": "User",
+        "kind": "OBJECT",
+        "fields": [
+          {
+            "name": "id",
+            "type": {
+              "name": null,
+              "kind": "NON_NULL",
+              "ofType": { "name": "ID" }
+            }
+          },
+          {
+            "name": "email",
+            "type": {
+              "name": null,
+              "kind": "NON_NULL",
+              "ofType": { "name": "String" }
+            }
+          },
+          {
+            "name": "displayName",
+            "type": { "name": "String", "kind": "SCALAR", "ofType": null }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+> **Editor's Note:** While `__definitions` naturally pairs with `__search` in a two-step
+> discover-then-resolve workflow for AI agents, it stands on its own as a general-purpose
+> introspection primitive. Any tool that works with schema coordinates benefits from direct
+> resolution without full introspection traversal.
+
+### 3. Indexing Requirements
 
 Implementations adhering to this specification:
 
@@ -193,15 +322,15 @@ Implementations adhering to this specification:
 
 The indexing strategy is intentionally left to the implementation.
 
-### 3. Example Usage
+### 4. Example Usage
 
 ```graphql
 # An LLM trying to find how to look up a user by email
 query {
   __search(query: "Find a user by their email address") {
     coordinate
     score
-    member {
+    definition {
       ... on __Field {
         name
         description
@@ -226,7 +355,7 @@ Example response:
       {
         "coordinate": "Query.userByEmail",
         "score": 0.92,
-        "member": {
+        "definition": {
           "name": "userByEmail",
           "description": "Retrieve a user by their email address",
           "args": [{ "name": "email", "type": { "name": "String" } }]
@@ -235,7 +364,7 @@ Example response:
       {
         "coordinate": "Query.users",
         "score": 0.71,
-        "member": {
+        "definition": {
           "name": "users",
           "description": "List all users, optionally filtered by email domain",
           "args": []
@@ -259,7 +388,7 @@ This could also be helpful for human developers exploring unfamiliar APIs.
 
 ```graphql
 """
-An example demonstrating how to use a schema member.
+An example demonstrating how to use a schema definition.
 """
 type __Example {
   """