test(miner): add real concurrent-process races test for claim-ledger and portfolio-queue

[galuis116]

Summary

• Only packages/gittensory-miner/lib/worktree-allocator.js had a dedicated multi-process collision test (test/unit/miner-worktree-allocator-collisions.test.ts) before this PR — the claim-ledger and portfolio-queue stores' atomicity was only exercised per-function (single process, sequential calls), never under real concurrent load from two actual OS processes racing the same on-disk SQLite file.
• Adds test/unit/miner-concurrent-store-races.test.ts, closely mirroring the existing worktree-allocator collision test's structure (spawn real Node child processes, barrier them on a stdin "go" signal after each reports READY, then assert the resulting on-disk state):
  • claim-ledger: two processes claiming the same (repoFullName, issueNumber) simultaneously — asserts exactly one active row results (no duplicate/corrupted rows despite the concurrent UPSERT), plus a sibling test that two processes claiming different issues both succeed with distinct rows.
  • portfolio-queue: two processes racing dequeueNext() on a single queued item — asserts exactly one process wins the atomic UPDATE...RETURNING claim and the other gets null (no double-dequeue), plus an N-processes/N-items variant asserting all N claims are distinct with zero duplicates.
• Two new child-process fixture scripts, mirroring test/fixtures/miner-worktree-allocator/acquire-child.mjs's exact shape: test/fixtures/miner-concurrent-stores/claim-child.mjs and .../dequeue-child.mjs.
• Per the issue's explicit scope note, this only adds test coverage locking in the existing atomicity guarantees (the stores' own atomic SQL statements — INSERT...ON CONFLICT for claims, UPDATE...RETURNING for dequeue). No claim-conflict "who wins" resolution logic is touched or added.

Fixes #4867

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — this change lives entirely under packages/gittensory-miner/**-adjacent test files (test/unit/**, test/fixtures/**), which are outside vitest's coverage.include glob (the packages/gittensory-miner/** source itself is what's exercised, and it sits outside coverage.include too), so codecov/patch cannot measure this directly — consistent with how the existing worktree-allocator collision test is also uncounted.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run build:miner
• npm run test:miner-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:test
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

This PR is the test addition: 6 new tests (4 real cross-process races + 2 fixture-argument-validation guards), all driving the real stores via real spawned node child processes against real on-disk SQLite files (no mocking of the concurrency behavior under test). Ran the new file 4 times in a row locally to check for timing flakiness — stable every time (6/6 passing, ~0.6–1.4s total).

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• 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, no auth/session/CORS surface touched.
• API/OpenAPI/MCP behavior is updated and tested where needed. — N/A, no API/OpenAPI/MCP surface change; test-only addition.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — N/A, no UI surface touched.
• Visible UI changes include a UI Evidence section below — N/A, no visible/UI change.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

Not applicable — this PR only adds cross-process integration tests for two local SQLite-backed stores; there is no visible UI change.

Notes

• Explicitly out of scope per the issue: if this test had uncovered a real race/corruption bug in the stores' conflict-resolution logic, the fix would need to be filed as a separate maintainer-only issue rather than folded into this PR. No such bug was found — the existing atomic SQL statements (ON CONFLICT upsert for claims, UPDATE...RETURNING subquery for dequeue) already hold correctly under real concurrent load; this PR only makes that guarantee test-verified instead of merely load-bearing-by-inspection.

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.67%. Comparing base (7e2e20d) to head (edbf70f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5464      +/-   ##
==========================================
- Coverage   94.71%   94.67%   -0.04%     
==========================================
  Files         555      555              
  Lines       44529    44529              
  Branches    14666    14666              
==========================================
- Hits        42175    42158      -17     
- Misses       1619     1636      +17     
  Partials      735      735              

Flag	Coverage Δ
shard-1	43.77% <ø> (-0.25%)	⬇️
shard-2	35.22% <ø> (-0.01%)	⬇️
shard-3	32.07% <ø> (+0.11%)	⬆️
shard-4	31.56% <ø> (-0.58%)	⬇️
shard-5	33.12% <ø> (+0.45%)	⬆️
shard-6	43.75% <ø> (+0.28%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 21:14:24 UTC}

3 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a real cross-process concurrency test suite for claim-ledger and portfolio-queue stores, closely mirroring the existing worktree-allocator collision test's proven pattern (spawn, READY, stdin barrier, JSON result). The tests exercise genuine atomicity guarantees (UPSERT for claims, UPDATE...RETURNING for dequeue) via actual OS-level races rather than mocked concurrency, and both fixture scripts correctly validate required args and exit non-zero on missing input. This is pure test-only addition with no changes to production code, closing the explicit scope gap noted in issue #4867.

Nits — 5 non-blocking

• test/unit/miner-concurrent-store-races.test.ts: the N-processes/N-items dequeue test uses 4 fixed identifiers rather than a parameterized N, so if you intend this to scale as true 'N processes' coverage in the future, consider extracting the count as a constant.
• test/fixtures/miner-concurrent-stores/claim-child.mjs and dequeue-child.mjs duplicate the READY/stdin-barrier/JSON-result boilerplate already present in test/fixtures/miner-worktree-allocator/acquire-child.mjs — a shared helper module could remove this triplication, though the mirroring is intentional per the PR description.
• test/unit/miner-concurrent-store-races.test.ts: `waitForReady` and `runBarriered` are copy-pasted verbatim from the worktree-allocator test file rather than imported from a shared test-util module — worth extracting if a fourth store test appears.
• Consider factoring the child-process barrier protocol (waitForReady/runBarriered) shared across miner-worktree-allocator-collisions.test.ts and this new file into a common test helper to avoid drift between the two copies.
• The dequeue-child.mjs and claim-child.mjs fixtures could share a small `readyAndBarrier(fn)` utility instead of duplicating the READY/stdin/try-catch-finally boilerplate.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#4867
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	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 1869 registered-repo PR(s), 1232 merged, 49 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	galuis116; Gittensor profile; 1869 PR(s), 49 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: clean · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed). LLM value judgment: moderate — The PR closes a real, previously-flagged gap (issue #4867) by adding genuine multi-process race coverage for two stores that only had single-process sequential tests before, using a proven pattern already validated in the codebase.

Linked issue satisfaction

Addressed
The PR adds a new integration test spawning real Node child processes that race the same on-disk SQLite file for both claim-ledger (simultaneous same-issue claim) and portfolio-queue (simultaneous dequeueNext), asserting exactly one winner and no duplicate/corrupted rows, matching the issue's deliverable and staying within its stated scope by not touching conflict-resolution logic.

Review context

• Author: galuis116
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 1869 PR(s), 49 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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.