Skip to content

openapi: /v1/scoring/eligibility-plan + /v1/scoring/explain-breakdown missing from spec (MCP tools + schemas already exist) #9301

Description

@JSONbored

⚠️ Definition of Done: this issue must be completed in full, in a single PR. Do not split this
work across multiple PRs, and do not defer any Deliverable below to a follow-up issue. A PR that
satisfies only some of the Deliverables, stubs a required test, or leaves a checkbox
partially-done does NOT resolve this issue and will be closed.

⚠️ Required pattern: mirror how GET /v1/repos/{owner}/{repo}/gate-config/effective is documented
in src/openapi/spec.ts (schema registered via registry.register(...), then attached to a
registry.registerPath({ path, method, ... }) call) — issue #6611 fixed the exact same class of gap
for that route.

Context

src/api/routes.ts has two live, tested /v1/scoring/* POST routes, each already backed by an MCP
tool with its own Zod output shape in src/mcp/server.ts:

  • POST /v1/scoring/eligibility-planloopover_get_eligibility_plan (outputSchema: eligibilityPlanOutputSchema)
  • POST /v1/scoring/explain-breakdownloopover_explain_score_breakdown (outputSchema: scoreBreakdownOutputSchema)

Neither route appears anywhere in src/openapi/spec.ts — grep for "/v1/scoring/eligibility-plan"
and "/v1/scoring/explain-breakdown" in that file returns nothing, and neither route is reachable
from the generated apps/loopover-ui/public/openapi.json. Their sibling /v1/scoring/* routes
(/v1/scoring/model, /v1/scoring/preview) ARE documented. This is the same class of gap #6611
fixed for /v1/repos/{owner}/{repo}/gate-config/effective ("OpenAPI spec is missing GET
.../gate-config/effective (documented sibling: live-gate-thresholds)").

Requirements

  • In src/openapi/schemas.ts, define EligibilityPlanResponseSchema and
    ScoreBreakdownResponseSchema as z.object({...}) Zod schemas matching the actual response shape
    — use eligibilityPlanOutputSchema and scoreBreakdownOutputSchema (the raw Zod-shape objects
    already validated in src/mcp/server.ts for this exact data) as the source of truth for field
    names/types, not a fresh guess at the shape.
  • In src/openapi/spec.ts, registry.register(...) both new schemas as components, then add a
    registry.registerPath({...}) entry for each route (POST /v1/scoring/eligibility-plan,
    POST /v1/scoring/explain-breakdown), following the existing pattern used for
    /v1/repos/{owner}/{repo}/gate-config/effective (request body schema + 200 response schema +
    appropriate error responses).
  • Schema is the contract — regenerate and commit the generated artifact. After editing
    src/openapi/schemas.ts/src/openapi/spec.ts, run npm run ui:openapi (this repo's build command
    for this artifact — scripts/write-ui-openapi.ts) to regenerate apps/loopover-ui/public/openapi.json,
    and commit the regenerated file in this same PR. CI enforces this via npm run ui:openapi:check
    (part of npm run test:ci) — a stale openapi.json fails CI.

Deliverables

  • EligibilityPlanResponseSchema and ScoreBreakdownResponseSchema added to
    src/openapi/schemas.ts, matching the MCP tools' existing output shapes field-for-field.
  • Both routes registered as OpenAPI paths in src/openapi/spec.ts.
  • apps/loopover-ui/public/openapi.json regenerated via npm run ui:openapi and committed.
  • npm run ui:openapi:check passes in CI.

All deliverables are required in this one PR — there is no follow-up issue.

Test Coverage Requirements

99%+ Codecov patch target (codecov/patch, unsharded via npm run test:coverage) on any new schema
helper code. Add a regression test (or extend an existing OpenAPI-spec snapshot/shape test) asserting
both new paths are present in buildOpenApiSpec()'s output with the correct method and a response
schema whose keys match eligibilityPlanOutputSchema/scoreBreakdownOutputSchema.

Expected Outcome

GET /openapi.json (and the committed apps/loopover-ui/public/openapi.json) documents both
scoring routes, matching what their MCP tool counterparts already validate — closing the drift
between "this data contract is already enforced by the MCP tool" and "this data contract is
discoverable via the public API spec."

Links & Resources

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:bugGittensor-scored bug fix — scores a 0.05x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions