docs(miner): clarify claim ledger is local bookkeeping only

[kiannidev]

Summary

• Document that miner_claims is a local bookkeeping primitive only — it records soft claims on this machine and does not adjudicate duplicate winners (that belongs to isDuplicateClusterWinnerByClaim in @jsonbored/gittensory-engine).
• Add regression tests: explicit claim→release→active-filter coverage and a source-doc assertion so the disclaimer cannot drift.

Closes #3355
Closes #3354

Test plan

• test/unit/miner-claim-ledger.test.ts — new Unit tests: claim-then-list, claim-then-release-then-list (released claim excluded from listActiveClaims), idempotent re-claim, and claims scoped correctly across two different repos. #3354 and Doc comment explicitly noting this table is a LOCAL bookkeeping primitive only and does NOT itself decide who "wins" a contested issue — that adjudication (reusing isDuplicateClusterWinnerByClaim from @jsonbored/gittensory-engine) is out of scope for this foundation-phase issue. #3355 cases
• 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-05 21:08:22 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This is a docs-only PR that adds a clarifying comment to claim-ledger.js stating the miner_claims table is local-only bookkeeping and does not adjudicate contested duplicate winners, plus two new regression tests: one exercising the existing claim→release→active-filter behavior and one asserting the disclaimer text is present in the source so it can't silently drift. The change is correct, low-risk, and matches the PR description exactly, with no schema, wiring, or logic changes. It explicitly closes #3354 and #3355 as required.

Nits — 4 non-blocking

• The new 'Unit tests: claim-then-list, claim-then-release-then-list (released claim excluded from listActiveClaims), idempotent re-claim, and claims scoped correctly across two different repos. #3354' test (test/unit/miner-claim-ledger.test.ts) largely duplicates coverage already exercised by the existing 'filters listClaims by repoFullName and/or status' test just above it, which also claims, releases, and checks the active filter — consider whether it adds anything beyond restating the same path.
• The 'Doc comment explicitly noting this table is a LOCAL bookkeeping primitive only and does NOT itself decide who "wins" a contested issue — that adjudication (reusing isDuplicateClusterWinnerByClaim from @jsonbored/gittensory-engine) is out of scope for this foundation-phase issue. #3355' test asserts on raw substrings of the source file text rather than on any behavior, so it will pass even if the comment's meaning is subtly changed as long as the three substrings remain — it only guards against wholesale deletion, not drift in accuracy.
• If the goal is to prevent the disclaimer from drifting, consider also asserting the comment stays anchored near the CREATE TABLE statement (not just present in the file) so it can't be moved somewhere confusing without failing the test.
• Given the fix here is purely documentation, consider whether the same disclaimer should also be mirrored in any README/docs describing the miner's claim flow, if such a doc exists, so contributors reading docs (not source) get the same warning.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#3355, #3354
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 (2 linked issues).
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: 1478 registered-repo PR(s), 770 merged, 48 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	kiannidev; Gittensor profile; 1478 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: 1478 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.13%. Comparing base (ae02b36) to head (87daaab).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3638   +/-   ##
=======================================
  Coverage   93.13%   93.13%           
=======================================
  Files         314      314           
  Lines       32002    32002           
  Branches    11723    11723           
=======================================
  Hits        29804    29804           
  Misses       1552     1552           
  Partials      646      646           

🚀 New features to boost your workflow:

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

[loopover-orb]

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