fix(miner): wire AMS policy resolver to the documented discovery order

[bitfathers94]

fix(miner): wire AMS policy resolver to the documented discovery order

AMS_POLICY_SPEC_FILENAMES documented a 4-path first-match-wins discovery
order "mirroring MINER_GOAL_SPEC_FILENAMES", but ams-policy.ts resolved
policy from a single operator-config-dir filename (.loopover-ams.yml),
never imported the constant, and had no fallback chain -- an operator
using the .github/ or .json variants silently got defaults.

Wire it up (issue option b): add a pure discoverAmsPolicySpecPath helper
to the engine mirroring discoverMinerGoalSpecPath, and have the miner's
readLocalAmsPolicyContent probe the full order inside the operator config
directory. An explicit LOOPOVER_MINER_AMS_POLICY_PATH still bypasses
discovery to one exact file. The config-dir resolution is factored into
a shared resolveLocalStoreConfigDir so all LOOPOVER_MINER_CONFIG_DIR reads
stay in local-store.ts and the generated env-reference is unchanged.

Closes #8863

Validation

Verified locally on this branch before opening:

• npm run typecheck
• npx turbo run build:tsc build:verify
• npm run test:coverage — patch coverage 100.0% of changed lines

[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 93.88%. Comparing base (e1ab6c4) to head (db3d45d).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9106   +/-   ##
=======================================
  Coverage   93.88%   93.88%           
=======================================
  Files         812      812           
  Lines       80650    80662   +12     
  Branches    24470    24474    +4     
=======================================
+ Hits        75721    75733   +12     
  Misses       3562     3562           
  Partials     1367     1367           

Flag	Coverage Δ
backend	95.17% <100.00%> (+<0.01%)	⬆️

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

Files with missing lines	Coverage Δ
packages/loopover-engine/src/ams-policy-spec.ts	100.00% <100.00%> (ø)
packages/loopover-miner/lib/ams-policy.ts	100.00% <100.00%> (ø)
packages/loopover-miner/lib/local-store.ts	100.00% <100.00%> (ø)

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-26 18:15:21 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This wires the previously dead-on-arrival AMS_POLICY_SPEC_FILENAMES fallback chain into the actual miner resolver: a new pure discoverAmsPolicySpecPath in the engine package mirrors discoverMinerGoalSpecPath, and ams-policy.ts's resolveLocalAmsPolicyReadPath now probes all four documented candidates inside the operator config dir while an explicit LOOPOVER_MINER_AMS_POLICY_PATH still bypasses discovery to one exact file. The config-dir extraction into local-store.ts's resolveLocalStoreConfigDir is a straightforward refactor that preserves resolveLocalStoreDbPath's existing behavior for its other callers (run-state.js, claim-ledger.js, etc.) since it's just factored out, not changed. Tests exercise every discovery-order filename, first-match-wins precedence, the explicit-path bypass, and the fallback-to-defaults paths for missing/unreadable overrides — this closes #8863 as described.

Nits — 5 non-blocking

• ams-policy.ts:97-105 resolveLocalAmsPolicyReadPath detects an explicit LOOPOVER_MINER_AMS_POLICY_PATH override indirectly by string-comparing canonicalPath against join(configDir, AMS_POLICY_FILENAME) rather than checking the env var directly — works today but is a fragile way to express 'was there an explicit override', consider passing/checking the raw env value instead for clarity.
• readLocalAmsPolicyContent still does a plain existsSync+readFileSync with no regular-file/size guard, unlike the sibling resolveMinerGoalSpec in miner-goal-spec.ts which uses O_NOFOLLOW+fstat+bounded read — preexisting, but worth noting since this PR extends the same read path to more candidate files.
• test/unit/miner-ams-policy.test.ts's 'resolves from explicit env, config dir, and XDG default' test no longer actually covers the XDG-default case (only 2 of the 3 named cases are asserted) despite the name still saying 'and XDG default'.
• Consider renaming or restoring the XDG-default assertion in the 'resolves from explicit env, config dir, and XDG default' test so the name matches what's covered.
• In resolveLocalAmsPolicyReadPath, an explicit boolean flag (e.g. `const isExplicitOverride = typeof env.LOOPOVER_MINER_AMS_POLICY_PATH === "string" && env.LOOPOVER_MINER_AMS_POLICY_PATH.trim() !== ""`) would be more directly readable than the path-equality inference.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#8863
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: 52 registered-repo PR(s), 41 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	bitfathers94; Gittensor profile; 52 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The PR chooses option (b): it adds a pure discoverAmsPolicySpecPath helper mirroring discoverMinerGoalSpecPath, wires readLocalAmsPolicyContent to probe the full documented 4-path order within the operator config dir (with explicit-path override still bypassing discovery), and exports the new helper from the engine index. It also adds discovery-behavior tests covering all four filename variants pl

Review context

• Author: bitfathers94
• 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: 52 PR(s), 0 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.

🧪 Chat with LoopOver

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

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

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

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