Add audited application resolution

docs/config.md

@@ -47,8 +47,8 @@ version checker, contributes no source, and continues through defaults, decode,
 projection. A missing file remains an error; it is never interpreted as no input.
 
 The current `Options` boundary accepts a defaults factory and `VersionRule`.
-Imports, active profiles, filesystem context, overrides, resolver and semantic
-validator callbacks, and dynamic secret classification return an explicit
+Imports, active profiles, filesystem context, overrides, semantic validator
+callbacks, and dynamic secret classification return an explicit
 `options.unavailable` error because their lifecycle stages are not implemented.
 The reserved profile spelling `default` selects no active profile. `NoSource`
 additionally rejects imports, active profiles, and filesystem context as invalid
@@ -84,6 +84,44 @@ source coordinates are retained. `History` records the Go-zero or application
 default baseline followed by exact base definitions, including equal-valued input.
 All metadata queries and returned nested records are detached.
 
+### Recorded application resolution
+
+An optional `Definition.Resolve` callback runs after successful typed decoding. It
+receives the working configuration and a per-load `Resolution` context. The context's
+`IsExplicit` query uses surviving input presence, so explicit false, zero, empty, and
+null are never confused with absence or static defaults.
+
+`Default` assigns and records a derived value only when its path is not explicit.
+`Normalize` always assigns and records. For transformations performed directly by
+application code, `Resolution.Record` declares a derived-default or normalization
+operation; a recorded container covers changes to its descendants. Records require
+a schema-valid path, valid kind, safe nonempty reason, and schema-valid dependency
+paths. Repeated records at one path are coalesced: reasons and dependencies retain
+their first occurrence, the last helper value is authoritative, and any normalization
+makes the combined operation a normalization.
+
+ConfigKit projects the configuration before and after the callback. Every net change
+must have an exact or ancestor record. Helper-assigned values must agree with the
+final value at their declared path, which supports ordinary map-entry copy/writeback
+while detecting forgotten writeback or unrelated targets. Invalid paths, kinds,
+values, records, helper targets, and unrecorded mutations fail the load. Equal-valued
+derived assignments may still record application intent even when there is no
+structural change.
+
+`Resolution.Error` and `Resolution.Warning` attach exact or nearest available input
+locations. Reported errors fail the load; warnings survive on a successful result. A
+returned resolver error adds one generic `resolve.hook_failed` error only when the
+callback did not report an error, and its text is never exposed. Callback panics are
+programming failures. Resolution and validation contexts are callback-scoped; using
+a nil, zero, or retained context outside its active callback panics with fixed,
+value-free text.
+
+Successful records update effective origins and append detached metadata history
+without changing input explicitness. Removed paths leave effective metadata but
+retain history. ConfigKit privately snapshots each recorded before/after subtree for
+later safe explanation; caller mutations of `Result.Config` cannot alter those
+snapshots.
+
 ## YAML documents
 
 The private YAML boundary currently accepts exactly one nonempty document whose root