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