Plan typed value access from configuration results
This commit is contained in:
160
docs/roadmap/result-value.md
Normal file
160
docs/roadmap/result-value.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user