eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Unify layered provenance history

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-06 21:09:52 +00:00
parent ef0e6078f7
commit 26cece6d53
9 changed files with 347 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/config.md
View File

@@ -79,7 +79,7 @@ error without reporting one, ConfigKit emits a generic `version.hook_failed`
diagnostic and suppresses the returned error text. Warnings alone are retained on a
successful result. Callback panics remain programming failures.
### Layered input/default metadata
### Layered metadata
`Result.Metadata` describes every final canonical path. Exact surviving input paths
are explicit and have a base or profile origin; omitted paths have a default origin.
@@ -91,6 +91,23 @@ metadata while retaining their base definition and the parent replacement operat
in history.
All metadata queries and returned nested records are detached.
History is chronological: a path can have a synthetic default record, its exact base
definition, a profile replacement, and a recorded resolution operation. A descendant
query uses the ancestor's path for a whole-container or whole-sequence replacement;
the descendant can therefore retain history after `Lookup` stops reporting it as
effective. Equal-valued input is still an explicit base definition, while a derived
value for absent input remains non-explicit.
A mapping assembled from the selected file and imports has one composite base origin
whose locations retain source traversal order. A mapping also visited by a profile
has a profile-layer composite origin with the lower contributing locations followed
by the profile location; an empty mapping is still an explicit container even though
it contributes no children. Resolution origins are synthetic: they have layer
`resolution`, no fabricated file location, and a `derived_default` or `normalization`
operation. Reasons and dependency paths retain first occurrence order with duplicates
removed. Source records remain ordered as selected source, depth-first imports, then
the selected profile.
### Recorded application resolution
An optional `Definition.Resolve` callback runs after successful typed decoding. It