Skip to content

docs(engine): add a Governor primitives README section (9 undocumented modules) #5817

Description

@JSONbored

Context

packages/loopover-engine/src/governor/ holds nine fully-implemented, pure, side-effect-free governor primitives, every one re-exported wholesale through the package barrel (src/index.ts has nine consecutive export * from "./governor/*.js" lines):

  • rate-limit.ts — rolling-window rate limiting + jittered backoff (5 exports)
  • budget-cap.ts — spend/turn budget ceiling calculator (5 exports)
  • self-plagiarism.ts — duplicate-submission detector (11 exports)
  • reputation-throttle.ts — self-reputation-driven throttling (8 exports)
  • write-rate-limit.ts — write-action rate limiting (13 exports)
  • run-halt.ts — non-convergence/budget/termination halt calculator (8 exports)
  • kill-switch.ts — global + per-repo emergency halt detector (6 exports)
  • action-mode.ts — action-mode resolution (8 exports)
  • chokepoint.ts — composes the above into one fail-closed allow/deny verdict (5 exports)

That's ~70 exported symbols, none of which have any dedicated README section. packages/loopover-engine/README.md has exactly one governor-related heading, ## Governor ledger, which documents the append-only storage contract (normalizeGovernorLedgerEvent) and explicitly says it "does not wire into live governor enforcement yet" — but the nine governor/*.ts modules above ARE the enforcement-decision calculators themselves (each one is a decided, shipped, well-commented pure function — e.g. kill-switch.ts's own header: "DETECTOR ONLY — no IO, no persistence... the Governor chokepoint's job... which consults this module first"). This is the largest coherent exported surface in the package with zero README narrative.

Requirements

  • Add a ## Governor primitives section to packages/loopover-engine/README.md giving each of the nine modules a short paragraph: what it decides, its key exported type(s) (e.g. LocalRateLimitConfig/LocalRateLimitDecision, MinerKillSwitchScope), and how chokepoint.ts composes the other eight into one verdict ("safest wins" precedence, per its own header comment).
  • Scope this as a concise per-module overview (mirroring the README's existing "Metadata opportunity signals" section's bullet-list style), not exhaustive per-function API docs — the goal is making the surface discoverable and pointing a reader at the right source file, not duplicating every JSDoc comment.
  • Cross-reference the existing "Governor ledger" section so a reader understands how the ledger (storage) and the primitives (decision) relate.

Deliverables

  • New ## Governor primitives README section covering all nine governor/*.ts modules, each with a one-paragraph summary + key types
  • A short note on chokepoint.ts's composition role and its "safest wins" precedence over the other eight

Test Coverage Requirements

Docs-only change to packages/loopover-engine/README.md — outside coverage.include per codecov.yml (coverage is collected over src/**, packages/loopover-engine/src/**, packages/loopover-miner/lib/**, not *.md). No Codecov gate applies.

Expected Outcome

A reader of the engine package's README can discover that the governor primitives exist, understand each one's role at a glance, and know which source file to open for the full API — without first reading src/index.ts's barrel exports to realize this surface exists at all.

Links & Resources

  • packages/loopover-engine/src/governor/{rate-limit,budget-cap,self-plagiarism,reputation-throttle,write-rate-limit,run-halt,kill-switch,action-mode,chokepoint}.ts
  • packages/loopover-engine/src/governor-ledger.ts — the existing "Governor ledger" README section to cross-reference
  • packages/loopover-engine/test/{chokepoint,kill-switch,action-mode,run-halt-enforcement,self-plagiarism,write-rate-limit-enforcement}.test.ts — existing tests for reference when writing summaries

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions