docs(miner): document append-only event ledger in README (#2322)

[kiannidev]

Summary

• Document the append-only event ledger in the miner README (initEventLedger, appendEvent, readEvents) and note it is insert-only local audit storage.
• Add a README contract test so the documented API surface stays in sync.

Closes #2322

Conflict avoidance

Touches only packages/gittensory-miner/README.md and test/unit/miner-event-ledger-readme.test.ts. No overlap with open PRs #3671, #3688, or #3691.

Test plan

• test/unit/miner-event-ledger-readme.test.ts
• npm run typecheck
• npm run build --workspace @jsonbored/gittensory-miner

Made with Cursor

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-06 06:38:17 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This is a documentation-only PR adding four sentences to the miner README describing the append-only event ledger API (initEventLedger/appendEvent/readEvents) and a corresponding contract test that asserts the README contains those exact strings. The change is straightforward, matches the existing convention already established by three prior similar entries in this same README (governor ledger #2328, claim ledger #2291), and CI passed. The test is a simple string-containment check tied to prose wording rather than the actual source code, so it will pass regardless of whether the described API truly behaves as documented (no source file for the event ledger implementation is included in this diff to verify against).

Nits — 3 non-blocking

• The new test only asserts the README text contains certain substrings; it doesn't verify against the actual `lib/event-ledger.js` (or equivalent) implementation the way `miner-claim-ledger.test.ts` does by reading source code, so it can't catch documentation drifting from real behavior.
• The PR provides no visibility into the actual event-ledger implementation file, so 'Insert-only — rows are never updated or deleted' cannot be independently verified from this diff alone; consider linking the test to the implementation file the way the claim-ledger tests do.
• Consider adding an assertion against the actual event-ledger source file (once it exists) similar to `claim-ledger.test.ts`'s check for 'LOCAL bookkeeping only' in `lib/claim-ledger.js`, so the contract test catches doc/code drift rather than just doc self-consistency.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2322
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	❌ 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: 1493 registered-repo PR(s), 781 merged, 48 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	kiannidev; Gittensor profile; 1493 PR(s), 48 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: kiannidev
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript, MDX, C++, HTML, Rust
• Official Gittensor activity: 1493 PR(s), 48 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.

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 93.35%. Comparing base (b39d174) to head (070f1c4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3702   +/-   ##
=======================================
  Coverage   93.35%   93.35%           
=======================================
  Files         315      315           
  Lines       32191    32191           
  Branches    11809    11809           
=======================================
  Hits        30053    30053           
  Misses       1507     1507           
  Partials      631      631           

🚀 New features to boost your workflow:

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

[JSONbored]

Will review shortly, investigating why AI review summaries didn't post for this PR, first time I've seen that in a while.