feat(miner): add local claim ledger

[dhgoal]

Summary

Adds the local claim ledger to @jsonbored/gittensory-miner — a 100% client-side record of "I'm working on issue #N in repo X", so Phase 2's soft-claim adjudication (sibling issues) has somewhere to persist claims. Schema + CRUD only — no adjudication logic, no network calls, no autonomous writes. It mirrors the package's existing local-store pattern (lib/run-state.js, lib/portfolio-queue.js, lib/event-ledger.js): the DB is owner-only and stays on the miner's machine, never phoning home.

API (lib/claim-ledger.js):

• openClaimLedger(dbPath?) → a ledger with recordClaim / releaseClaim / listClaims / close (plus default-singleton top-level functions and resolveClaimLedgerDbPath).
• recordClaim({ repoFullName, issueNumber, note? }) → ClaimEntry — idempotent: UNIQUE(repo_full_name, issue_number) keeps one row per claim, and the write is a single atomic INSERT … ON CONFLICT … DO UPDATE … WHERE status <> 'active', so re-claiming an already-active issue is a true no-op (never a duplicate row), while a released/expired claim can be re-activated.
• releaseClaim(repoFullName, issueNumber) → sets status released (returns the entry, or null if never claimed).
• listClaims({ repoFullName?, status? }) → claims, optionally filtered by repo and/or status.

Schema (claims table per the issue): id, repo_full_name, issue_number, claimed_at, status (active|released|expired, CHECK-constrained), note.

Location note: the issue sketched src/claim-ledger/store.ts, but this package is authored as plain-JS lib/*.js + hand-written .d.ts with node:sqlite (no TS build — its build is node --check), exactly like the four existing local stores it sits beside (run-state, ci-poller, opportunity-fanout, and the recently added portfolio-queue/event-ledger). I followed that established, consistent shape rather than introducing a separate TS toolchain to the package; node:sqlite is the package's existing zero-dependency SQLite choice.

Closes #2314.

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): local claim-ledger SQLite schema + CRUD in packages/gittensory-miner #2314).

Validation

• git diff --check
• npm run typecheck
• npm run test:coverage locally — the new test/unit/miner-claim-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 record/list/release/re-claim-after-release, the active-claim idempotency no-op, both list filters (and their combination), null-note handling, and input rejection.
• node --check lib/claim-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 idempotency 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, shared D1 migrations/, or Cloudflare-binding surface is touched. The SQLite table is a miner-local file, not a hosted-Worker 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/claim-ledger.js + its lib/claim-ledger.d.ts) mirroring lib/run-state.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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.12%. Comparing base (562f5dd) to head (b24014e).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2797   +/-   ##
=======================================
  Coverage   96.12%   96.12%           
=======================================
  Files         248      248           
  Lines       27548    27548           
  Branches    10007    10007           
=======================================
  Hits        26480    26480           
  Misses        443      443           
  Partials      625      625           

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-03 18:50:38 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This adds a local SQLite-backed claim ledger with path resolution, owner-only file permissions, idempotent claim insertion, release/list helpers, TypeScript declarations, and focused unit coverage. The core CRUD behavior is coherent: the unique constraint plus `ON CONFLICT ... WHERE status <> 'active'` preserves active claims and reactivates released rows without duplicating them. I do not see a reachable break in the provided diff, but there are a couple of API-contract and hardening details worth tightening before this becomes a dependency for later adjudication code.

Nits — 5 non-blocking

• nit: packages/gittensory-miner/lib/claim-ledger.d.ts:11 does not allow `note: null`, while `normalizeNote` in packages/gittensory-miner/lib/claim-ledger.js:53 explicitly accepts nullish notes; align the declaration with the runtime contract using `note?: string | null`.
• nit: packages/gittensory-miner/lib/claim-ledger.js:34 assumes any explicit `dbPath` has `.trim()`, so a bad runtime caller gets a generic TypeError instead of the module's `invalid_claim_ledger_db_path`; consider matching the repo-name/status validators and rejecting non-strings intentionally.
• nit: test/unit/miner-claim-ledger.test.ts:106 covers malformed repo/issue/status inputs but not invalid `note` or invalid DB path behavior, leaving two validation branches unexercised.
• packages/gittensory-miner/lib/claim-ledger.d.ts:11: change `note?: string;` to `note?: string | null;` so TypeScript consumers can use the nullish note path the implementation supports.
• packages/gittensory-miner/lib/claim-ledger.js:34: validate `typeof dbPath === "string"` before trimming so invalid runtime inputs fail with `invalid_claim_ledger_db_path`.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2314
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

[loopover-orb]

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