feat(miner-governor): local rate-limit token-bucket + jittered-backoff calculator (pure)

[GildardoDev]

Summary

Adds the Governor's pure rate-limit + jittered-backoff math to the shared engine package as packages/gittensory-engine/src/governor/rate-limit.ts. Given a rolling-window bucket and a clock reading it decides whether an event is allowed and, when blocked, how long to wait; and it computes a jittered exponential backoff from an injected random source. It computes numbers only — no storage, no scheduling, and it does not itself gate any write action (that enforcement wiring is a separate, maintainer-owned concern).

Closes #2327

Deliverables

• LocalRateBucket / LocalRateLimitConfig / LocalRateLimitDecision types, and evaluateLocalRateLimit(bucket, config, nowMs) returning { allowed, remaining, resetAtMs, retryAfterMs }. A fully elapsed window is treated as reset, so a stale bucket at its limit is permitted again in the new window.
• jitteredBackoffMs(baseMs, attempt, randomFn) — exponential base baseMs * 2 ** attempt scaled by a multiplicative jitter factor in the band [0.5, 1.5) drawn from an injected randomFn (never Math.random(), so tests stay deterministic). The attempt is clamped non-negative and bounded so it cannot overflow to Infinity, and an out-of-contract random draw is clamped into the band.
• The vocabulary mirrors the server-side RateLimitConfig / RateLimitDecision in src/auth/rate-limit.ts (that one is a Cloudflare Durable Object and is not reusable in the fully-local miner); this variant is millisecond-based and state-free.
• A doc comment stating explicitly that the module computes numbers only and gates nothing.
• Exported from the package barrel (packages/gittensory-engine/src/index.ts).

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• Focused and additive: one new pure module, its test, and a one-line barrel export. No unrelated changes.
• Follows CONTRIBUTING.md; stays inside packages/gittensory-engine/ and does not touch site/, CNAME, or removed tooling.
• Linked issue feat(miner-governor): local rate-limit token-bucket + jittered-backoff calculator (pure) #2327.

Validation

• Unit tests (14) cover: under-limit passes, at-limit blocks with retry timing, elapsed-window reset, sub-window boundary, negative/over-limit stored counts; backoff at attempt 0 and growth, the [0.5, 1.5) jitter band across a swept attempt range, negative/fractional attempt clamping, the exponent cap against overflow, a negative base, and out-of-contract random clamping.
• npm run build --workspace @jsonbored/gittensory-engine succeeds.
• Tests run green under the root Vitest suite (test/unit/governor-rate-limit.test.ts).

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-02 05:14:15 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This PR adds the requested pure local rate-limit decision helper and deterministic jittered backoff utility, exports them from the engine barrel, and covers the main boundary cases with focused unit tests. The core bucket math is coherent for normal positive windows, and the backoff path correctly avoids `Math.random()` and clamps numeric outputs. The only notable weakness is around invalid or future-skewed timing inputs, where the documented “always reset” behavior for non-positive windows is narrower than the implementation actually guarantees.

Nits — 5 non-blocking

• nit: packages/gittensory-engine/src/governor/rate-limit.ts:63 treats `windowMs <= 0` as elapsed only when `nowMs >= windowStartMs`; if the stored bucket start is in the future, the documented/tested “always-reset” behavior no longer holds, so either clamp future starts or tighten the comment/test to the intended contract.
• nit: packages/gittensory-engine/src/governor/rate-limit.ts:91 lets `randomFn()` exceptions propagate even though the surrounding docs emphasize the function always returns a non-negative integer for any numeric input; that is acceptable if a throwing RNG is out of contract, but the doc should make that boundary explicit.
• packages/gittensory-engine/src/governor/rate-limit.ts:63 could make the zero-window contract explicit with `const windowElapsed = windowMs === 0 || now - windowStartMs >= windowMs;` and add a test where `windowStartMs > nowMs`.
• packages/gittensory-engine/src/governor/rate-limit.ts:91 should either document that `randomFn` must not throw or wrap it and treat failures like a non-finite draw if the intended contract is truly total.
• 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	#2327
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: 226 registered-repo PR(s), 168 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	GildardoDev; Gittensor profile; 226 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: GildardoDev
• 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: 226 PR(s), 0 issue(s).
• Related work: Items reference the same linked issue feat(miner-governor): local rate-limit token-bucket + jittered-backoff calculator (pure) #2327. (issue #2327)
• Related work: Open PR work references issue feat(miner-governor): local rate-limit token-bucket + jittered-backoff calculator (pure) #2327. (issue #2327)
• Related work: Titles/paths share 7 meaningful terms. (issue #2327, issue #2292)

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.93%. Comparing base (5e9fa39) to head (60f7ffd).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2416   +/-   ##
=======================================
  Coverage   95.93%   95.93%           
=======================================
  Files         225      226    +1     
  Lines       25337    25359   +22     
  Branches     9218     9228   +10     
=======================================
+ Hits        24307    24329   +22     
  Misses        417      417           
  Partials      613      613           

Files with missing lines	Coverage Δ
...kages/gittensory-engine/src/governor/rate-limit.ts	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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