feat(miner-governor): wire rate-limit + jittered backoff into live write enforcement (#2344)

[andriypolanski]

Closes #2344

Summary

Wires the existing pure evaluateLocalRateLimit / jitteredBackoffMs calculator into Governor write enforcement: every write action is checked against both a global and a per-repo rolling-window bucket. Over-limit writes are throttled with jittered retry scheduling (not permanent failure or busy-looping) and recorded to the governor ledger.

Changes

Area	Change
packages/gittensory-engine/src/governor/write-rate-limit.ts	evaluateWriteRateLimit, bucket advance/deny helpers, ledger event builder
packages/gittensory-engine/src/index.ts	Export write-rate-limit module
packages/gittensory-miner/lib/governor-write-rate-limit.js	evaluateWriteRateLimitGate — check + retry schedule + ledger write
packages/gittensory-miner/lib/governor-write-rate-limit.d.ts	Type declarations
packages/gittensory-miner/package.json	build --check for governor-write-rate-limit
Tests	governor-write-rate-limit.test.ts, miner-governor-write-rate-limit.test.ts, engine package test

Behavior

• Under both limits → allowed; global + per-repo buckets advance
• Per-repo burst over limit → throttled with per_repo_rate_limit; jittered retryAfterMs grows with burst attempts
• Global ceiling reached → throttled with global_rate_limit even when the repo bucket is under its own limit
• Window elapses → bucket resets; writes permitted again
• Denied write → buckets unchanged; backoff attempt incremented for increasing jitter

Test plan

• Per-repo burst throttled with increasing jittered delays
• Global ceiling blocks when individual repo buckets are under limit
• Bucket resets after rolling window elapses
• buildWriteRateLimitGovernorLedgerEvent records retry metadata
• evaluateWriteRateLimitGate persists allowed/throttled decisions to governor ledger
• Engine package barrel + enforcement smoke test
• npm run test:unit -- test/unit/governor-write-rate-limit.test.ts test/unit/miner-governor-write-rate-limit.test.ts
• npm run test --workspace @jsonbored/gittensory-engine
• npm run test:ci (full gate before push)

Notes

• Composes with the Governor chokepoint (maintainer: wire the fail-closed Governor chokepoint before every write action #2340) — this issue delivers enforcement wiring + ledger helper, not the full composed chokepoint.
• The pure calculator in governor/rate-limit.ts was already on main; this PR adds the enforcement layer only.
• Default policies: open_pr 30/min global, 3/min per-repo; comment 60/min global, 10/min per-repo; 1s jitter base.

Test plan

• Integration tests: per-repo burst, global ceiling, window reset, increasing jitter
• Miner governor gate + ledger persistence tests
• npm run test:ci

[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-11 07:18:35 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR wires the existing pure evaluateLocalRateLimit/jitteredBackoffMs calculator into a new global+per-repo write enforcement layer (write-rate-limit.ts), a miner-side gate that checks both buckets and persists allowed/throttled decisions to the governor ledger, and updates the package.json build check + barrel export. The bucket math correctly reuses the pure primitives from rate-limit.ts (global.retryAfterMs is guaranteed 0 when allowed, so the max(windowWait, jitterWait) and blockedBy ternary are both reachable and correct, not can't-occur branches), and the three-layer test suite (engine unit, miner gate with a real sqlite ledger, and a barrel/dist smoke test) exercises allow, per-repo throttle, global-ceiling-despite-under-repo-limit, window reset, NaN/non-finite normalization, and default-policy fallback paths. This closes #2344 and is scoped tightly to the stated deliverable with no unrelated changes.

Nits — 5 non-blocking

• packages/gittensory-engine/src/governor/write-rate-limit.ts:31-40: the DEFAULT_WRITE_RATE_LIMIT_POLICIES limits (30/60/3/10 per 60s) are only exercised indirectly (via an unknown-actionClass PERMISSIVE_CONFIG fallback test); consider a test that omits `policies` entirely and asserts the real open_pr/comment defaults are applied.
• packages/gittensory-engine/src/governor/write-rate-limit.ts:19-38: several unexplained window/limit magic numbers (60_000, 30, 3, 10) could be named constants for readability, though the surrounding object keys already make intent fairly clear.
• packages/gittensory-miner/lib/governor-write-rate-limit.js: repoFullName is passed through to buildWriteRateLimitGovernorLedgerEvent in its original casing while the bucket/backoff keys are lowercased via writeRateLimitRepoKey — worth confirming the ledger's repoFullName column doesn't need case-normalization for downstream queries.
• Add a test asserting DEFAULT_WRITE_RATE_LIMIT_POLICIES values are actually applied when `policies` is omitted, not just that the omission path type-checks.
• Consider naming the window/limit literals in DEFAULT_WRITE_RATE_LIMIT_POLICIES (e.g. `ONE_MINUTE_MS`) for a small readability win.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2344
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: 140 registered-repo PR(s), 95 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 140 PR(s), 25 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: andriypolanski
• 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: 140 PR(s), 25 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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.31%. Comparing base (7bbf529) to head (639feaa).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4984   +/-   ##
=======================================
  Coverage   94.31%   94.31%           
=======================================
  Files         454      455    +1     
  Lines       39034    39083   +49     
  Branches    14234    14256   +22     
=======================================
+ Hits        36813    36862   +49     
  Misses       1572     1572           
  Partials      649      649           

Flag	Coverage Δ
shard-1	46.85% <6.12%> (-0.06%)	⬇️
shard-2	33.35% <6.12%> (+0.12%)	⬆️
shard-3	31.12% <6.12%> (-0.25%)	⬇️
shard-4	33.00% <6.12%> (-0.06%)	⬇️
shard-5	33.63% <6.12%> (+0.09%)	⬆️
shard-6	45.26% <100.00%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...gittensory-engine/src/governor/write-rate-limit.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.