feat(miner-mcp): event-ledger audit feed tool (#5158)

[andriypolanski]

Closes #5158

Summary

Adds gittensory_miner_get_audit_feed, a read-only MCP tool on gittensory-miner-mcp that exposes the local append-only event ledger as a metadata-only audit feed. Reads through eventLedger.readEvents() + existing CLI filters (repoFullName, since, type); projects each row to { eventType, repoFullName, outcome, actor, detail, createdAt } without returning payload_json or other raw columns.

Shape mirrors ORB's gittensory_get_agent_audit_feed where the schemas align, adapted for the miner's local ledger vocabulary.

Changes

Area	Change
packages/gittensory-miner/lib/event-ledger-cli.js	projectLedgerEventToAuditFeedEntry, normalizeAuditFeedMcpFilter, collectEventLedgerAuditFeed
packages/gittensory-miner/bin/gittensory-miner-mcp.js	Register gittensory_miner_get_audit_feed
packages/gittensory-miner/bin/gittensory-miner-mcp.d.ts	initEventLedger injection seam
packages/gittensory-miner/README.md	Document new MCP tool
test/unit/miner-mcp-audit-feed.test.ts	MCP tool + projection + invariants
test/unit/miner-mcp-scaffold.test.ts	Updated tool list assertion

Response shape

{
  "repoFullName": "acme/widgets",
  "events": [
    {
      "eventType": "manage_pr_update",
      "repoFullName": "acme/widgets",
      "outcome": "ready",
      "actor": "miner-bot",
      "detail": "gate passed",
      "createdAt": "2026-07-04T12:00:00.000Z"
    }
  ]
}

Optional tool arguments (mirror ledger list):

• repoFullName — owner/repo
• since — non-negative integer seq cursor (strictly greater-than semantics from readEvents)
• type — event type string (--type equivalent)

Notes

• CLI unchanged: gittensory-miner ledger list --json still returns full ledger rows (including payload) for local debugging; MCP returns the metadata-only projection required by Mirror AMS's event-ledger as a read-only MCP tool (gittensory_miner_get_audit_feed) #5158.
• No write-path changes in event-ledger.js.
• Issue labels: help wanted, gittensor:feature — confirm contributor eligibility before opening.
• Independent of Add integrity checks and retention to append-only ledgers #4834 (ledger durability/retention).

Test plan

• Metadata projection strips payload/secret fields
• Empty ledger returns { events: [] }
• repoFullName / since / type filters applied
• MCP output matches collectEventLedgerAuditFeed() (invariant)
• Returned rows never include fields outside the six audit columns (invariant)
• Tool never calls appendEvent (invariant)
• npx vitest run test/unit/miner-mcp-audit-feed.test.ts test/unit/miner-event-ledger-cli.test.ts test/unit/miner-mcp-scaffold.test.ts
• 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-12 14:49:49 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a fourth read-only MCP tool (gittensory_miner_get_audit_feed) mirroring the existing dashboard/claims tools' injection-seam pattern: it opens the event ledger, reuses filterLedgerEvents, and projects rows through a new metadata-only shape that strips payload_json, verified directly against the ledger read path and tests that assert no raw payload fields leak. The implementation is correct and well-tested (invariant tests for field-set, no-mutation, and structural parity with the direct collectEventLedgerAuditFeed() call), and it closes the linked #5158 issue with a narrowly-scoped change.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/event-ledger-cli.js:88-96 — projectLedgerEventToAuditFeedEntry's payload guard (`entry?.payload && typeof … === "object" && !Array.isArray(...)`) has no test for the entry.payload === undefined/null branch specifically (only the array case is tested), so that arm isn't exercised even though it maps to the 95.83% patch coverage shortfall.
• packages/gittensory-miner/lib/event-ledger-cli.js:105 (normalizeAuditFeedMcpFilter) — per the external complexity note this function is now ~13 branches; consider splitting the three independent field-normalizations into small helpers for readability, though it's not incorrect as written.
• packages/gittensory-miner/lib/event-ledger-cli.js — normalizeAuditFeedMcpFilter re-stringifies the already-validated zod `since` number (`String(input.since)` → `Number(...)`) purely to reuse the CLI's string-based parseSinceArg; harmless but a slightly odd round trip worth a one-line comment on why (shared CLI/MCP validation).
• Add a direct unit test for projectLedgerEventToAuditFeedEntry with `payload: undefined` (not just array/non-object) to close the coverage gap flagged by codecov/patch.
• Consider whether `since` validation should live only in one layer (zod schema vs. normalizeAuditFeedMcpFilter) to avoid dual validation paths for the same field.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#5158
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: 148 registered-repo PR(s), 100 merged, 29 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 148 PR(s), 29 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: 148 PR(s), 29 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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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.41%. Comparing base (776d59c) to head (aa8b51c).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5348   +/-   ##
=======================================
  Coverage   94.40%   94.41%           
=======================================
  Files         550      550           
  Lines       44117    44141   +24     
  Branches    14631    14631           
=======================================
+ Hits        41650    41675   +25     
+ Misses       1792     1791    -1     
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.73% <4.16%> (-0.28%)	⬇️
shard-2	34.01% <0.00%> (-0.63%)	⬇️
shard-3	32.20% <0.00%> (+0.60%)	⬆️
shard-4	31.27% <0.00%> (-0.15%)	⬇️
shard-5	33.08% <100.00%> (-0.07%)	⬇️
shard-6	43.61% <0.00%> (+0.25%)	⬆️

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

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/event-ledger-cli.js	96.00% <100.00%> (+2.57%)	⬆️

🚀 New features to boost your workflow:

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