feat(miner-deployment): add Kubernetes StatefulSet + Secret example for AMS fleet-mode

[davion-knight]

Adds k8s/ example manifests so an operator can run N isolated miner workers on a small cluster with kubectl (#5181), built on the existing packages/gittensory-miner/Dockerfile image.

Why a StatefulSet (not a Deployment)

The miner keeps all state in local SQLite ledgers not safe for concurrent multi-pod access, so each replica needs its OWN volume. A Deployment shares one PVC across replicas; a StatefulSet's volumeClaimTemplates give each replica its own — the per-pod-isolation safety property this issue requires.

Contents

• k8s/miner-deployment.yaml — StatefulSet: configurable replicas, per-pod volumeClaimTemplate for /data/miner, non-root securityContext with runAsGroup/fsGroup (so the worker can write its PVC), resource requests/limits, continuous run worker, secret-referenced GITHUB_TOKEN (+ optional provider keys).
• k8s/miner-secret.example.yaml — Secret template with empty values (real values go in out-of-band via kubectl create secret --from-literal, never committed).
• k8s/README.md — deploy sequence, scaling, and the StatefulSet/fsGroup rationale.

Validation

• test/unit/miner-k8s-manifests.test.ts (7 tests): the real manifests are well-formed Kubernetes (StatefulSet + Secret), a deliberately malformed manifest fails the structural validator, and the per-pod-storage invariant holds (has volumeClaimTemplates; rejects a shared-PVC config and a no-volumeClaimTemplates config).
• Manifests parse as valid YAML; tsc typecheck clean; prettier-clean. Static infra only — no src/** logic, no runtime/governor/claim control-flow touched.

Closes #5181

[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.36%. Comparing base (73a0912) to head (c036c74).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5258   +/-   ##
=======================================
  Coverage   94.36%   94.36%           
=======================================
  Files         474      474           
  Lines       40081    40081           
  Branches    14614    14614           
=======================================
  Hits        37821    37821           
  Misses       1585     1585           
  Partials      675      675           

Flag	Coverage Δ
shard-1	46.24% <ø> (-0.28%)	⬇️
shard-2	34.73% <ø> (+0.07%)	⬆️
shard-3	32.08% <ø> (+0.03%)	⬆️
shard-4	31.84% <ø> (-0.28%)	⬇️
shard-5	33.69% <ø> (-0.03%)	⬇️
shard-6	44.99% <ø> (+0.19%)	⬆️

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 12:11:08 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds static example k8s manifests (StatefulSet, Secret) plus a README and a unit test validating the manifests parse and satisfy a per-pod-storage invariant. The reasoning for using a StatefulSet over a Deployment (per-pod PVC isolation for SQLite state) is sound and clearly documented, and the test suite genuinely exercises the real manifest files rather than fabricating scenarios. No src/** logic is touched, so this is a low-risk, self-contained infra/example addition that closes #5181.

Nits — 5 non-blocking

• k8s/miner-deployment.yaml uses image: gittensory-miner:latest with no registry placeholder or comment enforcing that the operator edits it before apply — consider a clearly invalid placeholder (e.g. REPLACE_ME/gittensory-miner:latest) so kubectl apply fails loudly instead of silently trying to pull a non-existent local image.
• k8s/miner-deployment.yaml has no livenessProbe/readinessProbe; README acknowledges this but an exec-based liveness probe (e.g. checking the worker process is alive) would be a reasonable default rather than leaving it as a TODO for every operator.
• The test file's readManifest helper reads from process.cwd() + 'k8s' with no existence check — if run from a different working directory this will throw an unhelpful ENOENT rather than a clear test setup error.
• Consider pinning the example image tag to something other than :latest by default in miner-deployment.yaml to nudge operators toward immutable tags from the start (k8s/miner-deployment.yaml).
• Add a brief note in k8s/README.md about PodDisruptionBudget or update strategy (OnDelete vs RollingUpdate) since StatefulSets default to RollingUpdate, which could restart all replicas' SQLite-backed pods in sequence during a cluster upgrade.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5181
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: 111 registered-repo PR(s), 82 merged, 2 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	davion-knight; Gittensor profile; 111 PR(s), 2 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 delivers a complete, well-reasoned example deployment artifact (manifests + README + tests) that directly closes the linked issue #5181 with no risk to existing runtime code.

Linked issue satisfaction

Addressed
The PR delivers per-pod isolated storage (StatefulSet with volumeClaimTemplates instead of a Deployment, deliberately deviating from the literal ask but for a well-justified reason matching the issue's own stated safety constraint), a Secret template, configurable/scalable replicas, sized resource requests/limits with documented reasoning, deploy-sequence docs in k8s/README.md, and automated tests

Review context

• Author: davion-knight
• 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: 111 PR(s), 2 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.