feat(settings): add a read-only DB/config settings-drift diagnostic

[JSONbored]

Summary

• Adds computeSettingsDrift (src/settings/settings-drift.ts): a pure diff between a repo's DB-stored repository_settings row and the LIVE effective settings resolveEffectiveSettings would actually apply for it. Every entry names a DB-stored field whose value is silently shadowed by a .gittensory.yml config-as-code override — useful for a self-host operator who changed something via the dashboard and can't tell why it isn't taking effect. Confirmed via direct investigation that no such drift-detection exists anywhere in the codebase today (no drift/shadow/precedence comparison logic beyond the one-way { ...dbSettings, ...manifest.settings } overlay itself).
• Compares against a "no manifest" baseline rather than the raw DB row, because resolveEffectiveSettings also applies manifest-independent normalization (the shared/global contributor-blacklist merge, in particular) that would otherwise misreport as "shadowed by private config" for every repo with any global blacklist entry, even one with no manifest at all — verified this with a dedicated test.
• computeSettingsDriftForRepo wires the pure function to the same DB + manifest reads settings/repository-settings.ts's resolveRepositorySettings already makes, so it's immediately callable with a real Env — no new data-fetch path introduced.
• Scope note: this never touches the live resolve/review path — it's a pure, read-only diagnostic. A human-facing entry point (an MCP tool, dashboard route, or CLI script) needs its own auth/live-data-access wiring (a script would need to reconstruct self-host's DB connection + GitHub credentials outside the running service; an MCP tool needs the existing maintainer-auth/allowlist machinery) — investigated both and neither is a small addition, so it's intentionally left as a focused follow-up rather than bolted onto this PR half-verified. The correctness-critical diff logic (this PR) is the part that most needs to be right and well-tested before anything is built on top of it.
• No issue filed — this was one item in a small repo-policy config audit; happy to open a tracking issue for the entry-point follow-up if useful.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run typecheck (clean)
• npx vitest run test/unit/settings-drift.test.ts (12/12 passing)
• npx vitest run test/unit/focus-manifest.test.ts test/unit/selftune-readback.test.ts (regression check on the shared resolveEffectiveSettings/manifest-loader/DB-repositories dependencies — 263/263 passing, no changes needed)
• Scoped coverage check (vitest --coverage --coverage.include=src/settings/settings-drift.ts): 100% statements/branches/functions/lines on the new file.
• npm run test:workers / npm run build:mcp / npm run test:mcp-pack / npm run ui:openapi:check / npm run ui:build — not run individually this PR; no worker/MCP/OpenAPI/UI surface touched (no new route, no new MCP tool, no schema change). Ran the full npm run test:ci gate once already this session (PR fix(settings): authorize circuit-breaker hold labels via merge/close autonomy #3363, same branch point) with no relevant failures.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — covers: no drift, scalar/array/object-valued drift, a gate:-sourced vs settings:-sourced override both detected, a field the manifest never touches staying unreported, the global-blacklist-merge false-positive specifically guarded against, and the live DB+manifest fetch path including its catch(() => []) fallback.

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. (This is an internal diagnostic function, never posted to GitHub.)
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — N/A, no auth/session/CORS change; no new entry point (see Scope note above).
• API/OpenAPI/MCP behavior is updated and tested where needed. — N/A, no API/OpenAPI/MCP surface added in this PR.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — N/A, no UI change.
• Visible UI changes include a UI Evidence section below. — N/A, no visible UI change.
• Public docs/changelogs are updated where needed. — N/A, no user-facing behavior yet (no entry point); will document alongside whichever follow-up adds one.

Notes

• PR 4 of a small sequence auditing repo-policy config consistency (see PR fix(settings): authorize circuit-breaker hold labels via merge/close autonomy #3363, fix(selfhost): recognize repoDocGeneration in the config-lint allowlist #3364, feat(settings): distinguish assign-fallback outcome in audit_events #3366 for PRs 1-3).

[superagent-security]

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-05 05:22:00 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
The PR adds a narrow read-only diagnostic that compares the no-manifest effective settings baseline against the manifest-resolved effective settings, with focused unit coverage for settings, gate aliases, sparse objects, arrays, and the live DB/manifest fetch path. The important layering choice is correct: comparing through `resolveEffectiveSettings` avoids false positives from resolver-owned normalization such as shared contributor list merging. I do not see a reachable correctness break in the visible change.

Nits — 4 non-blocking

• nit: `src/settings/settings-drift.ts:20` says the local `stableStringify` is for "order-independent-equality", but arrays remain order-sensitive, so either tighten the comment or explicitly document that only object key order is normalized.
• nit: `src/settings/settings-drift.ts:59` silently swallows `getGlobalContributorBlacklist` failures; that matches the added test, but diagnostic callers lose the difference between "no shared entries" and "shared read failed", so consider returning warning metadata if this becomes user-facing.
• `src/settings/settings-drift.ts:20` should change the helper comment to "stable object-key equality" or similar so future readers do not assume array/set normalization exists.
• `src/settings/settings-drift.ts:55` can stay read-only, but when wiring a CLI/MCP/dashboard entry point later, surface the shared-list fallback as a diagnostic warning rather than only returning the shortened drift list.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 56 registered-repo PR(s), 46 merged, 416 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 56 PR(s), 416 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 56 PR(s), 416 issue(s).
• Related work: Titles/paths share 7 meaningful terms. (issue #2048, issue #2051)
• Related work: Titles/paths share 8 meaningful terms. (issue #2038, issue #2051)
• Related work: Titles/paths share 7 meaningful terms. (issue #2049, issue #2051)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Review top overlaps.
• Add a concise scope and risk note.
• No action.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.
• Check active issues and PRs before submitting.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.89%. Comparing base (1afb2ed) to head (90cdab6).
⚠️ Report is 4 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3369   +/-   ##
=======================================
  Coverage   93.88%   93.89%           
=======================================
  Files         282      283    +1     
  Lines       30570    30586   +16     
  Branches    11136    11139    +3     
=======================================
+ Hits        28702    28718   +16     
  Misses       1211     1211           
  Partials      657      657           

Files with missing lines	Coverage Δ
src/settings/settings-drift.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[loopover-orb]

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