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

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