feat(engine): add bestRankedOpportunityAtOrAboveScore

[kiannidev]

Summary

• Add bestRankedOpportunityAtOrAboveScore in @jsonbored/gittensory-engine — returns the highest-scoring generic ranked candidate at or above minScore, or null when none qualify.
• Thin wrapper over rankOpportunitiesAtOrAboveScore for miner discovery flows that need a single thresholded pick.
• Vitest coverage at 100% patch on the new helper.

Test plan

• COVERAGE_NO_THRESHOLDS=1 npx vitest run test/unit/ranked-opportunity-best-min-score.test.ts --coverage
• npx diff-cover coverage/lcov.info --compare-branch=main --fail-under=99 → 100%
• npm run build --workspace @jsonbored/gittensory-engine && npm run build:miner

Made with Cursor

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 05:39:19 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This adds a narrowly scoped helper that delegates to the existing thresholded ranker and returns the first survivor, which matches the stated contract because the delegated ranker already filters and sorts ranked opportunities. The barrel export is wired, and the tests cover empty input, excluded candidates, non-finite thresholds, tie order, and the public export path. I do not see a reachable correctness defect in the visible diff.

Nits — 3 non-blocking

• nit: test/unit/ranked-opportunity-best-min-score.test.ts:31 covers NaN and positive infinity but skips Number.NEGATIVE_INFINITY even though the helper documents all non-finite thresholds as null.
• test/unit/ranked-opportunity-best-min-score.test.ts:31: add Number.NEGATIVE_INFINITY to the non-finite threshold test so the documented contract is explicit for all non-finite values.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

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	❌ 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: 1334 registered-repo PR(s), 648 merged, 49 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	kiannidev; Gittensor profile; 1334 PR(s), 49 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: kiannidev
• 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: 1334 PR(s), 49 issue(s).
• Related work: Titles/paths share 10 meaningful terms. (issue #2281, issue #2276)
• Related work: Titles/paths share 8 meaningful terms. (issue #2281, issue #2287)
• Related work: Titles/paths share 8 meaningful terms. (issue #2276, issue #2287)

Contributor next steps

• Explain no-issue PR.
• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• 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.46%. Comparing base (25347c4) to head (10925eb).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3377   +/-   ##
=======================================
  Coverage   93.46%   93.46%           
=======================================
  Files         286      287    +1     
  Lines       30761    30763    +2     
  Branches    11209    11210    +1     
=======================================
+ Hits        28750    28752    +2     
  Misses       1355     1355           
  Partials      656      656           

Files with missing lines	Coverage Δ
...ry-engine/src/ranked-opportunity-best-min-score.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.