subgraph-registry-mcp 0.9.0 → 0.9.2

package/README.md

@@ -188,6 +188,53 @@ in the main list and the 40-day-old Monad perps subgraph under `emerging`.
 so it is already age-neutral — it carries the `maturity` labels but no
 `emerging` list, because a three-week-old subgraph can top it on merit.
 
+### Ranking
+
+Three tools rank, and each ranks differently on purpose:
+
+- **`search_subgraphs`** — orders by how many of your query terms matched, then
+  by reliability. OR-ing the terms and ordering on reliability alone meant a
+  popular subgraph matching one incidental word beat a precise match on all
+  three, so being *more* specific returned worse answers. Version tokens
+  (`v2`, `v3`, `v4`) are kept rather than dropped as too short.
+- **`semantic_search_subgraphs`** — orders by `semantic_score × (0.5 + 0.5 ×
+  reliability)`. Pure cosine put testnets first, since their text is nearly
+  identical to mainnet's. The 0.5 floor keeps new subgraphs competitive.
+- **`recommend_subgraph`** — infers domain and protocol type from the goal, but
+  as a *ranking bonus*, never a filter. As a filter, one bad keyword collapsed
+  the candidate pool to nothing.
+
+A term matching a subgraph's **name** counts for more than one matching its
+description — `%ens%` also matches "tok**ens**", so equal weighting handed a
+search for `ens` to four Uniswap subgraphs.
+
+Chain names are aliased, so `ethereum`, `arbitrum`, `polygon` and `bnb` resolve
+to the corpus values `mainnet`, `arbitrum-one`, `matic` and `bsc`.
+
+### Testnets
+
+723 of the 5,425 served subgraphs are on testnets, and their text is nearly
+identical to their mainnet twins', so they compete for the top slot. They are
+**excluded by default** and every result carries `testnet: true|false`. Pass
+`include_testnets: true` to see them — and an explicit request for a testnet
+network (`network: "sepolia"`) always wins over the default, so that still
+returns exactly what you asked for.
+
+## Using the registry from payql
+
+[`payql`](https://www.npmjs.com/package/payql) can use this registry as its
+free discovery source instead of paying for a network-subgraph query. Run the
+registry's HTTP transport and point payql at it:
+
+```bash
+npx subgraph-registry-mcp --http-only          # serves :3848
+PAYQL_REGISTRY_URL=http://127.0.0.1:3848/graphql npx -y payql
+```
+
+`POST /graphql` answers in the Graph network subgraph's `subgraphMetadataSearch`
+shape, which is what payql already parses — so this needs no change on payql's
+side, and discovery becomes free and locally-ranked.
+
 ### Denied deployments
 
 Curation-denied deployments (`deniedAt > 0` — denied indexing rewards, usually

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subgraph-registry-mcp",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "mcpName": "io.github.PaulieB14/subgraph-registry-mcp",
   "description": "MCP server for agent-friendly subgraph discovery on The Graph Network. 15,330 classified subgraphs with x402 query URLs ($0.01 USDC on Base, no API key required), reliability scoring, and protocol classification.",
   "type": "module",

package/src/index.js

@@ -65,7 +65,7 @@ const GITHUB_DB_URL =
 //   3. Paste the new hash here and bump package.json version
 //   4. Update SKILL.md "Verifying the registry" section
 const EXPECTED_DB_SHA256 =
-  "ec7bb54f72379c0d4921b0c34c1c666c46e44c82f334efda440aeb2db09fa2d0";
+  "425b7a5bde8f61d8ae2f26ea6e201ffd3308c3328a0547fb0d29530222eba0d2";
 // Skip-verification escape hatch (set to "1" only if you're rebuilding the DB
 // locally and know what you're doing — never set in agent-runtime defaults).
 const SKIP_VERIFY = process.env.SUBGRAPH_REGISTRY_SKIP_VERIFY === "1";
@@ -177,6 +177,109 @@ function getDb() {
   return db;
 }
 
+// ── Network aliases ────────────────────────────────────────
+// The corpus stores graph-node's chain IDs (`mainnet`, `arbitrum-one`,
+// `matic`), but every human and every model says "ethereum", "arbitrum",
+// "polygon" — and so does our own auto_description, which prints the pretty
+// name from classifier.py NETWORK_NAMES. So an agent reads "Ethereum" in a
+// description, passes network:"ethereum" back, and gets zero results with no
+// error. SKILL.md made it worse by documenting `ethereum, arbitrum, base` as
+// the example values; two of those three matched nothing.
+// mainnet/bsc/arbitrum-one/matic alone are ~45% of the corpus.
+const NETWORK_ALIASES = {
+  ethereum: "mainnet",
+  eth: "mainnet",
+  "ethereum-mainnet": "mainnet",
+  arbitrum: "arbitrum-one",
+  "arbitrum one": "arbitrum-one",
+  arb: "arbitrum-one",
+  polygon: "matic",
+  "polygon-pos": "matic",
+  bnb: "bsc",
+  "bnb-chain": "bsc",
+  "binance-smart-chain": "bsc",
+  binance: "bsc",
+  op: "optimism",
+  "optimism-mainnet": "optimism",
+  avax: "avalanche",
+  "avalanche-c-chain": "avalanche",
+  xdai: "gnosis",
+  zksync: "zksync-era",
+  "zksync era": "zksync-era",
+  blast: "blast-mainnet",
+  "polygon-zk": "polygon-zkevm",
+  near: "near-mainnet",
+  mode: "mode-mainnet",
+  sei: "sei-mainnet",
+  ftm: "fantom",
+};
+
+// Normalize a caller-supplied chain name to the value stored in the corpus.
+// Unknown values pass through untouched so a legitimate new chain still works.
+function normalizeNetwork(name) {
+  if (!name || typeof name !== "string") return name;
+  const k = name.trim().toLowerCase();
+  return NETWORK_ALIASES[k] || k;
+}
+
+// ── Testnets ───────────────────────────────────────────────
+// 723 of the 5,425 served, non-denied subgraphs (13.3%) are on testnets, and
+// they compete directly with production because a testnet deployment's text is
+// near-identical to its mainnet twin's — that is exactly how ENS Sepolia (58
+// queries/30d) came to outrank ENS mainnet (34.8M queries/30d).
+//
+// Detected from the network name rather than a new column, so it works on the
+// corpus already shipped. All 57 matching networks were checked by hand; the
+// six without an explicit -testnet/-sepolia/-goerli suffix (chapel, fuji,
+// holesky, holesky-beacon, mumbai, polygon-amoy) are the well-known BSC,
+// Avalanche, Ethereum and Polygon testnets.
+const TESTNET_MARKERS = [
+  "sepolia", "goerli", "testnet", "devnet", "chapel", "fuji",
+  "holesky", "mumbai", "amoy", "baobab", "rinkeby", "kovan",
+];
+
+function isTestnetNetwork(name) {
+  if (!name) return false;
+  const n = String(name).toLowerCase();
+  return TESTNET_MARKERS.some((m) => n.includes(m));
+}
+
+// SQL fragment excluding testnets. Static string — the markers are a constant
+// allowlist, never caller input, so there is nothing to bind or escape.
+const NOT_TESTNET_SQL = TESTNET_MARKERS.map(
+  (m) => `network NOT LIKE '%${m}%'`,
+).join(" AND ");
+
+// Whether to hide testnets for this call.
+//
+// The trap: a caller who explicitly asks for network:"sepolia" must not get an
+// empty result because a default filter silently contradicts their request.
+// An explicit testnet network always wins over the default exclusion.
+function shouldExcludeTestnets({ include_testnets, network }) {
+  if (include_testnets) return false;
+  if (network && isTestnetNetwork(normalizeNetwork(network))) return false;
+  return true;
+}
+
+// Tokenize a free-text query into searchable terms.
+//
+// The old inline version was `.filter((w) => w.length > 2)`, which silently
+// dropped every protocol version token — "v2", "v3", "v4" are all two chars.
+// That made "uniswap v3" byte-identical to "uniswap", so the single most
+// natural way to disambiguate the largest protocol family in the corpus did
+// nothing at all. Keep the length floor for noise words, but let version
+// tokens through.
+const VERSION_TOKEN_RE = /^v\d+$/;
+
+function queryTerms(query) {
+  return query
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((w) => w.length > 2 || VERSION_TOKEN_RE.test(w))
+    .slice(0, 5);
+}
+
 // ── Maturity / cold-start handling ─────────────────────────
 // reliability_score is built from four CUMULATIVE inputs (curation signal,
 // indexer stake, lifetime query fees, 30d volume — see _reliability_score in
@@ -266,6 +369,7 @@ function searchSubgraphs({
   min_reliability = 0,
   include_unserved = false,
   include_denied = false,
+  include_testnets = false,
   limit = 20,
 } = {}) {
   const conditions = [];
@@ -290,6 +394,9 @@ function searchSubgraphs({
   if (!include_denied) {
     conditions.push("denied_at = 0");
   }
+  if (shouldExcludeTestnets({ include_testnets, network })) {
+    conditions.push(`(${NOT_TESTNET_SQL})`);
+  }
 
   if (domain) {
     conditions.push("domain = ?");
@@ -297,7 +404,7 @@ function searchSubgraphs({
   }
   if (network) {
     conditions.push("network = ?");
-    params.push(network);
+    params.push(normalizeNetwork(network));
   }
   if (protocol_type) {
     conditions.push("protocol_type = ?");
@@ -311,9 +418,34 @@ function searchSubgraphs({
     conditions.push("reliability_score >= ?");
     params.push(min_reliability);
   }
+  // Terms are OR'd for recall, then RANKED by how many of them matched.
+  //
+  // Before this, a multi-word query OR'd its terms and ordered the result by
+  // reliability alone, so a high-reliability subgraph matching ONE incidental
+  // word beat a lower-reliability one matching all three. The effect was that
+  // being more specific made the answer worse: "aave lending arbitrum"
+  // returned uniswap-v3-arbitrum, Arbitrum Minimal, camelot-amm-v3 and Graph
+  // TAP — not one Aave subgraph — while the bare query "aave" was correct.
+  //
+  // Keep the OR (dropping to AND would kill recall on descriptions that
+  // phrase things differently) and let matched_terms break the tie first.
+  //
+  // A hit in display_name is worth 3, a hit in the description 1. Counting
+  // them equally is not enough on short terms, where LIKE '%term%' matches
+  // half the corpus incidentally: searching "ens" scored ENS and four Uniswap
+  // subgraphs at 1 apiece — "tokens" contains "ens" — and reliability then
+  // handed the top slots to Uniswap. Weighting the name restores ENS to #1
+  // without narrowing what still gets found.
+  const matchParams = [];
+  let matchExpr = "0";
   if (query) {
-    const words = query.trim().split(/\s+/).filter((w) => w.length > 2).slice(0, 5);
+    const words = queryTerms(query);
     if (words.length) {
+      matchExpr = words
+        .map(() => "((CASE WHEN display_name LIKE ? THEN 3 ELSE 0 END) + (CASE WHEN (description LIKE ? OR auto_description LIKE ?) THEN 1 ELSE 0 END))")
+        .join(" + ");
+      words.forEach((w) => matchParams.push(`%${w}%`, `%${w}%`, `%${w}%`));
+
       const wordConds = words.map(() => "(display_name LIKE ? OR description LIKE ? OR auto_description LIKE ?)");
       words.forEach((w) => params.push(`%${w}%`, `%${w}%`, `%${w}%`));
       conditions.push(`(${wordConds.join(" OR ")})`);
@@ -327,18 +459,20 @@ function searchSubgraphs({
   // Over-fetch to allow dedup by IPFS hash (same deployment, different subgraph IDs)
   const fetchLimit = limit * 3;
   const sql = `
-    SELECT ${SEARCH_COLS}
+    SELECT ${SEARCH_COLS}, (${matchExpr}) AS matched_terms
     FROM subgraphs
     ${where}
-    ORDER BY reliability_score DESC
+    ORDER BY matched_terms DESC, reliability_score DESC
     LIMIT ?
   `;
   // Snapshot the filter params BEFORE the LIMIT is appended — the emerging
   // companion query reuses the same WHERE and must not inherit this LIMIT.
   const filterParams = [...params];
-  params.push(fetchLimit);
 
-  const rows = getDb().prepare(sql).all(...params);
+  // Positional binding order: the SELECT-clause scoring expression is bound
+  // before the WHERE clause, so matchParams must lead. filterParams stays
+  // WHERE-only, which is what the emerging companion query needs.
+  const rows = getDb().prepare(sql).all(...matchParams, ...filterParams, fetchLimit);
   // Dedup by IPFS hash — keep highest reliability per deployment
   const seenIpfs = new Set();
   const results = [];
@@ -362,6 +496,8 @@ function searchSubgraphs({
       // caller passed include_denied — surfaced so that choice stays visible
       // in the result rather than being silently carried.
       denied: Boolean(r.denied_at),
+    testnet: isTestnetNetwork(r.network),
+      testnet: isTestnetNetwork(r.network),
       // Ready-to-run GraphQL generated from this subgraph's actual schema — so an
       // agent can POST it to query_url_x402 immediately, no get_subgraph_detail round-trip.
       example_query: r.example_query || null,
@@ -394,6 +530,7 @@ function searchSubgraphs({
     powered_by_substreams: Boolean(r.powered_by_substreams),
     active_allocation_count: r.active_allocation_count || 0,
     denied: Boolean(r.denied_at),
+    testnet: isTestnetNetwork(r.network),
     example_query: r.example_query || null,
     age_days: ageDays(r.created_at),
     maturity: maturityOf(r.created_at),
@@ -427,59 +564,94 @@ function recommendSubgraph({ goal, chain = "" }) {
     lending: ["lend", "borrow", "loan", "collateral", "aave", "compound"],
     bridge: ["bridge", "cross-chain"],
     staking: ["stake", "validator", "delegation"],
-    options: ["option", "call", "put", "strike"],
+    // "call", "put" and "strike" are gone. They are ordinary English words —
+    // "reputation" contains "put", so the goal "reputation scores for onchain
+    // agents" inferred protocol_type ["options"] and returned the Polygon
+    // Optimistic Oracle. "option" alone is specific enough to keep.
+    options: ["option", "derivatives contract"],
     perpetuals: ["perp", "perpetual", "leverage", "margin"],
     governance: ["governance", "vote", "proposal"],
     "name-service": ["ens", "name service", "domain name"],
     "nft-marketplace": ["nft market", "opensea", "blur"],
   };
 
+  // Match on word boundaries, not bare substrings. Boundaries alone would not
+  // have saved "reputation"/"put" if "put" had stayed in the list — hence the
+  // removals above and the demotion from filter to bonus below — but they do
+  // stop "smart contract" inferring nfts via "art", and "start"/"chart"/
+  // "party" doing the same.
+  const hitsGoal = (kws) =>
+    kws.some((k) =>
+      new RegExp(`\\b${k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(goalLower),
+    );
   const domains = Object.entries(domainMap)
-    .filter(([, kws]) => kws.some((k) => goalLower.includes(k)))
+    .filter(([, kws]) => hitsGoal(kws))
     .map(([d]) => d);
   const ptypes = Object.entries(typeMap)
-    .filter(([, kws]) => kws.some((k) => goalLower.includes(k)))
+    .filter(([, kws]) => hitsGoal(kws))
     .map(([t]) => t);
 
   // recommend_subgraph exposes no include_* escape hatches — it answers "which
   // one should I use", so a curation-denied deployment is never the right
   // answer and the filter is unconditional here.
   const conditions = ["active_allocation_count > 0", "denied_at = 0"];
+  if (shouldExcludeTestnets({ include_testnets: false, network: chain })) {
+    conditions.push(`(${NOT_TESTNET_SQL})`);
+  }
   const params = [];
 
   if (chain) {
     conditions.push("network = ?");
-    params.push(chain);
+    params.push(normalizeNetwork(chain));
+  }
+  // The inferred domain/protocol_type used to go into the WHERE clause, so a
+  // single bad substring collapsed the candidate pool instead of merely
+  // mis-ordering it: "tokens" contains "ens" and cut 5,479 candidates to 78
+  // with ENS on top, and chain:"arbitrum" returned total_matches 0 with no
+  // error at all. Inference is a guess about intent; a guess belongs in the
+  // ORDER BY, where being wrong costs a few positions, not every result.
+  //
+  // The text terms now ALWAYS constrain (they used to be skipped entirely
+  // whenever anything was inferred), so the pool stays tied to what was
+  // actually asked.
+  const scoreParts = [];
+  const scoreParams = [];
+
+  const words = queryTerms(goalLower);
+  if (words.length) {
+    const textConds = words.map(() => "(display_name LIKE ? OR description LIKE ? OR auto_description LIKE ?)");
+    scoreParts.push(
+      words
+        .map(() => "((CASE WHEN display_name LIKE ? THEN 4 ELSE 0 END) + (CASE WHEN (description LIKE ? OR auto_description LIKE ?) THEN 1 ELSE 0 END))")
+        .join(" + "),
+    );
+    words.forEach((w) => scoreParams.push(`%${w}%`, `%${w}%`, `%${w}%`));
+    words.forEach((w) => params.push(`%${w}%`, `%${w}%`, `%${w}%`));
+    conditions.push(`(${textConds.join(" OR ")})`);
   }
   if (domains.length) {
-    conditions.push(`domain IN (${domains.map(() => "?").join(",")})`);
-    params.push(...domains);
+    scoreParts.push(`(CASE WHEN domain IN (${domains.map(() => "?").join(",")}) THEN 1 ELSE 0 END)`);
+    scoreParams.push(...domains);
   }
   if (ptypes.length) {
-    conditions.push(`protocol_type IN (${ptypes.map(() => "?").join(",")})`);
-    params.push(...ptypes);
-  }
-
-  if (!domains.length && !ptypes.length) {
-    const words = goalLower.split(/\s+/).filter((w) => w.length > 2).slice(0, 5);
-    if (words.length) {
-      const textConds = words.map(() => "(display_name LIKE ? OR description LIKE ?)");
-      words.forEach((w) => params.push(`%${w}%`, `%${w}%`));
-      conditions.push(`(${textConds.join(" OR ")})`);
-    }
+    scoreParts.push(`(CASE WHEN protocol_type IN (${ptypes.map(() => "?").join(",")}) THEN 1 ELSE 0 END)`);
+    scoreParams.push(...ptypes);
   }
 
+  const goalScore = scoreParts.length ? scoreParts.join(" + ") : "0";
   const where = `WHERE ${conditions.join(" AND ")}`;
   const sql = `
     SELECT id, display_name, description, auto_description, domain, protocol_type, network,
-           reliability_score, ipfs_hash, canonical_entities, active_allocation_count, example_query
+           reliability_score, ipfs_hash, canonical_entities, active_allocation_count, example_query,
+           (${goalScore}) AS goal_score
     FROM subgraphs
     ${where}
-    ORDER BY reliability_score DESC
+    ORDER BY goal_score DESC, reliability_score DESC
     LIMIT 15
   `;
 
-  const rows = getDb().prepare(sql).all(...params);
+  // SELECT-clause params bind before WHERE-clause params.
+  const rows = getDb().prepare(sql).all(...scoreParams, ...params);
   // De-dup first so we batch the stability lookup over the trimmed set.
   const seenIpfs = new Set();
   const keep = [];
@@ -594,7 +766,34 @@ function getSubgraphDetail({ subgraph_id }) {
 // Stable, machine-readable manifest other crawlers and agents can index
 // without going through MCP. Served at /.well-known/subgraph/{id}.jsonld and
 // /subgraphs/{id}.jsonld (alias, same payload).
-const JSONLD_CONTEXT = "https://subgraph-registry.paulieb14.dev/context.jsonld";
+// Every JSON-LD document used to carry @context and @id under
+// subgraph-registry.paulieb14.dev, a hostname that has never resolved
+// (NXDOMAIN). A JSON-LD processor that dereferences the context gets nothing,
+// and the @id identified each subgraph by a URL that 404s — so the documents
+// the README calls "auto-discoverable" were undiscoverable by construction.
+//
+// Two changes. The context is inlined, because a context that must be fetched
+// is a dependency on a host we do not run. And @id now defaults to The Graph's
+// explorer, which is the canonical, resolving identifier for a subgraph and is
+// where we want an agent following the link to end up anyway.
+//
+// Set SUBGRAPH_REGISTRY_BASE_URL to serve these under your own origin (the
+// --http-only transport does exactly that).
+const PUBLIC_BASE_URL = (process.env.SUBGRAPH_REGISTRY_BASE_URL || "").replace(/\/+$/, "");
+const EXPLORER_BASE = "https://thegraph.com/explorer/subgraphs";
+
+function subgraphIri(id) {
+  return PUBLIC_BASE_URL ? `${PUBLIC_BASE_URL}/subgraphs/${id}` : `${EXPLORER_BASE}/${id}`;
+}
+
+const JSONLD_CONTEXT = {
+  "@vocab": "https://schema.org/",
+  id: "@id",
+  name: "https://schema.org/name",
+  description: "https://schema.org/description",
+  network: "https://schema.org/provider",
+  SubgraphDeployment: "https://schema.org/Dataset",
+};
 
 function buildJsonLdManifest(row) {
   if (!row) return null;
@@ -603,7 +802,7 @@ function buildJsonLdManifest(row) {
   return {
     "@context": JSONLD_CONTEXT,
     "@type": "SubgraphDeployment",
-    "@id": `https://subgraph-registry.paulieb14.dev/subgraphs/${row.id}`,
+    "@id": subgraphIri(row.id),
     id: row.id,
     ipfsHash: row.ipfs_hash,
     name: row.display_name,
@@ -739,6 +938,7 @@ async function semanticSearchSubgraphs({
   min_score = 0.3,
   include_unserved = false,
   include_denied = false,
+  include_testnets = false,
   domain = "",
   network = "",
   protocol_type = "",
@@ -768,13 +968,16 @@ async function semanticSearchSubgraphs({
   if (!include_denied) {
     conditions.push("denied_at = 0");
   }
+  if (shouldExcludeTestnets({ include_testnets, network })) {
+    conditions.push(`(${NOT_TESTNET_SQL})`);
+  }
   if (domain) {
     conditions.push("domain = ?");
     params.push(domain);
   }
   if (network) {
     conditions.push("network = ?");
-    params.push(network);
+    params.push(normalizeNetwork(network));
   }
   if (protocol_type) {
     conditions.push("protocol_type = ?");
@@ -806,7 +1009,23 @@ async function semanticSearchSubgraphs({
     if (score < min_score) continue;
     scored.push({ row: r, score });
   }
-  scored.sort((a, b) => b.score - a.score);
+  // Rank on similarity WEIGHTED by reliability, not similarity alone.
+  //
+  // Pure cosine made this the only tool in the package that ignored the
+  // registry's own quality signal, and testnets win on pure cosine because
+  // their text is near-identical to mainnet's. Observed: "ENS domain name
+  // registrations" put ENS Sepolia (58 queries/30d, reliability 0.2463) above
+  // ENS mainnet (34.8M queries/30d, reliability 0.9775) on a cosine margin of
+  // 0.0105 — a rounding error deciding between a toy and the real thing.
+  //
+  // The 0.5 floor is deliberate: reliability is itself age-biased (see the
+  // maturity block above), so a multiplier that ran to 0 would re-bury every
+  // new subgraph and undo the emerging work. At 0.5 + 0.5*r a brand-new
+  // subgraph keeps half its similarity and can still outrank an established
+  // one it genuinely beats on meaning, while a 0.01 cosine tie resolves
+  // toward the subgraph that is actually serving traffic.
+  const effective = (s) => s.score * (0.5 + 0.5 * (s.row.reliability_score || 0));
+  scored.sort((a, b) => effective(b) - effective(a));
 
   const results = [];
   for (const { row: r, score } of scored) {
@@ -826,6 +1045,8 @@ async function semanticSearchSubgraphs({
       powered_by_substreams: Boolean(r.powered_by_substreams),
       active_allocation_count: r.active_allocation_count || 0,
       denied: Boolean(r.denied_at),
+    testnet: isTestnetNetwork(r.network),
+      testnet: isTestnetNetwork(r.network),
       example_query: r.example_query || null,
       // No `emerging` companion list here: this tool ranks by cosine score,
       // not reliability_score, so a three-week-old subgraph can and does take
@@ -887,6 +1108,7 @@ function getSchemaChanges({ subgraph_id, since_timestamp = 0 }) {
         `SELECT fingerprint, prev_fingerprint, detected_at, ipfs_hash
          FROM schema_history
          WHERE subgraph_id = ? AND detected_at >= ?
+           AND prev_fingerprint IS NOT NULL
          ORDER BY detected_at DESC`,
       )
       .all(subgraph_id, since);
@@ -898,17 +1120,41 @@ function getSchemaChanges({ subgraph_id, since_timestamp = 0 }) {
     };
   }
 
+  // Baselines are excluded from `rows`, so "no rows" now means "never changed
+  // since we first saw it" rather than "no history". Those are very different
+  // claims to an agent deciding whether a schema is safe to depend on, and
+  // collapsing them to stable_days: null loses the distinction. Report the
+  // first sighting separately and measure stability from it, so a subgraph
+  // that has genuinely never changed reads as stable — which is the honest
+  // answer, and the one the old code accidentally gave everybody.
+  let first_seen_at = null;
+  try {
+    const fs = getDb()
+      .prepare(
+        "SELECT MIN(detected_at) AS t FROM schema_history WHERE subgraph_id = ?",
+      )
+      .get(subgraph_id);
+    first_seen_at = fs && fs.t != null ? fs.t : null;
+  } catch {
+    first_seen_at = null;
+  }
+
+  const never_changed = rows.length === 0;
   const last_changed_at = rows.length > 0 ? rows[0].detected_at : null;
+  const stable_since = last_changed_at !== null ? last_changed_at : first_seen_at;
   const stable_days =
-    last_changed_at !== null
-      ? Math.round(((now - last_changed_at) / 86400) * 10) / 10
+    stable_since !== null
+      ? Math.round(((now - stable_since) / 86400) * 10) / 10
       : null;
 
   return {
     subgraph_id,
     total_changes: rows.length,
+    never_changed,
+    first_seen_at,
     last_changed_at,
     stable_days,
+    stable_days_basis: never_changed ? "first_seen" : "last_change",
     changed_within_24h:
       last_changed_at !== null && now - last_changed_at < 86400,
     changed_within_7d:
@@ -932,7 +1178,8 @@ function getSchemaStabilityFor(id) {
     const r = getDb()
       .prepare(
         "SELECT MAX(detected_at) AS schema_changed_at " +
-          "FROM schema_history WHERE subgraph_id = ?",
+          "FROM schema_history WHERE subgraph_id = ? " +
+          "AND prev_fingerprint IS NOT NULL",
       )
       .get(id);
     if (!r || r.schema_changed_at == null) {
@@ -958,6 +1205,7 @@ function getSchemaStabilityBatch(ids) {
         `SELECT subgraph_id, MAX(detected_at) AS schema_changed_at
          FROM schema_history
          WHERE subgraph_id IN (${placeholders})
+           AND prev_fingerprint IS NOT NULL
          GROUP BY subgraph_id`,
       )
       .all(...ids);
@@ -1011,6 +1259,11 @@ const TOOLS = [
           description: "Include curation-denied deployments (deniedAt > 0 — denied indexing rewards, typically spam, duplicates or deprecations). Default false. When true, each result carries denied: true so the choice stays visible.",
           default: false,
         },
+        include_testnets: {
+          type: "boolean",
+          description: "Include testnet deployments (sepolia, goerli, holesky, chapel, fuji, mumbai, amoy, *-testnet). Default false — a testnet twin's text is near-identical to its mainnet original, so it competes for the top slot without being the thing anyone wanted. Ignored when you explicitly request a testnet network, so network:\"sepolia\" still works. Each result carries testnet: true|false.",
+          default: false,
+        },
       },
     },
   },
@@ -1085,6 +1338,11 @@ const TOOLS = [
           description: "Include curation-denied deployments (deniedAt > 0 — denied indexing rewards, typically spam, duplicates or deprecations). Default false. When true, each result carries denied: true so the choice stays visible.",
           default: false,
         },
+        include_testnets: {
+          type: "boolean",
+          description: "Include testnet deployments (sepolia, goerli, holesky, chapel, fuji, mumbai, amoy, *-testnet). Default false — a testnet twin's text is near-identical to its mainnet original, so it competes for the top slot without being the thing anyone wanted. Ignored when you explicitly request a testnet network, so network:\"sepolia\" still works. Each result carries testnet: true|false.",
+          default: false,
+        },
         domain: {
           type: "string",
           description: "Pre-filter by domain (defi, nfts, dao, gaming, identity, infrastructure, social, analytics)",
@@ -1207,6 +1465,62 @@ function startHttpTransport(port) {
     res.json({ status: "ok", subgraphs: getDb().prepare("SELECT COUNT(*) as c FROM subgraphs").get().c });
   });
 
+  // ── payql compatibility shim ─────────────────────────────────────
+  // payql (npm `payql`, same author) advertises PAYQL_REGISTRY_URL as a "free
+  // discovery source (e.g. your own subgraph registry)" — but it POSTs the
+  // Graph network subgraph's GraphQL document and reads
+  // `data.subgraphMetadataSearch`, a shape this registry has never served. So
+  // pointing payql here returned zero hits and, because the response still
+  // parsed as JSON, it failed as an empty success rather than an error. The
+  // two projects were built to compose and the seam between them was dead.
+  //
+  // Serve that shape. No GraphQL engine needed: the only input that varies is
+  // the `text` variable, and the result set is what search_subgraphs already
+  // computes. Answering in the incumbent's vocabulary means payql works
+  // against this registry with no change on its side.
+  //
+  // Token amounts are returned as wei-scale strings because payql divides them
+  // by 1e18 (weiToGRT); handing back plain GRT would under-report by 1e18.
+  app.post("/graphql", express.json({ limit: "256kb" }), (req, res) => {
+    try {
+      const text = String(req.body?.variables?.text ?? "");
+      const first = Math.max(1, Math.min(Number(req.body?.variables?.first) || 10, 50));
+      // payql sends a prefix tsquery ("uniswap:* | v3:*"); strip the fulltext
+      // operators back to plain words before handing them to LIKE matching.
+      const plain = text.replace(/:\*/g, " ").replace(/[|&()]/g, " ").trim();
+      const { subgraphs = [] } = searchSubgraphs({ query: plain, limit: first });
+      res.json({
+        data: {
+          subgraphMetadataSearch: subgraphs.map((s) => ({
+            displayName: s.display_name,
+            description: s.description,
+            categories: s.domain ? [s.domain] : [],
+            subgraphs: [
+              {
+                id: s.id,
+                active: true,
+                currentSignalledTokens: null,
+                currentVersion: {
+                  subgraphDeployment: {
+                    ipfsHash: s.ipfs_hash,
+                    stakedTokens: null,
+                    signalledTokens: null,
+                    queryFeesAmount: null,
+                  },
+                },
+              },
+            ],
+          })),
+        },
+      });
+    } catch (err) {
+      // Answer in GraphQL's error shape so a client that only knows GraphQL
+      // sees a failure instead of an empty success — the exact trap this
+      // route exists to close.
+      res.status(500).json({ errors: [{ message: String(err?.message || err) }] });
+    }
+  });
+
   // ── OpenAPI 3.1 spec (auto-generated at release time) ────────────
   // scripts/gen-openapi.js inventories the TOOLS array + the REST
   // routes below and writes data/openapi.json. We serve the file
@@ -1266,7 +1580,7 @@ function startHttpTransport(port) {
       generatedAt: new Date().toISOString(),
       count: rows.length,
       subgraphs: rows.map((r) => ({
-        "@id": `https://subgraph-registry.paulieb14.dev/subgraphs/${r.id}`,
+        "@id": subgraphIri(r.id),
         id: r.id,
         name: r.display_name,
         network: r.network,