# Typed value access and focused inspection 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. Libraries can also offer inspection focused on their section. 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. Existing inspection and comparison operate on completed-load snapshots, but there is no reusable subtree reporting view. Redacted inspection snapshots are not execution inputs. PromptKit has accepted the typed-value direction. The subsequently agreed inspection addition supports libraries such as PromptKit that expose an `InspectConfiguration()` API and want its ordinary reports to focus on their own configuration. The earlier broader request remains background. Independent source-version policies, a component registry, and a new configuration conversion API remain outside this roadmap. ## Targeted end state Add two complementary capabilities: trusted access to current typed settings, and a lightweight reporting view over existing frozen inspection state. ### Typed value access Add the 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. - **OD-1 settled:** return `(nil, false)` for a nil receiver. Any non-nil result exposes its current `Config` through the same traversal rules, including a manually constructed result without load or inspection state. Lookup success establishes value availability only, not validation or corresponding load evidence. This matches direct field access and supports hand-built fixtures without coupling typed access to inspection. `InspectSubtree` still requires completed-load inspection state. ### 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. **OD-2 settled:** navigate current values inside `any` using ConfigKit's existing supported types and field-binding rules, including supported structs and their YAML field names. Apply the same rules to values supplied during loading, post-load replacements, and manually constructed results. Reuse existing runtime type-description machinery as appropriate; do not restrict navigation to YAML-decoded maps and slices or introduce a second Go-object navigation model. Intermediate pointers and interfaces follow the rules above, and scalar types remain leaves. Return `(nil, false)` when continued traversal requires an unsupported shape. At a reached terminal, return the actual current value without conversion or revalidation. Lookup does not invoke application codecs or establish new secret-classification semantics. ### Subtree-focused inspection Provide a small inspection-view object, selected once from a result. The intended usage is illustrative pending the public-shape decision below: ```go inspection, ok := result.InspectSubtree(configkit.Keys("promptkit")) ``` The view retains existing completed-load inspection state and a selected path. It does not load, decode, resolve, validate, or create another execution snapshot. Later changes to `Result.Config` do not change its evidence. It is a reporting focus, not an access-control or isolation boundary. - **Effective output:** render the selected subtree using existing frozen values and redaction, without the enclosing application mappings. Preserve sensitivity inherited from ancestors; do not reclassify an extracted value as a new root. - **Path discovery:** enumerate existing effective and historical paths at or beneath the selected path, retaining existing ordering and path semantics. Reuse historical enumeration and effective lookup rather than introducing another path inventory. - **Explicit queries:** explanation, explanation rendering, metadata lookup, and history queries use native application paths and existing behavior. Explicit queries may name paths outside the selected subtree. Existing metadata can remain available unchanged; focused enumeration belongs to the view. - **Context:** retain existing source IDs, locations, source catalogs, and resource contexts. Do not determine exclusive source ownership by subtree. Ancestor snapshots, dependency references, and other contextual evidence may include configuration outside the focus. Do not trim or rewrite that evidence. - **Comparison:** compare original frozen configurations with the existing diff behavior, then retain differences at, beneath, or above the selected path. Preserve sequence-atomic comparison, ordering, equality, paired redaction, and existing difference records. An ancestor difference can reflect changes outside the focus: a nonempty report does not necessarily mean the selected values themselves changed. Cross-location comparison is not needed for this addition. - **Absent scopes:** selecting a scope does not assert current or historical presence. A valid path can select an absent, historical-only, or explicit-null section. This supports optional sections and comparisons where a section was added or removed. Constructor success must not mean current value presence; ordinary queries retain their existing absence and null distinctions. Keep native application paths throughout; for example, `/promptkit/prompts` remains `/promptkit/prompts` in queries, explanations, history, and differences. Use semantic paths for scope matching, including segment boundaries and existing numeric-token behavior, rather than raw string-prefix matching. Reuse existing public result types such as `Explanation`, `Difference`, and `ValueSnapshot`. No new confidentiality, deep-copy, or concurrent-mutation guarantee is implied. ## Consumer integration A library may define its own input interface; ConfigKit need not introduce a shared component interface or configuration 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. A library that offers inspection can additionally request `InspectSubtree` through its consumer-owned interface and retain the returned view. PromptKit can forward the focused operations through `InspectConfiguration()` without constructing or loading another configuration. Its adapter may still need changes for native application paths and the agreed broader contextual evidence; this roadmap does not promise unchanged downstream method signatures. The view is separate from `Result[T]`, not a partially populated result or a new typed configuration. 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 and reporting outcomes, including nil values, absent scopes, 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 and supported structs inside `any`, numeric keys versus indices, bounds, missing/nil values, scalar leaves, and the settled receiver/mutation rules, including manually constructed results. Verify ordinary aliasing and unchanged frozen inspection without promising concurrent mutation safety. Check trusted secret access and existing redaction with disposable values. 4. Add the root-owned inspection view over existing private inspection state. Reuse explanations, metadata, source queries, rendering, and comparison; add only subtree rendering and reporting selection where needed. Keep whole-result APIs unchanged. Preserve original paths and sensitivity context. 5. Add focused inspection checks for absent, null, and historical-only sections; subtree output and discovery; native-path queries outside the focus; ancestor history and differences; source-context continuity; and sensitivity inherited from ancestors or either compared result. Check sibling path names and numeric path segments. Verify frozen behavior after caller mutation and unchanged whole-result inspection. Include a comparison where the section exists on only one side. 6. 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. Include a library-owned inspection facade that selects its scope once and forwards focused reports and explicit queries. Keep library-specific runtime construction outside ConfigKit. 7. Document the APIs beside their declarations, 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, and a library can offer focused inspection using the same completed result. Independently versioned source support is not required. The intended release is additive: existing loading and inspection callers need not adopt either new capability. ## Open Decisions ### OD-3: Inspection view and comparison API **Recommendation:** expose a non-generic `Inspection` view through `InspectSubtree(path Path) (Inspection, bool)`. Return false for an unavailable completed-load snapshot or malformed path, not for an absent selected value. Use familiar method names for effective output, explanations, metadata, source queries, and focused historical-path enumeration. Keep `Metadata()` unchanged; the view's enumeration supplies the reporting focus. Provide comparison between views with the same selected native path, retaining the existing same-root-configuration-type comparison boundary. Because the view erases the application's Go type, that compatibility check would occur at runtime. This allows a library to forward inspection without knowing the root type, while avoiding an incidental expansion into cross-type or cross-location comparison. The exact method signature and zero-view error behavior should be recorded before implementation; existing whole-result `Diff` remains unchanged. **Alternative:** make the view generic in the application's root type and offer a generic comparison function, retaining compile-time comparison compatibility. This follows the current `Diff[T]` shape, but complicates the consumer-owned interface used by a library that does not know the root type. A separate adapter or comparison callback would then be needed for that library's inspection API. Another viable alternative is a non-generic view with structural comparison regardless of the original Go root types. It avoids runtime type-checking machinery and reuses the engine's snapshot comparison, but broadens the new comparison API beyond the existing same-type contract. This is a public-scope choice, not a correctness requirement imposed by subtree selection. ### OD-4: Effective output for an absent selected value **Recommendation:** let the view remain valid, but have `WriteEffective` return an error without output when the selected effective value is absent. Continue to permit history, explanations, enumeration, and comparison. Render explicit null normally. This preserves the distinction between an absent value and a renderable null without adding a new output format or presence return value. **Alternative:** treat absence as successful empty output. This is convenient for optional-section reports and avoids special caller error handling, but a successful render no longer necessarily contains a YAML value. Presence would still need to be checked through existing queries when that distinction matters.