fix(review): cache grounding's full-file-content fetch by (repo, path, head SHA)

[JSONbored]

Closes #4499.

Summary

• makeGithubFileFetcher (src/review/grounding-wire.ts) re-fetched every changed file's full post-change body from GitHub on every invocation with zero cache/memoization. Grounding is a dynamic feature (bypasses the durable ai_review result cache), so the only throttle was the 30-minute AI_REVIEW_NON_CACHEABLE_RETRY_COOLDOWN_MS cooldown — after which, or on any non-push webhook event (review comments, review submissions, thread resolutions — none of which change the head SHA), the full multi-file re-fetch repeated from scratch.
• Adds grounding_file_content_cache (migration 0130), keyed by (repo_full_name, path, head_sha) — deliberately without a pull number, unlike linked_issue_satisfaction_cache: file content at an immutable git commit is universal, not PR-specific, so two PRs that happen to share a (repo, path, head_sha) triple (e.g. a cherry-pick) correctly share one cached row.
• Only a genuinely successful fetch is cached — a transient network/timeout failure stays retryable rather than being treated as a confirmed-permanent (binary/oversized/inaccessible) condition. The existing oversized-file placeholder is cached too, since it's a deterministic function of the file at that commit.
• GITTENSORY_REVIEW_GROUNDING defaults off on hosted, on in .env.selfhost.example — self-host deployments are the population most exposed to this bug.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• Owner PR resolving a maintainer-tracked issue (fix(review): grounding re-fetches every changed file's full body every 30 min with zero caching #4499); no additional linked-issue-eligibility concern applies.

Validation

• npm run typecheck
• npm run db:migrations:check / npm run db:schema-drift:check (both clean, re-verified after rebase)
• New tests added and empirically verified to FAIL without the fix (temporarily reverted grounding-wire.ts locally): a repeat-call invariant test (2 fetches → 1) and a regression test reproducing the exact incident shape (5 cooldown-driven passes on an unchanged head → 5 fetches without the fix, 1 with it). Also added negative-path coverage: a genuinely new head SHA still fetches fresh, and a failed fetch is never cached (stays retryable).
• npx vitest run test/unit/grounding-wiring.test.ts test/unit/review-grounding.test.ts test/unit/impact-map-grounding.test.ts test/unit/queue.test.ts (830 passed)

If any required check was skipped, explain why:

• Full npm run test:coverage not re-run unsharded locally; this is an additive change (new table + one function's internal caching, no shared-interface changes) with a broad targeted run already covering grounding + the full queue integration suite. Relying on CI for the full gate.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• N/A — no auth/cookie/CORS/GitHub App/Cloudflare/session changes.
• N/A — no API/OpenAPI/MCP behavior changed (no route/schema touched).
• N/A — no UI changes.

[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 94.04%. Comparing base (95e9ec6) to head (f1f6d68).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4538   +/-   ##
=======================================
  Coverage   94.04%   94.04%           
=======================================
  Files         422      422           
  Lines       37600    37609    +9     
  Branches    13736    13740    +4     
=======================================
+ Hits        35362    35371    +9     
  Misses       1583     1583           
  Partials      655      655           

Files with missing lines	Coverage Δ
src/db/repositories.ts	96.73% <100.00%> (+<0.01%)	⬆️
src/db/schema.ts	72.43% <100.00%> (+0.30%)	⬆️
src/review/grounding-wire.ts	96.47% <100.00%> (+0.08%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-10 00:11:21 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a durable (repo, path, head_sha) cache for grounding's full-file-content GitHub fetch, correctly keyed without a pull number since blob content at an immutable SHA is universal. The cache-read happens before the network call and only a genuinely successful fetch (or the deterministic oversized-placeholder) is written back via ON CONFLICT upsert; non-OK responses and thrown exceptions return early and bypass the write, keeping transient failures retryable. Schema, migration (D1-safe, no temp/PRAGMA/ATTACH), and repository bind-order all line up correctly, and the new tests exercise the hit/miss/new-SHA/failed-fetch paths against the real code path.

Nits — 6 non-blocking

• migrations/0130_grounding_file_content_cache.sql:14 uses a static `DEFAULT CURRENT_TIMESTAMP`, but repositories.ts always supplies `fetched_at` explicitly via `nowIso()` on insert, so the SQL default is dead code — harmless here since every write is explicit, but worth aligning with the `$defaultFn(() => nowIso())`-only convention if a future writer ever omits the column.
• codecov/patch is failing at 71.42% vs a 99% target — the untested branches look like the nullish/no-op arms in src/db/repositories.ts (`if (!headSha) return null;` / `if (!headSha) return;`) and the `.catch(() => null)` / `.catch(() => undefined)` fallback paths in grounding-wire.ts when the cache read/write itself throws.
• src/review/grounding-wire.ts: `let content: string | null` is only ever assigned a non-null string via the ternary before the `content !== null` check, so that guard is either dead or silently relying on an unseen null return from `readTextWithLimit` — worth a comment or test making clear which case it actually guards against.
• Add a direct unit test for `getCachedGroundingFileContent`/`putCachedGroundingFileContent` in src/db/repositories.ts covering a null/undefined `headSha` no-op, to close the coverage gap flagged by codecov/patch.
• Add a test where the cache read itself throws (DB error) to confirm the `.catch(() => null)` fallback still falls through to a fresh GitHub fetch rather than silently failing.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4499
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: 48 registered-repo PR(s), 40 merged, 363 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 48 PR(s), 363 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds a durable grounding_file_content_cache keyed exactly by (repo_full_name, path, head_sha), wires getFileContent to check it before any GitHub call and only writes back genuinely successful fetches, and includes the required invariant, regression (repeated non-push webhook calls on an unchanged head), and negative-path (new head SHA re-fetches) tests plus extra edge-case coverage for cac

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 48 PR(s), 363 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

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.

_{🟩 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 Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review