fix(scoring): clamp fixed_base_score and SRC_TOK_SATURATION_SCALE to documented bounds

[joaovictor91123]

Summary

Fixes #1744.

computeScoreCore (src/scoring/preview.ts) consumed two repo-configurable scoring inputs without enforcing the ranges upstream documents for them, so an out-of-range value silently distorted the preview:

• fixed_base_score forces base_score to a constant documented as [0, 100], but reached the preview unbounded above — src/api/routes.ts:567 validates it as z.number().min(0) (no max) and src/registry/normalize.ts:73 accepts any finite value. A misconfigured fixed_base_score: 150 previewed baseScore = 150, a base component above the model ceiling that then multiplied through to estimatedMergedScore.
• SRC_TOK_SATURATION_SCALE is per-repo overridable only within [10, 500] (default 58), but saturationScore only floored it at 1, so an out-of-band snapshot value distorted the saturation curve.

This clamps both inputs to their documented ranges at the scoring boundary (clampFixedBaseScore → [0, 100], clampSaturationScale → [10, 500]). A non-finite/absent fixed_base_score still falls through to the token-derived base score, and in-range values (e.g. 12, 58) are unchanged — so existing previews are unaffected.

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 actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥97% coverage of the lines AND branches you changed (aim for 98%+ on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Ran the full npm run test:ci (green) plus npm audit --audit-level=moderate (0 vulnerabilities). Added four regression tests in test/unit/scoring.test.ts covering the [0,100] clamp (above-ceiling and below-floor) and the [10,500] saturation-scale clamp (below-floor and above-ceiling); each fails before the fix.

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.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with screenshots.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

No auth/CORS/session/OpenAPI/UI changes: this is a backend-only clamp on values the preview already consumed (the public OpenAPI spec is unchanged; ui:openapi:check passes). No UI evidence is applicable.

Notes

• The clamp is intentionally applied at the scoring boundary so it covers both the API input (input.fixedBaseScore) and the registry-config (config.fixedBaseScore) sources without changing the registry normalization or API schema contracts.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-06-29 21:40:50 UTC}

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

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review

Review summary
The change clamps the two repo-configurable preview inputs at the scoring boundary and keeps absent or non-finite fixed-base overrides on the derived path, which matches the documented behavior described in the PR. The fixed-base change is localized before the existing base-score branch, and the saturation-scale change replaces the old divide-by-zero guard with the documented finite range. The added tests cover both upper and lower clamp behavior for these changed branches, so the visible diff is safe to proceed.

Nits — 5 non-blocking

• nit: test/unit/scoring.test.ts:1873 labels the negative fixedBaseScore case as the API input path, but the PR description says the API schema already rejects negatives, so the test name should describe this as direct preview-input hardening or exercise a real producer path.
• test/unit/scoring.test.ts:1873: rename the negative fixedBaseScore test to avoid implying API reachability, or move that case through the registry/config path if that is the producer you intend to cover.
• src/scoring/preview.ts:1296: consider adding a short unit assertion for non-finite fixedBaseScore falling through to the token-derived base score, since the helper explicitly preserves that contract.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#1744
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 (size label size:S; 1 linked issue).
Validation posture	❌ 5/25	Preflight is holding this PR; address the blocker before review.
Contributor workload	✅ 10/10	Author activity: 37 registered-repo PR(s), 19 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 37 PR(s), 0 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: joaovictor91123
• Role context: outside_contributor
• 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: 37 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Fix the blocker.
• Triage stale or unlinked PRs.
• Refresh registry data or choose a registered active repo.

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 95.59%. Comparing base (ce1d354) to head (89d5558).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1745   +/-   ##
=======================================
  Coverage   95.59%   95.59%           
=======================================
  Files         204      204           
  Lines       22316    22322    +6     
  Branches     8067     8068    +1     
=======================================
+ Hits        21332    21338    +6     
  Misses        408      408           
  Partials      576      576           

Files with missing lines	Coverage Δ
src/scoring/preview.ts	99.07% <100.00%> (+0.01%)	⬆️

🚀 New features to boost your workflow:

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