44 lines
1.8 KiB
Markdown
44 lines
1.8 KiB
Markdown
# 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](../policy/architecture.md) owns these invariants; the
|
|
[target design](../roadmap/initial.md#recorded-resolution-and-validation) 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.
|