fix(openapi): declare 503 on the BYOK key setters and drop the unreachable GET 404

[shin-core]

What & why

The four BYOK key-write routes (POST public + internal ai-key/linear-key) catch missing_encryption_secret and answer 503 encryption_unavailable when TOKEN_ENCRYPTION_SECRET is unconfigured — but their spec entries never declared 503, so a generated client had no schema for the one failure a maintainer actually hits.

Conversely, the two public key GETs declared a 404 they can never return: the handler answers 200 { configured: false } for an unregistered repo, never a 404.

The fix

In the per-kind flatMap in src/openapi/orb-and-control-route-specs.ts — the single place all four key routes are generated, so ai-key and linear-key can't drift:

• add 503 (encryption_unavailable — TOKEN_ENCRYPTION_SECRET is not configured) to the public and internal setters, matching the 503 description style used for POST /v1/internal/provider-credentials/{provider};
• remove the unreachable 404 from the public getter.

No handler behaviour changes. apps/loopover-ui/public/openapi.json regenerated.

Tests (test/unit/routes-ai-byok.test.ts)

• POST /v1/repos/:owner/:repo/ai-key with no secret answers 503 { error: "encryption_unavailable" } and buildOpenApiSpec() declares 503 for that operation (fails on main).
• The same for POST /v1/internal/repos/:owner/:repo/linear-key (fails on main).
• GET /v1/repos/:owner/:repo/ai-key for a repo with no key answers 200 { configured: false }, and the spec's GET no longer declares 404 — proving the removed 404 was unreachable (fails on main).

Validation

• npm run typecheck green; npm run ui:openapi:check clean; the byok, openapi, route-spec-ratchet, and security-parity suites all green.
• Diff coverage on the changed spec file is 100%.
• git diff --check <base> HEAD clean; diff is the spec source + its test + the regenerated openapi.json; no handler or lockfile change.

Closes #9709

[superagent-security]

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

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-29 11:34:52 UTC}

3 files · 1 AI reviewer · no blockers · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This PR adds a `503 encryption_unavailable` response to the four BYOK key-setter routes (public/internal ai-key and linear-key) and removes the unreachable `404` from the two public key GETs, all centralized in the single `flatMap` in `src/openapi/orb-and-control-route-specs.ts`. The regenerated `openapi.json` diff matches the source change exactly (503 added to the three POST setters shown, 404 removed from the GETs), and the new tests directly exercise both the runtime 503/200 behavior and the spec's declared responses. The change is narrow, well-scoped to the linked issue (#9709), and the tests genuinely drive the real handler path rather than fabricating an unreachable scenario.

Nits — 4 non-blocking

• The `openapi.json` diff only shows 3 added 503 blocks (two public/internal ai-key/linear-key POSTs plus one more), but the PR claims all four setters gain 503 — worth double-checking the diff covers all four operations (get/set for both kinds × public/internal) rather than only three, since the source flatMap change is symmetric but the JSON diff hunks are easy to miscount.
• The inline comments added in orb-and-control-route-specs.ts (`// No 404 (api(byok): key-write routes return an undeclared 503; the GETs declare an unreachable 404 #9709)...`, `// 503 (api(byok): key-write routes return an undeclared 503; the GETs declare an unreachable 404 #9709)...`) are helpful context but slightly redundant with the PR description; not a real issue, just a style note.
• Consider adding a short assertion in the route-spec-ratchet or a dedicated meta-test that the 503 response is present for the internal linear-key GET/DELETE-adjacent setter path too, to lock in symmetry across all four kind×scope combinations as the code evolves.
• apps/loopover-ui/public/openapi.json is a large generated file; no action needed here since it's the expected regenerated artifact, but confirm `ui:openapi:check` remains part of CI going forward to keep this file from drifting again.

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	#9709
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: 63 registered-repo PR(s), 46 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	shin-core; Gittensor profile; 63 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: minor

Linked issue satisfaction

Addressed
The diff adds 503 to the flatMap-generated setAiKey/setLinearKey/setAiKeyInternal/setLinearKeyInternal spec entries, removes the unreachable 404 from the GET entries, regenerates openapi.json, and extends the existing test file with the required 503 and 200/no-404 assertions exactly as specified. It preserves the shared flatMap table (no unrolling) and does not alter handler behavior, matching all

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: TypeScript, JavaScript, Solidity, Dart, Python, CSS, PHP, Rust
• Official Gittensor activity: 63 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Await review-lane availability.
• Then work through the remaining 1 step 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.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.03%. Comparing base (55b6a82) to head (fdd76c4).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9819   +/-   ##
=======================================
  Coverage   79.03%   79.03%           
=======================================
  Files         280      281    +1     
  Lines       58366    58379   +13     
  Branches     6697     6699    +2     
=======================================
+ Hits        46128    46141   +13     
  Misses      11955    11955           
  Partials      283      283           

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

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

Files with missing lines	Coverage Δ
src/openapi/orb-and-control-route-specs.ts	100.00% <ø> (ø)

[loopover-orb]

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