feat(governor): add budget/turn/termination cap calculator

[real-venus]

Summary

Add a pure budget/turn/termination cap calculator to the engine's local Governor module — evaluateGovernorCaps(usage, limits) in packages/gittensory-engine/src/governor/budget-cap.ts, a sibling to rate-limit.ts (not built on top of it).

Where rate-limit.ts measures a rolling-window request rate that resets, these caps are cumulative, monotonic counters across a whole run:

• budget — total budget/cost units spent
• turns — total turns/iterations taken
• termination — elapsed session time vs. a wall-clock ceiling

Each dimension is evaluated independently, then combined into one verdict drawn from GOVERNOR_LEDGER_EVENT_TYPES (packages/gittensory-engine/src/governor-ledger.ts) rather than a parallel vocabulary: kill_switch when the termination ceiling is reached (a hard stop, and the most severe), denied when a budget or turn ceiling is reached, allowed when everything is clear.

It mirrors rate-limit.ts's discipline exactly:

• Pure — no IO, no clock read (elapsed time and usage are caller-supplied, like the injected nowMs), no state, no scheduling, no enforcement.
• Every numeric input is normalized (non-finite/negative → 0, mirroring finiteNonNegativeInt), so no input can produce a NaN verdict or a negative remaining value; the turn dimension is floored to whole iterations while budget/elapsed keep fractional precision.
• Re-exported from the package entrypoint alongside rate-limit.

The fail-closed enforcement chokepoint that composes this with rate-limit and the non-convergence detector is separate, maintainer-owned work (#2340) — this issue builds one of those three calculators in isolation.

Scope

• Narrow, one coherent change — one new pure module + its barrel export + tests
• In scope (packages/), no blockedPaths, no secrets/private terms
• No API/OpenAPI/migration/wrangler changes (nothing to regenerate)

Validation

• npm run typecheck
• npm run test:coverage (full unsharded suite)
• New unit test test/unit/governor-budget-cap.test.ts: per-dimension under/at/over cap, termination precedence, non-finite/negative normalization, and fractional-turn flooring
• Every changed line and branch covered (both normalizer arms, each exceeded comparison, and every verdict branch) — 100% statements/branches/functions on the new file

Safety

• Pure calculator: no state, scheduling, IO, or write-action gating; explicitly documented, with maintainer: wire the fail-closed Governor chokepoint before every write action #2340 named as the future (separate, maintainer-only) consumer
• No secrets, tokens, wallets, trust scores, or reward values in code, tests, or this description

Closes #4288

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.95%. Comparing base (084cb38) to head (11a42e8).
⚠️ Report is 41 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4374   +/-   ##
=======================================
  Coverage   93.95%   93.95%           
=======================================
  Files         400      401    +1     
  Lines       36820    36829    +9     
  Branches    13452    13456    +4     
=======================================
+ Hits        34595    34604    +9     
  Misses       1569     1569           
  Partials      656      656           

Files with missing lines	Coverage Δ
...kages/gittensory-engine/src/governor/budget-cap.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]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 17:15:54 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a pure, side-effect-free budget/turn/termination cap calculator (evaluateGovernorCaps) as a sibling to rate-limit.ts, correctly re-using GOVERNOR_LEDGER_EVENT_TYPES for its verdict vocabulary instead of inventing a parallel one, and mirrors rate-limit.ts's normalization discipline (finiteNonNegative/finiteNonNegativeInt) so no input can produce a NaN or negative result. The logic is correct: termination takes priority as kill_switch, budget/turns as denied, and the >= comparison plus Math.max(0, ...) clamping match the documented 'limit 0 means nothing allowed' semantics. Tests exercise the real exported function directly (not a fabricated payload) and cover every branch: allowed, each individual cap type, kill_switch precedence over simultaneous breaches, non-finite/negative normalization on both usage and limits, and turn-flooring vs fractional budget/elapsed precision — this looks like solid, mergeable code on its own merits.

Blockers

• Per this repo's issue-scope policy, the PR description never cites an issue it closes — it only points to maintainer: wire the fail-closed Governor chokepoint before every write action #2340 as separate, later, maintainer-owned work — so as written this doesn't satisfy the requirement that every contributor PR close or clearly link an eligible open issue, and I can't mark it merge-ready without that link.

Nits — 5 non-blocking

• This module isn't called from anywhere yet (the enforcement chokepoint is deferred to maintainer: wire the fail-closed Governor chokepoint before every write action #2340), so until that lands it's inert exported surface — same as rate-limit.ts presumably was, but worth confirming that precedent explicitly rather than assuming it.
• budget-cap.ts:64 floors `limits.turns` itself via finiteNonNegativeInt (e.g. a configured limit of 20.9 silently becomes 20) — matches the 'turns are whole counts' contract but worth a one-line comment noting the ceiling itself is floored, not just usage, since that's easy to miss on a skim.
• The module-level file comment and the function's JSDoc both re-explain the sibling-to-rate-limit relationship almost verbatim — nit for DRY, not a blocker, and matches existing verbosity in rate-limit.ts so it's at least consistent.
• Add 'Closes #<issue>' (or link the specific open issue this calculator was requested under) to the PR description so it satisfies the issue-linkage requirement.
• Consider trimming the duplicated sibling-relationship explanation down to one location (file header OR function JSDoc) in a follow-up, not blocking here.

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

Linked issue satisfaction

Addressed
The PR adds packages/gittensory-engine/src/governor/budget-cap.ts with the requested types (GovernorCapLimits, GovernorCapUsage, GovernorCapDimension, GovernorCapReport) and a pure evaluateGovernorCaps(usage, limits) function that normalizes non-finite/negative inputs, evaluates budget/turns/termination independently, and combines them into a verdict drawn from GOVERNOR_LEDGER_EVENT_TYPES; it is r

Review context

• Author: real-venus
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript, CSS, MDX, Rust, Svelte, Swift
• Official Gittensor activity: 108 PR(s), 5 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 approves — the gate is satisfied and CI is green.