Files
configkit/docs/roadmap/result-value.md

161 lines
8.5 KiB
Markdown

# 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.