feat(api): add REST filter parity to GraphQL subnet_gaps

[RealDiligent]

Closes #7880

What

subnet_gaps returned the baked gap report as an unparameterized JSON blob, while GET /api/v1/subnets/{netuid}/gaps pages the same artifact through csvListQuery("review-gap-priorities", { exclude: ["netuid"] }). This adds the missing arguments so the two surfaces agree.

• Filters: curation_level, missing_kinds, review_state — the exact three the REST route exposes (netuid is the path param, excluded there and here).
• Sort/order/projection/paging: sort, order, fields, limit, cursor.
• Pagination meta: total, returned, limit, cursor, next_cursor, sort, order, matching REST's envelope.

An unsupported filter or sort value is a BAD_USER_INPUT GraphQL error, not a silently substituted default — the convention subnet_evidence and subnet_candidates already follow in this file.

How

The resolver passes the report to applyQueryFilters(report, url, "review-gap-priorities", [...]) — the same shared helper the REST pipeline runs, sourced from the same API_QUERY_COLLECTIONS entry, so the filter and sort allowlists cannot drift from REST.

Only priorities is filtered; the rest of the envelope is returned unchanged. This is deliberate. The artifact also carries enrichment_queue, which is part of the documented response and which existing consumers of the unparameterized field read today. Routing the field through loadSubnetGapsList instead would have returned that loader's narrower result and silently dropped enrichment_queue — a breaking change well outside the scope of adding filter parity. No loader or MCP file is touched by this PR, so MCP list_subnet_gaps and its error classification are byte-for-byte unchanged.

Tests

tests/graphql.test.ts — filter + sort + fields projection + limit/cursor in one query, asserting the envelope (enrichment_queue included) survives; truncated-page next_cursor round-trip; unsupported enum value → BAD_USER_INPUT. The pre-existing passthrough and cold-artifact-null tests are unmodified and still pass.

All 988 tests in tests/graphql.test.ts pass. tsc --noEmit clean, eslint clean, validate-api / validate-mcp / validate-graphql-types-drift all pass, generated types regenerated and committed. Local vitest --coverage over the changed src/graphql.ts lines: 0 uncovered statements, 0 partial branches across all 56 changed source lines.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.67%. Comparing base (c84ecc0) to head (5b734e8).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8048   +/-   ##
=======================================
  Coverage   97.67%   97.67%           
=======================================
  Files         219      220    +1     
  Lines       27104    27192   +88     
  Branches    10745    10789   +44     
=======================================
+ Hits        26473    26561   +88     
  Misses        140      140           
  Partials      491      491           

Files with missing lines	Coverage Δ
src/graphql-sdl.ts	100.00% <ø> (ø)
src/graphql.ts	99.65% <100.00%> (+<0.01%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-24 20:44:55 UTC}

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds REST-parity filter/sort/paging args to GraphQL subnet_gaps by piping the baked artifact's priorities array through the same applyQueryFilters/csvListQuery('review-gap-priorities') helper REST uses, preserving the untouched enrichment_queue field and following the existing subnet_evidence/subnet_candidates BAD_USER_INPUT convention in this file. SDL, generated types, resolver, and tests are updated consistently, and the added tests exercise filter+sort+fields+cursor, truncated-page next_cursor, and the invalid-filter error path.

Nits — 3 non-blocking

• src/graphql.ts:~3612 builds a throwaway `new URL("https:​//graphql.internal/subnets/gaps")` purely to hand searchParams to applyQueryFilters — worth a one-line comment noting it's never dispatched as a real request, since the external scan flagged it as a hardcoded endpoint.
• The pagination-meta fallback (`page.total ?? priorities.length`, etc.) assumes `transformed.meta.pagination` is always populated on success; confirm applyQueryFilters actually sets those keys for the review-gap-priorities collection rather than relying on the `??` fallback silently masking a missing meta shape.
• Consider extracting the repeated `[name, value] -> searchParams.set` param-building block into a small shared helper if a fourth filterable resolver adopts this same pattern, to avoid drift across subnet_gaps/subnet_evidence/subnet_candidates.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#7880
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 370 registered-repo PR(s), 154 merged, 37 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 370 PR(s), 37 issue(s).

Linked issue satisfaction

Addressed
The PR adds curation_level, missing_kinds, review_state, sort, order, fields, limit, and cursor arguments to subnet_gaps and routes them through applyQueryFilters using the same review-gap-priorities collection/allowlist as REST, matching the issue's requirement to mirror the root gaps(...) field's filter shape.

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, Ruby, JavaScript, Svelte, TypeScript, Cuda, Markdown, MDX
• Official Gittensor activity: 370 PR(s), 37 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.