feat(miner): document claim ledger and verify schema via PRAGMA

[kiannidev]

Summary

• Document the foundation claim ledger in the miner README (openClaimLedger, claimIssue, releaseClaim, listActiveClaims) and note it is local bookkeeping only.
• Add PRAGMA-based regression tests that verify the live miner_claims columns, NOT NULL constraints, default active status, UNIQUE (repo_full_name, issue_number), and CHECK rejection of invalid statuses (Schema: repo_full_name TEXT NOT NULL, issue_number INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('active','released')), claimed_at TEXT NOT NULL, released_at TEXT, PRIMARY KEY (repo_full_name, issue_number). #3352).
• Add explicit cross-repo listActiveClaims scoping coverage (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).

Closes #2291
Closes #3352

Test plan

• test/unit/miner-claim-ledger.test.ts — PRAGMA schema + repo scoping (16 tests)
• test/unit/miner-claim-ledger-readme.test.ts — README API surface
• npm run build --workspace @jsonbored/gittensory-miner

Made with Cursor

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-05 22:01:28 UTC}

3 files · 1 AI reviewer · 1 blocker · readiness 80/100 · CI failing · blocked

🛑 Suggested Action - Reject/Close

• Linked issue overlaps another open PR — Review the related PRs before spending reviewer time on duplicate work.

Review summary
This PR adds PRAGMA-based regression tests for the miner_claims table (columns, NOT NULL constraints, default status, UNIQUE index, CHECK constraint) plus README documentation for the claimIssue/releaseClaim/listActiveClaims API, with no production code changes. I traced the test expectations against the actual CREATE TABLE statement in packages/gittensory-miner/lib/claim-ledger.js and they match exactly (column order, NOT NULL columns, 'active' default, UNIQUE(repo_full_name, issue_number)), and the CHECK-constraint rejection test inserts a real invalid 'bogus' status that will genuinely throw via the CHECK clause — this is real path coverage, not a fabricated scenario. The README addition also matches the existing source comment referencing `isDuplicateClusterWinnerByClaim` from `@​jsonbored/gittensory-engine`, so the doc and code stay in sync.

Nits — 5 non-blocking

• test/unit/miner-claim-ledger.test.ts: the inline `TableColumn` type and PRAGMA-parsing logic duplicates patterns that could live in a shared test helper if more schema tests are added later.
• test/unit/miner-claim-ledger.test.ts: `PRAGMA index_info('${uniqueIndexes[0]!.name}')` interpolates a metadata-sourced name into SQL string rather than using a bound parameter — safe here since the name comes from sqlite_master, but worth a comment noting why interpolation is acceptable in this one spot.
• test/unit/miner-claim-ledger-readme.test.ts: only checks that specific substrings exist in the README, so it would pass even if the surrounding prose became inaccurate — acceptable for a foundation-phase doc test but low signal beyond presence-of-string.
• Consider asserting the `note` column's nullability (TEXT, no NOT NULL) via the same PRAGMA table_info result set, since the other four columns are already checked for NOT NULL — would make the schema test fully exhaustive.
• The CHECK-constraint test could also assert the specific error message/code from node:sqlite (e.g. matching on 'CHECK constraint failed') rather than just `.toThrow()`, to catch a future accidental CHECK removal that throws for a different reason.

Why this is blocked

• Linked issue overlaps another open PR — Review the related PRs before spending reviewer time on duplicate work.

CI checks failing

• validate
• validate-code

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#2291, #3352
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	❌ Blocking	Repo-configured hard 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

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code); Linked issue overlaps another open PR; duplicate of another open PR). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.