fix(api): align the telemetry-ingest routes' published statuses with their handlers

[shin-core]

What & why

Closes #9708.

The two near-identical telemetry-ingest routes' published operations disagreed with their handlers
and with each other:

• POST /v1/ams/ingest declared a 202 its handler never returns (the real success status is 200)
  and omitted 413.
• POST /v1/orb/ingest was a legacy registerPath block declaring only 200/400 with no
  security stanza at all — publishing an unauthenticated write endpoint that actually carries its
  own ORB_INGEST_TOKEN bearer and can return 401/403/413.

Change

• /v1/ams/ingest now declares 200 (not the unreachable 202), plus 413 for the
  readOrbIngestBody 1 MiB (MAX_ORB_INGEST_BODY_BYTES) body ceiling.
• /v1/orb/ingest moves from the spec.ts registerPath block to a SpecEntry in
  internal-and-public-route-specs.ts with auth: "orb" (which derives the OrbBearer security
  stanza) and responses 200, 400, 401, 403, 413.
• openapi.json regenerated; security: [{ "OrbBearer": [] }] now present on /v1/orb/ingest.

Validation

• New test/unit/openapi-ingest-status-parity.test.ts: for both routes, no bearer → 401, an
  oversized content-length → 413, and a valid authenticated batch → 200; and each of those
  statuses (plus, for orb, the OrbBearer security and 403) is declared in buildOpenApiSpec().
• test/unit/route-spec-ratchet.test.ts still passes in both directions.
• Bug-catch verified: reverting the AMS spec to 202 fails the status-parity assertion.
• 100% patch coverage on the new SpecEntry; ui:openapi:check drift-check clean.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-29 06:12:40 UTC}

4 files · 1 AI reviewer · no blockers · CI green · unstable

⏸️ Suggested Action - Manual Review

• Required AI review was skipped by a submitter-reputation downgrade: This repository requires blocking AI review, and the submitter's recent-submission signal downgraded this PR to deterministic-only checks. Those checks do not read code semantics, so the gate is held for human review instead of passing automatically.

Review summary
This PR aligns published OpenAPI statuses with actual handler behavior for two telemetry-ingest routes: /v1/ams/ingest now declares 200 (not the unreachable 202) plus 413 for the body-size ceiling, and /v1/orb/ingest is migrated from a legacy registerPath block with no security stanza to a SpecEntry with auth: "orb", correctly deriving the OrbBearer security requirement and adding 401/403/413. The change is narrow, well-targeted, and includes a genuine parity test that exercises both routes end-to-end (no-auth->401, oversized body->413, valid batch->200) plus a spec-level assertion that the declared responses match, with a documented negative-control (reverting AMS to 202 fails the test). The openapi.json diff mirrors the spec.ts changes correctly for both paths.

Nits — 6 non-blocking

• src/openapi/internal-and-public-route-specs.ts: the AMS route's `auth: "orb"` reuses the ORB shared-secret derivation via a comment rather than a distinct auth level — worth confirming AMS_INGEST_TOKEN and ORB_INGEST_TOKEN are genuinely handled by the same auth path in define-route.ts, since they're different env vars per the test file's tokenEnv distinction.
• test/unit/openapi-ingest-status-parity.test.ts: the two per-route auth-token headers are hardcoded to the same 'fleet-secret' bearer value for both AMS and ORB tests even though they use different tokenEnv names, which works only because createTestEnv sets whichever token that specific test needs — a minor readability point, not a bug.
• No changelog/migration note for the openapi.json security addition on /v1/orb/ingest, though this is a docs-only surface change so likely fine to skip.
• Consider a brief code comment in internal-and-public-route-specs.ts noting that AMS and ORB ingest share `auth: "orb"` intentionally despite having separate token env vars, to preempt future confusion for someone splitting them into distinct auth levels.
• The FAILED 'Contributor trust' check is unrelated to this diff's content; likely tied to contributor flagging process rather than a code defect.
• Required AI review was skipped by a submitter-reputation downgrade — Review this PR manually, or run AI review with a trusted override, before merging.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ⚠️ Gate result — Not blocking (Advisory; not blocking this PR.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9708
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	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 38 registered-repo PR(s), 26 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	shin-core; Gittensor profile; 38 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Linked issue satisfaction

Addressed
The diff moves /v1/orb/ingest into internal-and-public-route-specs.ts as a SpecEntry with auth: "orb" and 200/400/401/403/413 responses, removes the legacy registerPath block from spec.ts, fixes /v1/ams/ingest to declare 200 (not 202) plus 413, regenerates openapi.json with the OrbBearer security stanza, and adds the required status-parity test covering both routes' 401/413/200 behavior against th

Review context

• Author: shin-core
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is registered but has no active allocation in the current snapshot.
• Public profile languages: not available
• Official Gittensor activity: 38 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Await review-lane availability.
• Then work through the remaining 2 steps in the Signals table above.

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.

Decision record

• action: hold · clause: ai_review_inconclusive
• config: bf17a4551a8096754e18a48accbf69c417a52c5a3588f868c0e6a74b6d09a8ff · pack: oss-anti-slop · ci: passed
• record: 1ae0c4b6f9497669b71c5890b2672a97a88f3ef1ace5ea7c9ebda6f15a10f356 (schema v5, head fb2d11e)

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop	before /	after /	—
/	mobile	before / (mobile)	after / (mobile)	—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

Scroll preview

Route	Before (production)	After (this PR's preview)
/	before / (scroll)	after / (scroll)

A short scroll-through clip (desktop) — click either thumbnail to open the full animation. Evidence for scroll-linked behavior a single screenshot can't show.

_{🟩 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

[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 76.70%. Comparing base (a9ac8a7) to head (fb2d11e).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9751      +/-   ##
==========================================
+ Coverage   76.58%   76.70%   +0.11%     
==========================================
  Files         282      284       +2     
  Lines       59419    59729     +310     
  Branches     6553     6559       +6     
==========================================
+ Hits        45508    45816     +308     
  Misses      13629    13629              
- Partials      282      284       +2     

Flag	Coverage Δ
backend	99.35% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/openapi/internal-and-public-route-specs.ts	100.00% <ø> (ø)
src/openapi/spec.ts	99.30% <ø> (ø)