refactor(services): rename burden-forecast loader to reflect cache-only behavior (#8019)

[real-venus]

Summary

src/services/burden-forecast.ts's loadOrComputeBurdenForecastResponse is named "load-or-compute" and its return type declared source: "snapshot" | "computed", but the body only ever returns a stored snapshot (source: "snapshot") or null — there is no compute path. Commit f850d7a5b ("#906") deleted the inline buildBurdenForecast(...) fallback and moved it to the background buildBurdenForecasts job (src/queue/processors.ts), but left the name, the unreachable "computed" type variant, and the docs behind. src/mcp/server.ts's handler summary already says "no cached burden forecast" for the null case, confirming the cache-only reality.

Changes

• Rename loadOrComputeBurdenForecastResponse → loadCachedBurdenForecastResponse at every call site (src/mcp/server.ts, src/api/routes.ts, the definition, and the unit test).
• Drop the unreachable "computed" variant from BurdenForecastResponse.source — the loader only ever sets "snapshot" (line 28). No consumer branches on a burden-forecast .source (the two response.source === "snapshot" checks in mcp/server.ts belong to the issue-quality and repo-outcome-patterns handlers, not this one; routes.ts only passes the value through), so narrowing creates no dead branch.
• Document the real snapshot-or-null behavior and point to buildBurdenForecasts for how the cache is populated.

Scope

• Narrow, single coherent change (rename + dead-type-variant removal + doc)
• In wantedPaths (src/**, test/**); no blockedPaths
• No secrets/private-scoring terms anywhere
• No generated-artifact changes required (internal service; the type variant was never surfaced in OpenAPI as a distinct shape)

Validation

• npx vitest run test/unit/burden-forecast.test.ts — 14/14 pass (the suite already asserts source: "snapshot", which now also pins the narrowed type)
• Coverage: burden-forecast.ts 100% lines + 100% branches; both renamed call sites are covered in CI by test/integration/api.test.ts (in-process tools/call for loopover_get_burden_forecast + the /v1/repos/:owner/:repo/intelligence route)
• typecheck clean on changed files (only the 2 pre-existing local semver TS7016s remain) — the type-narrow ripples to no other type
• git diff --check clean

Safety

• Behavior-preserving: pure rename + removal of an unreachable type variant; no runtime path changes
• The two unrelated source: "computed" literals (a PR-reviewability report, a repo-status object) are on different types and are untouched
• No auth/CORS surface touched; no secrets introduced

Closes #8019

[superagent-security]

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

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-22 14:29:03 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a well-scoped rename (loadOrComputeBurdenForecastResponse → loadCachedBurdenForecastResponse) plus removal of the unreachable "computed" variant from BurdenForecastResponse.source, correctly propagated to every call site (routes.ts, mcp/server.ts) and the test file, with comments documenting the cache-only reality and pointing to buildBurdenForecasts as the actual compute path. The description's trace matches the diff: the loader in burden-forecast.ts only ever sets source: "snapshot" (confirmed by the test file's assertions on every branch), so narrowing the type is safe and no consumer branches on this field. This is exactly the kind of narrow, non-generated dead-code/naming cleanup the review guide favors.

Nits — 3 non-blocking

• The `(loadOrComputeBurdenForecastResponse can never return source: computed — the compute half was deleted in #906, the name/type/docs weren't updated #8019)` and `(fix(signals): avoid request-time burden forecast scans #906)` issue-number references embedded in the new comments (src/services/burden-forecast.ts:9,20) are fine as historical pointers but will read oddly if this code moves again; consider keeping such references in the commit/PR body only.
• Verify the file's full content wasn't given here, so the exact placement of the JSDoc block relative to other exports in burden-forecast.ts couldn't be independently confirmed — worth a quick self-check that the doc comment renders correctly for IDE tooltips.
• No functional follow-up needed; if the PR wants to be fully self-documenting, it could also update any external docs/OpenAPI description strings that still reference "load or compute" phrasing for this response, if any exist outside the diff.

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	#8019
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: 106 registered-repo PR(s), 43 merged, 17 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	real-venus; Gittensor profile; 106 PR(s), 17 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: minor

Linked issue satisfaction

Addressed
The diff renames loadOrComputeBurdenForecastResponse to loadCachedBurdenForecastResponse across all call sites (server.ts, routes.ts, tests), narrows BurdenForecastResponse.source to the single 'snapshot' literal, and updates the doc comment to describe the cache-only behavior and point to buildBurdenForecasts as the real population path, matching all stated requirements.

Review context

• Author: real-venus
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript, Python, Rust, CSS, MDX, Svelte, Swift
• Official Gittensor activity: 106 PR(s), 17 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.