# Typed value access from a result Status: agreed feature scope; not implemented. Remaining decisions are below. Baseline: v1.3.0, commit `652ddb6`. ## Purpose and baseline Let an application load configuration once and pass the whole result to libraries such as PromptKit and FeedKit. Each library selects its conventional section, checks its public settings type, and constructs its runtime objects. Section names remain library conventions, not ConfigKit reserved keys. Today, [Result.Config](../../lifecycle.go) supplies trusted typed values, but its generic root type prevents a library from selecting a field without knowing the application type or adding its own traversal. Existing metadata and [source contexts](../../resource_context.go) already support field provenance and resource lookup. Redacted inspection snapshots are not execution inputs. PromptKit has accepted this narrower direction. Its earlier request for scoped inspection and independent source-version policies is background, not acceptance criteria for this addition. Those capabilities, a component registry, and a new configuration conversion API are outside this roadmap. ## Targeted end state Add one public method: ```go func (r *Result[T]) Value(path Path) (any, bool) ``` The method selects a current value from `r.Config`. It performs no loading, decoding, defaulting, normalization, validation, resource acquisition, or secret lookup. It does not invoke application text codecs or render configuration. Libraries perform ordinary Go type assertions; ConfigKit does not convert the selected value into a requested component type. ### Values, ownership, and inspection - Return the actual terminal Go value, preserving named types, pointers, and resolved `Secret` values. Do not dereference a terminal pointer automatically. An interface contributes its current dynamic value under ordinary Go semantics. - Use ordinary Go assignment semantics. Structs and arrays are copied as values; pointers, maps, and slices can share underlying state with `Result.Config`. There is no deep-copy or additional frozen execution snapshot guarantee. - Read current configuration state, including caller changes made after loading. Existing inspection continues to describe the completed load. Document the distinction and recommend handoff before mutations invalidate that evidence; do not add mutation detection or synchronization. - This is trusted access, like `Result.Config`, and does not redact. Consumers capture owned settings where needed and use existing inspection for safe output. - A found nil pointer, map, slice, or interface is distinct from an unavailable path. In particular, `(nil, true)` is possible. A zero/defaulted struct field may be found without YAML input; source presence remains a metadata question. ### Path traversal Use the existing [Path](../../path.go) and [schema binding](../config.md#application-schema-binding) rules. The root path selects `Config`. Struct paths use YAML names or the existing default field names, including flattened inline fields and inline maps. Ignored and unexported fields do not become navigable paths. Typed scalars, including text-codec types and `Secret`, remain leaves even when their Go representation is a struct. Mapping keys and sequence indices retain their semantic distinction; parsed numeric tokens resolve according to the containing value. Check current map membership and slice/array bounds. Follow non-nil intermediate pointers and interfaces only when navigation continues. Do not allocate missing maps or pointer targets, including nil inline embeddings, to satisfy a lookup. Return `(nil, false)` for malformed paths, missing keys, out-of-range indices, incompatible segments, or traversal through nil or a scalar. Declared schema validity alone does not make a runtime descendant available. Receiver handling and dynamic values changed after loading are addressed in the open decisions. ## Consumer integration A library may define its own interface; ConfigKit need not introduce a shared interface or wrapper: ```go type Configuration interface { Value(configkit.Path) (any, bool) Metadata() configkit.Metadata SourceContext(string) (configkit.ResourceContext, bool) } ``` PromptKit selects `Value(configkit.Keys("promptkit"))` and asserts its settings type. FeedKit can use a smaller interface if it needs only values. Both receive the same application result. Paths remain application-root paths. Resource lookup uses effective field origins and original source contexts; historical evidence does not restore a lost effective origin. Before loading, library-owned helpers incorporate public settings, defaults, normalization, validation, sensitivity, and sequence identities into the application's existing `Definition[T]`. One typed field selector per library is acceptable registration wiring. Helpers preserve application rules, keep callback ordering explicit, and avoid shared mutable per-load state. Desired bundled resources enter the original load as ordinary underlays. Representative one-library and two-library probes passed using existing lifecycle APIs and a limited stand-in for `Value`. They establish feasibility, not completion of real PromptKit integration. PromptKit still owns its public settings model, presence-state handling, resource capture, and settings ownership refactoring. ## Work needed 1. Settle the open decisions and record representative lookup outcomes, including nil values and the difference between typed-value availability and input presence. 2. Add the root-owned method and reuse existing schema bindings and semantic path logic for typed traversal. Keep any supporting implementation private. Do not route through inspection projection or add another complete load-time snapshot. 3. Add focused public tests for root/nested lookup, named and pointer types, inline fields/maps, dynamic containers, numeric keys versus indices, bounds, missing/nil values, scalar leaves, and the selected receiver/mutation rules. Verify ordinary aliasing and unchanged frozen inspection without promising concurrent mutation safety. Check trusted secret access and existing redaction with disposable values. 4. Add maintained one-library and two-library consumer examples. Demonstrate one load, typed registration, whole-result handoff, composed callbacks and identity checks, and resource contexts retained through placement and existing structural operations. Keep library-specific runtime construction outside ConfigKit. 5. Document the method beside its declaration, extend the configuration ownership contract and consumer guidance, and run the relevant public tests and normal repository checks. This is an additive API; existing loading, inspection, comparison, and shared source-version behavior remain as documented. Completion means both representative library consumers can obtain their typed settings and existing provenance from one application result without application extraction, reshaping, serialization, or a second load. No new scoped reporting or independently versioned source support is required for completion. ## Open Decisions ### OD-1: Nil and manually constructed results **Recommendation:** return `(nil, false)` for a nil receiver or a result without successful-load inspection state, including `&Result[T]{Config: value}`. This keeps the method on the completed-result boundary and consistent with the inspection methods a library may use alongside it. This is a proposed eligibility rule, not a claim that caller changes to a successful result are revalidated. **Alternative:** allow any non-nil result to expose its `Config`, even without load state. This matches direct field access and simplifies hand-built fixtures, but a library can then obtain values from a result with no corresponding load evidence. Nil receivers would still return `(nil, false)`. ### OD-2: Traversal after arbitrary changes inside `any` **Recommendation:** navigate current dynamic values using ConfigKit's supported dynamic container shapes. Return false if further traversal needs an unsupported shape. At a reached terminal, return the current value without revalidating it; lookup is not a new configuration validation pass. This follows current-value ownership while reusing ConfigKit's existing navigation model. **Alternative:** reflect through arbitrary Go shapes inserted into `any` after loading, including new struct types. This offers more flexibility for mutated results, but requires additional runtime binding and failure rules for values the load never supported. Neither demonstrated consumer needs that expansion.