diff --git a/docs/releases/v1.4.0.md b/docs/releases/v1.4.0.md new file mode 100644 index 0000000..898ddcb --- /dev/null +++ b/docs/releases/v1.4.0.md @@ -0,0 +1,58 @@ +# ConfigKit v1.4.0 + +Applications can now load configuration once and pass the complete result to +libraries that select their own typed settings and reporting scope. The new APIs +reuse the original load's provenance, resource contexts, and frozen inspection +state. + +## Current typed values + +`Result.Value(path)` selects a current Go value without requiring the consumer +to know the application's root configuration type. It uses ConfigKit's existing +field bindings and semantic paths, preserving named types, terminal pointers, +and resolved `Secret` values. A present nil value succeeds; unavailable paths +return false. Lookup also works with manually constructed results and returns +terminal values without conversion or revalidation. + +This is trusted access with ordinary Go assignment semantics: maps, slices, and +pointers can share state with `Result.Config`. Later caller changes are visible +to lookup, while inspection continues to describe the completed load. Consumers +remain responsible for capturing any owned runtime settings they need. +[Value API](../../result_value.go) · [Ownership contract](../config.md#completion-and-resource-lifetime) + +## Focused inspection + +`Result.InspectSubtree(path)` returns a non-generic `Inspection` view. It renders +the selected frozen value with existing redaction, enumerates observed paths +within the scope, and forwards explanations, metadata, source records, and +resource contexts using native application paths. + +A valid absent scope can be selected for history and comparison. Rendering an +absent effective value returns an error without output; explicit null renders +normally. Numeric key and index spellings with the same canonical JSON Pointer +select the same reporting location. Explicit queries retain their normal path +intent and can address values outside the focus. Source catalogs and ancestor +evidence remain available: the view is a reporting focus, not an isolation +boundary. Scoped path enumeration avoids copying unrelated effective metadata. +[Inspection API](../../inspection_view.go) · [Inspection contract](../config.md#layered-metadata) + +`Inspection.Diff` compares views selecting the same location, including views +from different application root Go types. It uses the existing whole-snapshot +comparison and paired redaction, then retains differences at, below, or above +the focus. Sequences remain atomic: a retained ancestor difference can reflect +changes outside the selected descendant. Uninitialized views and mismatched +scopes return an error without records. Existing same-type `Diff[T]` is unchanged. +[Comparison contract](../config.md#effective-configuration-diffs) + +The maintained [one-library](../../examples/consumers/result_component.go) and +[two-library](../../examples/consumers/result_composition.go) examples demonstrate +registration, one-load handoff, owned settings capture, and resource lookup from +effective source origins. [Consumer guidance](../consumers/README.md#component-handoff) + +## Compatibility + +These APIs are additive. Existing loading, composition, inspection, and shared +source-version behavior remains unchanged; existing callers need no migration. +The Go consumer minimum remains 1.27.0. + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/oss/attribution.md)