43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# ADR 0005: Record explicit CLI overrides and safe value explanation
|
|
|
|
Status: accepted
|
|
|
|
Date: 2026-09-06
|
|
|
|
## Context
|
|
|
|
Consumers need deliberate per-invocation configuration changes and an explanation
|
|
of effective values. Presence and origin records alone cannot show which values
|
|
were replaced. Adding CLI parsing or arbitrary environment overlays would broaden
|
|
the library beyond its consistent configuration model.
|
|
|
|
## Decision
|
|
|
|
Use parser-neutral explicit path/value/flag records above selected profiles.
|
|
Defaults remain below strictly composed base input. Apply overrides to the owned
|
|
node tree before typed decoding, retaining the existing parser adapter boundary.
|
|
Recorded domain resolution follows input selection. Provide safe structured
|
|
historical values and an explanation renderer in the initial release, building
|
|
on ADR 0003's presence and audited resolution decision. Applications own commands.
|
|
The [current override contract](../config.md#explicit-cli-overrides) and
|
|
[explanation contract](../config.md#historical-value-explanation) own the implemented
|
|
behavior.
|
|
|
|
## Alternatives considered
|
|
|
|
- Retire configuration flags in favor of profiles: smaller API, but removes useful
|
|
explicit invocation choices that fit a single fixed precedence model.
|
|
- Mutate structs after loading: easy locally, but bypasses validation and leaves
|
|
metadata and effective inspection inconsistent.
|
|
- Defer historical values: reduces initial implementation scope but cannot answer
|
|
why an effective value differs from defaults or an earlier file.
|
|
- Publish raw history trees: flexible but couples consumers to internals and risks
|
|
leaking sensitive values. Detached, redacted snapshots preserve the boundary.
|
|
|
|
## Consequences
|
|
|
|
The library owns override validation and source attribution without choosing a
|
|
CLI framework. History requires bounded retained state and tests for replacement,
|
|
deletion, composite origins and sensitivity. Credentials never enter history;
|
|
secret reference names remain explainable unless explicitly classified sensitive.
|