feat(api): add saved_query GraphQL field for the curated saved-query library (#7642) (#7652)

Add saved_query(id: String!, params: JSON): JSON to type Query, mirroring
GET /api/v1/queries/{id} and the run_saved_query MCP tool by calling the same
shared executor (src/saved-queries.mjs runSavedQuery) -- template lookup,
param coercion/validation, and execution are all its; nothing re-implemented.
Unknown id and invalid params (its not_found / invalid_params toolErrors) map
to BAD_USER_INPUT, matching the file's invalid-argument convention; any other
executor failure surfaces as a normal GraphQL error. Opaque
{query_id, params, data} JSON passthrough per the registry_summary-family
convention, RELATIONSHIP_FIELD_COMPLEXITY weight, and tests (template run
with a params object literal, unknown id listing valid ids, unknown param,
complexity).

Author: RealDiligent

src/graphql.mjs

@@ -235,6 +235,9 @@ import {
   labelsForSs58,
 } from "./entity-labels.mjs";
 import { loadSudoKey } from "./sudo-key.mjs";
+// #7642: saved_query reuses the same maintainer-curated template executor the
+// GET /api/v1/queries/{id} route and run_saved_query MCP tool already share.
+import { runSavedQuery } from "./saved-queries.mjs";
 import { loadNetworkParameters } from "./network-parameters.mjs";
 import { loadRandomnessStatus } from "./randomness.mjs";
 import { loadAddressMapping, H160_PATTERN } from "./address-mapping.mjs";
@@ -504,6 +507,8 @@ export const SDL = `
     curation: JSON
     "The discovered candidate-surface ledger: every machine-discovered surface awaiting review, with its subnet (netuid), kind, provider, and review state. Filter by netuid/kind/provider/state and page with limit/cursor, exactly like the REST route. Resolves to {items,total,next_cursor} as opaque JSON. Mirrors GET /api/v1/candidates."
     candidates(netuid: Int, kind: String, provider: String, state: String, limit: Int, cursor: String): JSON
+    "Run one maintainer-curated saved-query template by id, with its template-defined params object -- the same parameterized query library REST and the run_saved_query MCP tool execute. Resolves to {query_id, params, data} as opaque JSON. An unknown id or invalid params is a BAD_USER_INPUT error listing the valid template ids, not a silently substituted default. Mirrors GET /api/v1/queries/{id}."
+    saved_query(id: String!, params: JSON): JSON
     "The recorded response fixtures for registered surfaces, used to replay/verify a surface without calling it. Null when no fixture index has been baked in this environment. Opaque JSON passed through verbatim, matching the list_fixtures MCP/REST shape. Mirrors GET /api/v1/fixtures."
     fixtures: JSON
     "The agent-callable service catalog: without a netuid, the global index of subnets exposing callable services; with one, that subnet's full per-service catalog. Both are overlaid with live health exactly as REST composes them. Null when the catalog has not been baked. Opaque JSON, matching the get_agent_catalog MCP/REST shape. Mirrors GET /api/v1/agent-catalog."
@@ -4250,6 +4255,7 @@ export const FIELD_COMPLEXITY = {
   agent_resources: RELATIONSHIP_FIELD_COMPLEXITY,
   curation: RELATIONSHIP_FIELD_COMPLEXITY,
   candidates: RELATIONSHIP_FIELD_COMPLEXITY,
+  saved_query: RELATIONSHIP_FIELD_COMPLEXITY,
   fixtures: RELATIONSHIP_FIELD_COMPLEXITY,
   agent_catalog: RELATIONSHIP_FIELD_COMPLEXITY,
   freshness: RELATIONSHIP_FIELD_COMPLEXITY,
@@ -6210,6 +6216,28 @@ const rootValue = {
     return loadArtifact(context, "/metagraph/registry-summary.json");
   },
 
+  async saved_query({ id, params }, context) {
+    // #7642: the same maintainer-curated template executor the REST route and
+    // run_saved_query MCP tool share (src/saved-queries.mjs) -- template
+    // lookup, param coercion/validation, and execution are all its. Its
+    // not_found (unknown id) and invalid_params toolErrors map to
+    // BAD_USER_INPUT, matching this file's invalid-argument convention; any
+    // other executor failure surfaces as a normal GraphQL error.
+    try {
+      return await runSavedQuery(context.env, id, params ?? {});
+    } catch (err) {
+      if (
+        err?.toolError &&
+        (err.code === "not_found" || err.code === "invalid_params")
+      ) {
+        throw new GraphQLError(err.message, {
+          extensions: { code: "BAD_USER_INPUT" },
+        });
+      }
+      throw err;
+    }
+  },
+
   source_health(_args, context) {
     // Same baked artifact the REST route + get_source_health MCP tool read.
     return loadArtifact(context, "/metagraph/source-health.json");

tests/graphql.test.mjs

@@ -16667,6 +16667,44 @@ describe("graphql — registry_leaderboards (#5661, shared composer + REST-match
   });
 });
 
+describe("graphql — saved_query (#7642, curated saved-query templates)", () => {
+  test("runs a template through the shared executor and returns the {query_id, params, data} envelope", async () => {
+    const { status, body } = await gql(
+      `{ saved_query(id: "subnet-leaderboard", params: { limit: 5 }) }`,
+    );
+    assert.equal(status, 200);
+    assert.equal(body.errors, undefined);
+    const result = body.data.saved_query;
+    assert.equal(result.query_id, "subnet-leaderboard");
+    assert.equal(result.params.limit, 5);
+    assert.ok(result.data, "expected the executed template's data payload");
+  });
+
+  test("an unknown id is BAD_USER_INPUT listing the valid template ids", async () => {
+    const { status, body } = await gql(
+      `{ saved_query(id: "no-such-template") }`,
+    );
+    assert.equal(status, 200);
+    assert.ok(body.errors.find((e) => e.extensions?.code === "BAD_USER_INPUT"));
+    assert.match(body.errors[0].message, /no-such-template/);
+    assert.match(body.errors[0].message, /subnet-leaderboard/);
+    assert.equal(body.data?.saved_query ?? null, null);
+  });
+
+  test("an unknown param is BAD_USER_INPUT, not a silent default", async () => {
+    const { status, body } = await gql(
+      `{ saved_query(id: "subnet-leaderboard", params: { not_a_real_param: 1 }) }`,
+    );
+    assert.equal(status, 200);
+    assert.ok(body.errors.find((e) => e.extensions?.code === "BAD_USER_INPUT"));
+    assert.match(body.errors[0].message, /not_a_real_param/);
+  });
+
+  test("is priced at the relationship-field complexity weight", () => {
+    assert.equal(FIELD_COMPLEXITY.saved_query, FIELD_COMPLEXITY.candidates);
+  });
+});
+
 describe("Query.subnet_hyperparameters / subnet_hyperparameters_history", () => {
   const HP_FIELDS =
     "kappa_ratio immunity_period tempo registration_allowed min_burn_tao bonds_moving_avg_raw liquid_alpha_enabled min_childkey_take_ratio";