docs(miner): operational runbook for local SQLite state (#4875)

[andriypolanski]

Closes #4875

Summary

Adds packages/gittensory-miner/docs/operations-runbook.md — the missing operator runbook for AMS local SQLite state. Covers the three scenarios called out in the issue plus the existing busy_timeout concurrency guarantee that was implemented but never documented for operators.

Documentation-only PR.

Changes

Area	Change
packages/gittensory-miner/docs/operations-runbook.md	New runbook: concurrency, two-miner collision, corruption recovery, post-upgrade migration
packages/gittensory-miner/docs/coding-agent-driver.md	Related docs link (issue entry point)
packages/gittensory-miner/README.md	Link from install/local-storage section
packages/gittensory-miner/DEPLOYMENT.md	Link from invariants
packages/gittensory-miner/docs/discovery-plane-operator-guide.md	Related docs cross-link
test/unit/miner-operations-runbook.test.ts	Doc presence + link resolution invariants

Runbook sections

1. SQLite concurrency (busy_timeout) — 5000 ms default, what it does and does not guarantee (one loop per state dir)
2. Two miners collided — symptoms, diagnosis commands, stop/split-state remediation
3. Ledger corrupted — corrupted_*_row errors, integrity_check, tiered recovery (single-store reset / restore / re-init)
4. Migrate after upgrade — applySchemaMigrations / PRAGMA user_version, backup checklist, fleet rolling upgrade note

Test plan

• Runbook documents all three issue scenarios + busy_timeout
• coding-agent-driver.md link resolves to operations-runbook.md
• DEPLOYMENT.md links to runbook
• npx vitest run test/unit/miner-operations-runbook.test.ts
• npm run test:ci

Notes

• Issue labels: help wanted, gittensor:feature — confirm contributor eligibility before opening.
• Distinct from #5190 (Grafana observability) — runbook links out rather than duplicating.
• No src/** changes — Codecov patch gate N/A.

[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.41%. Comparing base (a0639fd) to head (97ef112).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5390   +/-   ##
=======================================
  Coverage   94.41%   94.41%           
=======================================
  Files         551      551           
  Lines       44168    44168           
  Branches    14632    14632           
=======================================
  Hits        41702    41702           
  Misses       1791     1791           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.88% <ø> (-0.27%)	⬇️
shard-2	34.03% <ø> (-0.52%)	⬇️
shard-3	32.14% <ø> (+0.58%)	⬆️
shard-4	31.07% <ø> (-0.21%)	⬇️
shard-5	32.86% <ø> (-0.46%)	⬇️
shard-6	43.95% <ø> (+0.54%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 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 16:24:48 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a documentation-only PR adding an operations runbook for the miner's local SQLite state (concurrency, collision, corruption, migration), plus cross-links from four existing docs and a test asserting the runbook contains the required content and that links resolve. The content is accurate to what's described elsewhere in the repo (busy_timeout, BEGIN IMMEDIATE, schema-version.js/applySchemaMigrations, corrupted_*_row errors) and is well-organized; the test is a reasonable doc-presence/link-resolution check rather than a fabricated code test, and it closes issue #4875 as required. No code paths are touched, so no functional regression is possible.

Nits — 6 non-blocking

• test/unit/miner-operations-runbook.test.ts only checks driverDoc contains the runbook link and that runbook exists, but doesn't verify README.md/discovery-plane-operator-guide.md links despite the PR description claiming those cross-links — consider asserting those too for parity.
• The runbook states production stores use the default busy_timeout only, and that override is 'tests only' (packages/gittensory-miner/docs/operations-runbook.md) — worth double-checking this claim against local-store.js if it ever changes, since it's an assertion not directly verified by the added test.
• Add a test assertion for the README.md and discovery-plane-operator-guide.md links mentioned in the PR description table, matching the existing pattern for coding-agent-driver.md and DEPLOYMENT.md.
• Consider linking the runbook's 'schema-version.js' convention section directly to the source file path if one exists, for easier operator navigation.
• nit: packages/gittensory-miner/docs/operations-runbook.md:9 points operators to packages/gittensory-miner/README.md#local-storage for the store inventory, but that README section still says there are only four SQLite stores while this runbook lists additional files, so update the README table or keep the full inventory in one canonical doc.
• Diff looks like trivial or whitespace-only churn — Reduce whitespace-only or formatting-only churn and keep the diff focused on substantive changes.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#4875
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: 153 registered-repo PR(s), 103 merged, 29 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 153 PR(s), 29 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: low · 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 fills a genuine documentation gap (issue #4875) for an existing but previously undocumented busy_timeout/migration guarantee, with accurate cross-links and a test that mechanically enforces the documented invariants stay true.

Review context

• Author: andriypolanski
• 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: 153 PR(s), 29 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.