diff --git a/docs/roadmap/result-value.md b/docs/roadmap/result-value.md new file mode 100644 index 0000000..9f1dcc2 --- /dev/null +++ b/docs/roadmap/result-value.md @@ -0,0 +1,160 @@ +# 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.