feat(miner): add append-only event ledger

[dhgoal]

Summary

Adds the local append-only event ledger to @jsonbored/gittensory-miner — an immutable audit trail of every significant miner-loop event (discovered_issue, plan_built, plan_step_completed, pr_prepared, … — a small fixed vocabulary for this foundation phase that grows later), backed by a small local SQLite table. It mirrors the package's existing local-store pattern (lib/run-state.js, lib/portfolio-queue.js) and never uploads, syncs, or phones home — the DB is owner-only and stays on the miner's machine.

Immutability invariant: the module only ever issues INSERT and SELECT — it never rewrites or removes a row — so a contributor auditing the miner's history later can trust it was not retroactively edited. The header comment states this constraint explicitly, and a test asserts the module source contains no mutating/removing SQL keyword.

API (lib/event-ledger.js):

• appendEvent({ type, repoFullName?, payload }) → LedgerEntry — stamps a module-maintained monotonic seq and an ISO timestamp; payload is stored as JSON and round-trips verbatim.
• readEvents(filter?) — all events in seq ASC order, optionally filtered by repoFullName and/or since (events with a seq strictly greater than since — the "give me everything after the last seq I saw" polling shape).

Schema is per the issue spec: id INTEGER PRIMARY KEY AUTOINCREMENT, seq INTEGER NOT NULL, event_type TEXT NOT NULL, repo_full_name TEXT, payload_json TEXT NOT NULL, created_at TEXT NOT NULL. seq is maintained by the module (MAX(seq) + 1) rather than relying on AUTOINCREMENT's reuse-after-vacuum behavior, so consumers get a stable ordering guarantee.

Closes #2290.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue (feat(miner-foundation): immutable event ledger for gittensory-miner #2290).

Validation

• git diff --check
• npm run typecheck
• npm run test:coverage locally — the new test/unit/miner-event-ledger.test.ts passes (whole miner suite green). This change lives entirely in packages/**, which Codecov does not measure, so it carries no codecov/patch obligation; the logic is nonetheless exercised across append/read round-trip, seq monotonicity, both filters (and their combination), null vs present repo scope, input rejection, and the append-only-source assertion.
• node --check lib/event-ledger.js via npm run --workspace @jsonbored/gittensory-miner build
• npm audit --audit-level=moderate — this PR adds no dependencies, so dependency-review has nothing new to evaluate.
• New behavior has unit tests for new branches, fallback paths, and the immutability invariant.

If any required check was skipped, explain why:

• UI/OpenAPI/migration/workers checks are not applicable: this change is one local-persistence module in packages/gittensory-miner/lib plus its test — no src/**, UI, API schema, Drizzle, or Cloudflare-binding surface is touched. The SQLite table is a miner-local file, not a repo migration.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed. The DB is created 0o600 in a 0o700 dir, owner-only, and never leaves the machine.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — n/a: local-only SQLite persistence, no auth/session/network surface.
• API/OpenAPI/MCP behavior is updated and tested where needed. — n/a: no API/OpenAPI/MCP surface changed.
• UI changes use live API data or real states. — n/a: no UI change.
• Visible UI changes include a UI Evidence section. — n/a: no visible UI, frontend, docs, or extension change.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

Additive and consistent with the package's existing local-store pattern: two new files (lib/event-ledger.js + its lib/event-ledger.d.ts) mirroring lib/run-state.js / lib/portfolio-queue.js (path resolution, 0o600/0o700 perms, prepared statements, default-store singleton), one line added to the package build (node --check) gate, and one new test file. No existing code is modified.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-03 18:37:49 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
The change adds a focused local SQLite-backed event ledger with typed exports, path resolution, append/read APIs, owner-only file permissions, and useful unit coverage for ordering, filtering, validation, and append-only intent. The core insert/read path is coherent: `BEGIN IMMEDIATE` protects the `MAX(seq)+1` sequence assignment, rows are returned in `seq ASC`, and payloads are rejected when JSON would not round-trip. I do not see a reachable breaking defect in the provided diff, but the API currently documents a fixed event vocabulary while accepting any non-empty string.

Nits — 5 non-blocking

• nit: packages/gittensory-miner/lib/event-ledger.js:39 accepts any non-empty event type even though the module header and PR description describe a small fixed vocabulary; define and enforce that vocabulary or make the contract explicitly open-ended.
• nit: packages/gittensory-miner/lib/event-ledger.js:155 treats any non-number `since` as absent and accepts `NaN`/`Infinity` as numbers; validate `since` as a finite non-negative integer so polling callers cannot silently get surprising results.
• nit: packages/gittensory-miner/lib/event-ledger.js:92 unconditionally `chmodSync`s the resolved path after opening it, which is right for local ownership but should be called out because explicit DB paths may point at caller-managed files.
• In packages/gittensory-miner/lib/event-ledger.d.ts:9, consider exporting `type EventType = "discovered_issue" | "plan_built" | "plan_step_completed" | "pr_prepared" | ...` and using it in `AppendEventInput` to keep TypeScript and runtime validation aligned.
• In packages/gittensory-miner/lib/event-ledger.js:155, reject invalid `since` values instead of dropping the filter, e.g. only accept `Number.isSafeInteger(filter.since) && filter.since >= 0`.

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

Review context

• Author: dhgoal
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 27 PR(s), 1 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 96.09%. Comparing base (28a6b40) to head (8bfdf03).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2754   +/-   ##
=======================================
  Coverage   96.09%   96.09%           
=======================================
  Files         245      245           
  Lines       27391    27391           
  Branches     9947     9947           
=======================================
  Hits        26322    26322           
  Misses        443      443           
  Partials      626      626           

🚀 New features to boost your workflow:

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

[dhgoal]

Fixed the flagged concurrency defect. seq allocation is now atomic: the schema enforces UNIQUE(seq) and appendEvent runs the MAX(seq)+1 read and the INSERT inside a single BEGIN IMMEDIATE transaction (with PRAGMA busy_timeout), so two ledger instances opened on the same file serialize on the write lock and can never compute or persist a duplicate seq. Added a test appending 50 events and asserting the seqs are exactly 1..50 (gapless + unique).

[dhgoal]

Fixed the payload round-trip defect. appendEvent now enforces that the payload survives JSON verbatim: it rejects (invalid_payload) any object JSON would alter — undefined/function/symbol values, NaN/Infinity, BigInt, or a circular reference — by verifying isDeepStrictEqual(JSON.parse(JSON.stringify(payload)), payload). So a read-back is always identical to the appended event. Added tests for the rejected cases plus a nested JSON-safe payload that reads back identically.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.