You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
ORB has a well-established, documented .gittensory.yml override layer with an explicit yml > DB > defaults precedence order. AMS's equivalent config file, .gittensory-miner.yml, already exists (introduced in #4873), but nothing today documents or tests how it resolves against MINER_*/GITTENSORY_MINER_* environment variables and CLI flags when the same setting is specified in more than one place. This repo has a known recurring bug class around config-precedence drift, and AMS currently has zero guardrails against it.
Dependencies
None — independently shippable. The .gittensory-miner.yml file itself already exists (see #4873); this issue only adds documentation and a resolution-order test on top of the existing mechanism. It does not require any new precedence logic to be built first — it requires only that the current resolver's actual behavior be observed, documented, and pinned down with a test.
Requirements
Locate the current config-resolution logic for AMS — likely in packages/gittensory-miner/lib/config.js (or wherever the miner package loads .gittensory-miner.yml, MINER_*/GITTENSORY_MINER_* env vars, and CLI flags) — and determine empirically which source wins today when a setting is specified in more than one place.
Add a new documentation section (in the miner package's README or a dedicated docs file under packages/gittensory-miner/) that explicitly states the precedence order, in the same explicit style as ORB's documented .gittensory.yml "yml > DB > defaults" precedence.
Document the order the code actually implements today — do not invent or "correct" the order as part of this issue. If the resolution order is inconsistent across different settings or undefined for some source combination, note that explicitly in the docs and file a separate follow-up issue rather than fixing the broader resolver here.
Pick at least one setting that can legitimately be set all three ways (via yml, via a MINER_*/GITTENSORY_MINER_* env var, and via a CLI flag) and write an automated test that sets all three simultaneously with three different values, then asserts the resolved value matches whichever source the new documentation says wins.
Add a second test case that sets only two of the three sources (e.g. yml + env, or env + CLI) to verify correct fallback ordering, not just top-of-precedence override behavior.
Keep this change confined to docs + tests: do not modify the actual precedence/resolution implementation as part of this issue unless the new test reveals a genuine bug — in that case, open that as a separate follow-up issue instead of patching it inline.
Deliverables / Acceptance Criteria
New/updated documentation section stating the .gittensory-miner.yml vs MINER_*/GITTENSORY_MINER_* vs CLI-flag precedence order explicitly, in the miner package's docs.
At least one new automated test asserting the actual resolution order for a setting configurable via all three methods.
A second test asserting correct fallback behavior when only a subset of the three sources set the value.
If a precedence bug or inconsistency is discovered while writing the tests, a new issue is filed to track it (not fixed inline in this PR).
All new code paths covered by unit tests satisfying the repo's 99%+ Codecov patch gate.
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new/changed resolution-order test logic's success and failure paths, (2) an invariant test asserting that the documented precedence order for .gittensory-miner.yml vs MINER_*/GITTENSORY_MINER_* env vars vs CLI flags always matches the resolver's actual runtime behavior — i.e., there is no source combination tested where the resolved config value diverges from what the new documentation states, and (3) a regression test is not strictly applicable since this isn't framed as a bug fix, but the resolution-order test itself doubles as the regression guard against future silent precedence changes.
Codecov visibility note:packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.
Expected Outcome
Contributors and operators configuring the miner can consult one explicitly documented precedence order instead of guessing or reverse-engineering the resolver, and a test will fail immediately if a future change silently alters that order.
Links & Resources
packages/gittensory-miner/lib/config.js (or the package's actual config-resolution module)
Context
ORB has a well-established, documented
.gittensory.ymloverride layer with an explicit yml > DB > defaults precedence order. AMS's equivalent config file,.gittensory-miner.yml, already exists (introduced in #4873), but nothing today documents or tests how it resolves againstMINER_*/GITTENSORY_MINER_*environment variables and CLI flags when the same setting is specified in more than one place. This repo has a known recurring bug class around config-precedence drift, and AMS currently has zero guardrails against it.Dependencies
None — independently shippable. The
.gittensory-miner.ymlfile itself already exists (see #4873); this issue only adds documentation and a resolution-order test on top of the existing mechanism. It does not require any new precedence logic to be built first — it requires only that the current resolver's actual behavior be observed, documented, and pinned down with a test.Requirements
packages/gittensory-miner/lib/config.js(or wherever the miner package loads.gittensory-miner.yml,MINER_*/GITTENSORY_MINER_*env vars, and CLI flags) — and determine empirically which source wins today when a setting is specified in more than one place.packages/gittensory-miner/) that explicitly states the precedence order, in the same explicit style as ORB's documented.gittensory.yml"yml > DB > defaults" precedence.MINER_*/GITTENSORY_MINER_*env var, and via a CLI flag) and write an automated test that sets all three simultaneously with three different values, then asserts the resolved value matches whichever source the new documentation says wins.Deliverables / Acceptance Criteria
.gittensory-miner.ymlvsMINER_*/GITTENSORY_MINER_*vs CLI-flag precedence order explicitly, in the miner package's docs.Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new/changed resolution-order test logic's success and failure paths, (2) an invariant test asserting that the documented precedence order for
.gittensory-miner.ymlvsMINER_*/GITTENSORY_MINER_*env vars vs CLI flags always matches the resolver's actual runtime behavior — i.e., there is no source combination tested where the resolved config value diverges from what the new documentation states, and (3) a regression test is not strictly applicable since this isn't framed as a bug fix, but the resolution-order test itself doubles as the regression guard against future silent precedence changes.Codecov visibility note:
packages/gittensory-miner/**,apps/gittensory-miner-ui/**, andapps/gittensory-miner-extension/**currently sit entirely outside vitest'scoverage.includeglob, socodecov/patchcannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change underpackages/gittensory-engine/src/**or the repo's ownsrc/**remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.Expected Outcome
Contributors and operators configuring the miner can consult one explicitly documented precedence order instead of guessing or reverse-engineering the resolver, and a test will fail immediately if a future change silently alters that order.
Links & Resources
packages/gittensory-miner/lib/config.js(or the package's actual config-resolution module)doctorvalidate config content, not just its path #4873 (introduces.gittensory-miner.yml).gittensory.ymlprecedence model (yml > DB > defaults) as the documentation-style reference