Finalize ConfigKit design and implementation plan

docs/adr/0003-preserve-presence-and-resolution-history.md

@@ -0,0 +1,43 @@
+# 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.