From 070f1c44e3a30f841933ef860af2b0c73fd66379 Mon Sep 17 00:00:00 2001
From: kiannidev <156195510+kiannidev@users.noreply.github.com>
Date: Mon, 6 Jul 2026 06:54:30 +0200
Subject: [PATCH] docs(miner): document append-only event ledger in README
 (#2322)

Document the shipped initEventLedger/appendEvent/readEvents API with a
README contract test so the manage-phase ledger surface stays discoverable.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 packages/gittensory-miner/README.md         |  4 ++++
 test/unit/miner-event-ledger-readme.test.ts | 16 ++++++++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 test/unit/miner-event-ledger-readme.test.ts

diff --git a/packages/gittensory-miner/README.md b/packages/gittensory-miner/README.md
index 42b08ab419..984d1eacf9 100644
--- a/packages/gittensory-miner/README.md
+++ b/packages/gittensory-miner/README.md
@@ -32,6 +32,10 @@ The package also includes a local soft-claim ledger: `openClaimLedger` / `claimI
 `listActiveClaims` persist which issues this miner instance has claimed on this machine. The table is local
 bookkeeping only — duplicate winners are adjudicated elsewhere via `@jsonbored/gittensory-engine`. (#2291)
 
+The package also includes an append-only event ledger: `initEventLedger` / `appendEvent` / `readEvents` persist
+immutable miner-loop events in local SQLite for contributor audit. Insert-only — rows are never updated or
+deleted. (#2322)
+
 ## Install
 
 See [`docs/miner-goal-spec.md`](docs/miner-goal-spec.md) for the `.gittensory-miner.yml` field reference and [`.gittensory-miner.yml.example`](../../.gittensory-miner.yml.example) at the repo root.
diff --git a/test/unit/miner-event-ledger-readme.test.ts b/test/unit/miner-event-ledger-readme.test.ts
new file mode 100644
index 0000000000..592afc87dc
--- /dev/null
+++ b/test/unit/miner-event-ledger-readme.test.ts
@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const readmePath = join(process.cwd(), "packages/gittensory-miner/README.md");
+
+describe("gittensory-miner event ledger README (#2322)", () => {
+  it("documents the append-only event ledger API surface", () => {
+    const readme = readFileSync(readmePath, "utf8");
+    expect(readme).toContain("initEventLedger");
+    expect(readme).toContain("appendEvent");
+    expect(readme).toContain("readEvents");
+    expect(readme).toContain("append-only");
+    expect(readme).toContain("Insert-only");
+  });
+});