1.8 KiB
ADR 0003: Preserve Presence and Record Application Resolution
Status
Accepted. This records a design decision, not implementation completion.
Date
2026-09-06
Context
Go zero values cannot distinguish omitted input from explicitly configured false, zero, or empty text. Decoding immediately also loses information needed to explain imports and overlays. Application normalization can subsequently make retained input metadata disagree with runtime values.
Decision
Preserve input presence and provenance separately from ordinary application Go values. Keep application defaults and normalization application-owned, but record resolution changes so final inspection and metadata describe the actual resolved snapshot. Do not promise language-enforced immutability of exported Go values. The architecture policy owns these invariants; the target design owns the planned recording mechanism and ownership semantics.
Alternatives considered
- Infer presence from zero values: cannot preserve explicit zero-valued settings.
- Require pointers or optional wrappers everywhere: burdens application types and confuses input presence with domain nullability.
- Retain only the composed input tree: cannot explain post-decode changes.
- Automatically diff mutations without reasons: detects changes but cannot explain application intent or derivation dependencies.
Consequences
Metadata and snapshot ownership are core concerns rather than optional debugging features. Resolution hooks must participate in recording changes. Verification must compare final values, origins, and rendering, including secret treatment. This costs more than plain unmarshalling but removes repeated presence machinery from consumers and supports trustworthy inspection.