feat(miner-portfolio): add pure non-convergence detector to gittensory-engine

[dhgoal]

Adds a pure non-convergence DETECTOR to the engine (Closes #4286).

New packages/gittensory-engine/src/portfolio/non-convergence.ts: a pure classifier over one portfolio-queue item's attempt/outcome counts — classifyPortfolioConvergence(input, thresholds) returning { status, reasons } where status is converging | stalled | non_convergent.

Rules (mirroring the pure-classifier discipline of contributor-fit.ts):

• Zero attempts ⇒ converging — a first attempt is not evidence of a stuck loop (the same non-judgment-on-absence rule contributor-fit.ts uses).
• Reached done ⇒ converging by definition.
• A single failure or re-enqueue (below threshold) ⇒ stalled, never non-convergent.
• A sustained streak — consecutiveFailures or reenqueues at/above its threshold ⇒ non_convergent (the observable "cycling queued→in_progress→queued without reaching done" from portfolio-queue.js:108-115).

DETECTOR only — no IO, no Date.now(), no randomness, no enforcement, no write-blocking. It produces one input signal; the fail-closed Governor chokepoint that composes it (rate-limit + budget caps + this) is separate, maintainer-owned work tracked in #2340. Re-exported from src/index.ts alongside ./portfolio/queue.js.

Test

test/portfolio-non-convergence.test.ts — zero history, one failure (stalled), single re-enqueue (stalled), a converging/improving streak, reached-done, a consecutive-failure streak past threshold, a re-enqueue streak past threshold, both streaks (two reasons), and configurable thresholds. Full engine suite: 284 pass; test:engine-parity green.

• Conventional Commit; focused; Closes feat(miner-portfolio): non-convergence DETECTOR (pure signal, no enforcement) #4286. No site//CNAME/**/lovable/**; no CHANGELOG.md. New engine module + test + one entrypoint re-export.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[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-09 17:20:14 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a small, pure classifier (classifyPortfolioConvergence) over caller-supplied attempt/outcome counts, returning converging/stalled/non_convergent based on consecutive-failure and re-enqueue streak thresholds, and re-exports it from the engine barrel. The logic is correct and matches its own tests: zero attempts and reached-done short-circuit to converging, either streak at/above threshold yields non_convergent with per-cause reasons, and a below-threshold single failure/re-enqueue yields stalled — every branch (including the OR arms in the streak check and the stalled fallback) has a dedicated test. It's a detector only (no IO, no enforcement) with no caller wiring yet, consistent with the PR's stated scope of feeding a separate, not-yet-built Governor chokepoint (#2340).

Nits — 5 non-blocking

• non-convergence.ts: when attempts<=0 but reachedDone is somehow true, the function returns the 'first attempt' reason instead of 'reached done' since the attempts<=0 check runs first — cosmetic only since both paths return converging, but worth a comment or reordering for clarity.
• The new module has no caller wiring in this diff (only the barrel re-export) — confirm this is intentionally deferred to the Governor composition work in maintainer: wire the fail-closed Governor chokepoint before every write action #2340 rather than dead code left unconsumed.
• Tests import from '../dist/index.js' rather than '../src/index.ts', so a stale dist/ build could let a regression in non-convergence.ts pass CI silently — confirm this matches the existing test convention for other portfolio modules.
• Consider validating that thresholds passed in are >=1 (a 0 threshold would make even a single failure/re-enqueue non_convergent, bypassing the 'stalled' path) — not a bug today since DEFAULT is 3, but worth a guard or doc note given thresholds are caller-configurable.
• The header comment cites packages/gittensory-miner/lib/portfolio-queue.js:108-115 as the source of the re-enqueue behavior being modeled — worth double-checking that reference still matches current queue code so the classifier's semantics don't drift from the real re-enqueue path.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

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

Linked issue satisfaction

Addressed
The diff adds packages/gittensory-engine/src/portfolio/non-convergence.ts with a pure classifyPortfolioConvergence(input, thresholds) function returning {status, reasons}, correctly treats zero attempts and a single failure/re-enqueue as non-punitive (converging/stalled), only flags non_convergent on sustained streaks past threshold, is IO/Date/random-free, is re-exported from src/index.ts alongsi

Review context

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

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (Contributor trust)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.

[loopover-orb]

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