feat(api): public SN74 contribution-interface descriptor for metagraphed discovery (#695, gittensory side)

[JSONbored]

What

The gittensory half of the metagraphed discovery funnel (#695): a public, unauthenticated, machine-readable descriptor that declares Gittensory as gittensor (Bittensor subnet 74)'s contribution interface, so metagraphed — and any agent that discovers gittensor — can route discovery → Gittensory.

• src/services/subnet-interface.ts — buildSubnetInterfaceDescriptor returns:

  • subnet: { netuid: 74, name: "gittensor", home, upstreamRepo }
  • provider: { name: "Gittensory", role: "contribution_interface", site, summary }
  • interfaces.mcp: the /mcp endpoint + a curated, miner-facing tool subset (decision-pack, check-before-start, validate-linked-issue, preflight, monitor-open-prs, list-notifications, agent-plan) + version floor
  • interfaces.githubApp: install URL
  • onboarding.steps: ordered maintainer + contributor steps

  Pure product metadata (URLs, tool names) — no reward/score/private wording, so no sanitization needed. Reuses existing constants (footer URLs, MCP version, app slug, upstream repo).

• GET /v1/public/subnet-interface — added to requiresApiToken exclusions (unauthenticated), cacheable. Origin from PUBLIC_API_ORIGIN, falling back to the request origin.

Why

metagraphed surfaces gittensor as SN74 but has no machine-readable pointer to how to contribute. This descriptor is that pointer — the highest-ROI ecosystem link. metagraphed's catalog ingests it server-side; the catalog entry that makes get_subnet/how_do_i_call for SN74 return Gittensory ships separately in JSONbored/metagraphed.

Tests

• Unit: SN74 shape, origin trailing-slash normalization, curated tools (incl. gittensory_list_notifications), upstream-repo default, no-private-wording assertion.
• Integration: no-auth 200, response shape, Cache-Control, request-origin fallback when PUBLIC_API_ORIGIN unset.
• 97% coverage gate green; workers tests + git diff --check + ui:openapi:check pass.

Advances #695 (gittensory side). metagraphed catalog entry follows.

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#709 is no longer open.	No action.

---

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

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

[ghost]

gittensory · advisory review

Reviewed 4 changed file(s) — two independent AI reviewers.

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
This PR introduces a new public endpoint that returns a machine‑readable descriptor for the Gittensor (SN74) contribution interface, adds the builder function, updates routing and auth bypass, and includes unit and integration tests. The implementation is straightforward, respects the public/private sanitization rules, and the tests cover the main paths.

Suggestions

• Consider adding a small validation that origin is a valid URL scheme (http/https) to avoid malformed endpoints.
• Document the new /v1/public/subnet-interface route in the API README or OpenAPI spec for discoverability.
• Add a test case for the scenario where GITHUB_APP_SLUG is missing to ensure the endpoint fails gracefully or defaults.

Worth double-checking

• If the environment variable GITHUB_APP_SLUG is undefined, the generated install URL will contain undefined – ensure this is impossible in production.
• The new route is now whitelisted in requiresApiToken; verify that no sensitive data is ever added to this descriptor in future changes.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds a new public endpoint /v1/public/subnet-interface that serves a machine-readable descriptor declaring Gittensory as the contribution interface for Bittensor subnet 74. The descriptor contains only public metadata (URLs, tool names, onboarding steps) and avoids forbidden private context/score/private context terminology. The change includes appropriate unit and integration tests, follows existing patterns for public routes, and correctly excludes the endpoint from authentication requirements.

Suggestions

• Consider adding a comment in buildSubnetInterfaceDescriptor clarifying why the term 'scoring' in the tool summary is permissible (since it's not in the forbidden list but related to private context).
• The integration test could assert the exact cache-control header value for stronger verification, though the current substring check is acceptable.

Worth double-checking

• Verify that the tool summary containing 'scoring' does not violate the public/private boundary (though 'scoring' is not explicitly forbidden, it warrants attention given the score-related context).
• Ensure the descriptor's MCP endpoint construction (${origin}/mcp) cannot be exploited via origin manipulation (though origin is validated via environment or request origin, and no external fetching occurs).

[superagent-security]

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