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

Expose resolution input provenance

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-12 13:13:07 +00:00
parent 88f21d09c7
commit e20a0a0998
8 changed files with 184 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/config.md
View File

@@ -326,6 +326,27 @@ receives the working configuration and a per-load `Resolution` context. The cont
`IsExplicit` query uses surviving input presence, so explicit false, zero, empty, and
null are never confused with absence or static defaults.
`Resolution.InputInfo(path)` returns detached effective metadata from the fixed
decoded entry state, before application resolution runs. It includes retained static
defaults, preserves explicit null, and uses the same exact semantic path matching as
`Metadata.Lookup`; missing, malformed, and key/index-shape-mismatched paths return
false without diagnostics. Its `Explicit` value agrees with `IsExplicit` for every
found entry path. Resolution changes, additions, removals, and moves do not alter
this entry view.
`Resolution.Source(id)` returns a detached record for an already acquired source in
the same load: the main source, imports, selected profile, and supplied CLI records
where applicable. Empty and unknown IDs return false. It never reloads input, reads
the filesystem, resolves symlinks, or looks up credentials. A source path exists
only when the acquired source has one; defaults and byte, reader, and CLI sources do
not acquire an invented file path. Applications select a base directory from exact
origin locations and these source records according to their own policy.
Both queries are callback-scoped like the rest of `Resolution`: nil, zero, or
retained contexts panic with the fixed closed-context failure outside the callback.
Returned field and source records are detached and remain usable after callback
exit; changing them cannot affect later queries, results, or another load.
`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

5
docs/development.md
View File

@@ -46,8 +46,9 @@ The completed string-and-integer schema-version implementation and remediation
records are preserved in Git history at `244104f`. The
[configuration contract](config.md#application-schema-versions) owns current behavior.
Planned feature: [source origins during resolution](roadmap/source-origins-during-resolution.md).
This roadmap defines future behavior; its staged implementation plan is not yet written.
Current implementation work: [source origins during resolution](roadmap/source-origins-during-resolution.md)
and its [staged plan](roadmap/implementation.md). The roadmap defines target
behavior; the implementation plan records progress and handoffs.
## Baseline validation

15
docs/roadmap/implementation.md
View File

@@ -123,7 +123,7 @@ Stage 1 risks were identified.
## Stage 2 — Wire the callback API and enforce lifetime
Status: not started. Dependencies: Stage 1.
Status: complete (2026-09-12). Dependencies: Stage 1.
Scope: `load_result.go`, `resolution.go`, necessary private callers, reference
comments, and resolution/callback ownership tests.
@@ -152,6 +152,19 @@ existing mutation auditing remain unchanged.
Validation: `go test . -run 'Resolution|Callback|Metadata|Load'`, then the everyday
checker. Do not mark complete with public methods that work only in private tests.
Completion record (2026-09-12): `resolveLoadInput` now creates a
`resolutionInput` after decoded/overlay metadata and passes it explicitly into
`runResolution`; the private state retains it for the callback. `Resolution.InputInfo`
and `Resolution.Source` use the existing activity guard before exact entry lookup or
source lookup, and return detached records. Public load tests cover a canonical
file-authored value, a retained default, explicit null, misses, empty/unknown IDs,
and defaults-only input; they also cover nil, zero, successful-retained, and
failed-retained contexts plus saved record independence. Go reference comments,
the configuration contract, and the development guide now describe the active work
accurately. `go test . -run 'Resolution|Callback|Metadata|Load'` and
`./scripts/check.sh` passed with Go 1.26.7 on Linux. No deviations or remaining
Stage 2 risks were identified.
## Stage 3 — Verify layered provenance and snapshot independence
Status: not started. Dependencies: Stage 2.