From 87daaab328754abff43e534d0f6adb0d6b96b4c7 Mon Sep 17 00:00:00 2001
From: kiannidev <156195510+kiannidev@users.noreply.github.com>
Date: Sun, 5 Jul 2026 23:02:45 +0200
Subject: [PATCH] docs(miner): clarify claim ledger is local bookkeeping only
 (#3355)

Document that miner_claims does not adjudicate duplicate winners and add regression tests for the active-only filter (#3354).

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 packages/gittensory-miner/lib/claim-ledger.js |  3 +++
 test/unit/miner-claim-ledger.test.ts          | 18 +++++++++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/gittensory-miner/lib/claim-ledger.js b/packages/gittensory-miner/lib/claim-ledger.js
index cbd9a9146d..dfdf77f5e0 100644
--- a/packages/gittensory-miner/lib/claim-ledger.js
+++ b/packages/gittensory-miner/lib/claim-ledger.js
@@ -78,6 +78,9 @@ export function openClaimLedger(dbPath = resolveClaimLedgerDbPath()) {
   const db = new DatabaseSync(resolvedPath);
   chmodSync(resolvedPath, 0o600);
   db.exec("PRAGMA busy_timeout = 5000");
+  // LOCAL bookkeeping only: this table records which issues this miner instance has soft-claimed on this
+  // machine. It does NOT adjudicate contested duplicates — sibling miners claiming the same issue are
+  // resolved elsewhere via `isDuplicateClusterWinnerByClaim` from `@jsonbored/gittensory-engine` (#3355).
   db.exec(`
     CREATE TABLE IF NOT EXISTS miner_claims (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
diff --git a/test/unit/miner-claim-ledger.test.ts b/test/unit/miner-claim-ledger.test.ts
index 369e568017..dbe5b36942 100644
--- a/test/unit/miner-claim-ledger.test.ts
+++ b/test/unit/miner-claim-ledger.test.ts
@@ -1,4 +1,4 @@
-import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -120,4 +120,20 @@ describe("gittensory-miner claim ledger (#2314)", () => {
     expect(() => ledger.recordClaim({ repoFullName: "o/a", issueNumber: 1.5 })).toThrow("invalid_issue_number");
     expect(() => ledger.listClaims({ status: "bogus" as never })).toThrow("invalid_status");
   });
+
+  it("claim-then-list, then release, excludes released rows from the active-only filter (#3354)", () => {
+    const ledger = tempLedger();
+    ledger.recordClaim({ repoFullName: "o/a", issueNumber: 10 });
+    expect(ledger.listClaims({ status: "active" }).map((c) => c.issueNumber)).toEqual([10]);
+    ledger.releaseClaim("o/a", 10);
+    expect(ledger.listClaims({ status: "active" })).toEqual([]);
+    expect(ledger.listClaims()).toHaveLength(1);
+  });
+
+  it("documents that miner_claims is local bookkeeping only, not duplicate adjudication (#3355)", () => {
+    const source = readFileSync("packages/gittensory-miner/lib/claim-ledger.js", "utf8");
+    expect(source).toContain("LOCAL bookkeeping only");
+    expect(source).toContain("does NOT adjudicate contested duplicates");
+    expect(source).toContain("isDuplicateClusterWinnerByClaim");
+  });
 });