feat(miner-discovery): pure opportunity-ranker in packages/gittensory-engine (#2302)

[nickmopen]

Closes #2302.

Implements the core Phase-1 miner-discovery ranker: a pure, deterministic function that composes five already-normalized [0,1] signals into one ordinal opportunity score, so a later gittensory_find_opportunities tool has something deterministic to sort by. No IO, no Date, no random — following the src/signals/duplicate-winner.ts PURE-module convention.

Deliverables (per the issue)

• packages/gittensory-engine/lib/opportunity-ranker.ts
  • OpportunityRankInput — the five 0-1 signals (potential, feasibility, laneFit, freshness, dupRisk).
  • rankOpportunityScore(input) = potential * feasibility * laneFit * freshness * (1 - dupRisk), clamping every field to [0,1] first so a malformed upstream signal (negative, >1, NaN, ±Infinity) degrades toward 0 instead of inverting the sign or overflowing the product.
  • rankOpportunities(candidates) — stable descending sort by score, annotating each with rankScore; equal scores keep input order (mirrors the tie-break intent of isDuplicateClusterWinnerByClaim, src/signals/duplicate-winner.ts:43). Returns a new array; input is not mutated.
  • Doc-comment carries the signal-source map (feasibility ← issue-quality.ts; laneFit ← MinerGoalSpec.preferredLanes; freshness/dupRisk ← reward-risk.ts + duplicate-winner.ts).

Packaging

Builds on the now-merged #2357 scaffold: adds the ranker under the package's src/ layout and exports it from the barrel. Its own node:test suite compiles to dist-test/ and runs in isolation (the validate-code job skips the package). As a member of the root packages/* workspaces glob it is registered in the root package-lock.json; broader CI build wiring remains deferred to #2297.

Validation

npm test in packages/gittensory-engine (tsc build + node --test):

ℹ tests 10
ℹ pass 10
ℹ fail 0

Covered: max inputs → 1; product composition; each of the five factors at 0 collapses to 0; dupRisk of exactly 1 zeroes; out-of-range (negative/>1) clamped not passed through; non-finite (NaN/Infinity) degrades to 0; descending sort with rankScore; stable tie-break; input not mutated; empty list → empty list. tsc is clean under strict + noUncheckedIndexedAccess + exactOptionalPropertyTypes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.80%. Comparing base (d4957ed) to head (02b784f).
⚠️ Report is 48 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2378   +/-   ##
=======================================
  Coverage   95.80%   95.80%           
=======================================
  Files         224      224           
  Lines       24970    24970           
  Branches     9075     9075           
=======================================
  Hits        23922    23922           
  Misses        428      428           
  Partials      620      620           

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-02 04:27:49 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
The change adds a pure deterministic opportunity scorer plus a stable ordered-list helper, exports it through the package barrel, and covers the formula, clamping behavior, tie handling, and non-mutation contract. The implementation matches the documented product formula and the package test setup exercises the built public entrypoint. No must-fix correctness defects are visible in the provided diff.

Nits — 5 non-blocking

• nit: packages/gittensory-engine/src/opportunity-ranker.ts:1 carries a long issue-specific header that mostly duplicates the README/API comments; keeping the source comment shorter would make the exported behavior easier to scan.
• nit: packages/gittensory-engine/test/opportunity-ranker.test.ts:99 uses JSON serialization for the immutability snapshot, which is fine for this fixture but would silently hide non-JSON fields if the sample grows.
• packages/gittensory-engine/src/opportunity-ranker.ts:24 could export or rename the clamp helpers only if future engine modules need the exact same normalization semantics; otherwise keeping them private is the right boundary.
• packages/gittensory-engine/test/opportunity-ranker.test.ts:91 add a distinct assertion that the returned element is a new object reference, since the contract says elements are not mutated and the current deep-equality snapshot only proves the source shape stayed unchanged.
• 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	✅ Linked	#2302
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 (size label size:L; 1 linked issue).
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: 97 registered-repo PR(s), 64 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 97 PR(s), 1 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: nickmopen
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript
• Official Gittensor activity: 97 PR(s), 1 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (PR #2389)
• Related work: Items reference the same linked issue feat(miner-packaging): add version/compatibility check on gittensory-miner startup #2331. (issue #2331, PR #2404)
• Related work: Open PR work references issue feat(miner-packaging): add version/compatibility check on gittensory-miner startup #2331. (issue #2331, PR #2404)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Triage stale or unlinked PRs.
• Refresh registry data or choose a registered active repo.
• 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