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

245 lines
14 KiB
Markdown

# Typed value access and focused inspection from a result
Status: agreed feature scope; OD-1 through OD-5 settled; not implemented.
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.
The inspection comparison extension is recorded in
[ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md), which
extends [ADR 0010](../adr/0010-effective-configuration-diff.md).
### 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
**OD-3 settled:** provide a non-generic `Inspection` view, selected once from a
result:
```go
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
func (i Inspection) Diff(other Inspection) ([]Difference, error)
```
For example:
```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.
`InspectSubtree` returns false for a nil result, unavailable completed-load
inspection state, or malformed path. A valid absent scope succeeds. The root
path selects the whole configuration. Use familiar methods: `WriteEffective`,
`Explain`, `WriteExplanation`, `Metadata`, `Sources`, `Source`, and `SourceContext`.
The view's `HistoricalPaths` provides focused enumeration; `Metadata()` retains
its existing unfiltered query behavior. Effective presence is checked with
metadata lookup. Forwarded operations retain their existing unavailable-state
behavior for a zero view.
- **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.
**OD-4 settled:** if no selected effective value exists, `WriteEffective` returns
an error without output. Explicit null renders normally. An absent value does
not invalidate the view or prevent history, queries, or comparison. Ordinary
writer failures retain existing behavior and may leave partial output.
- **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. Compare views selecting the same native application path;
uninitialized views or mismatched scopes return an error and no differences.
Compare snapshots regardless of the original application Go root types, without
adding runtime root-type tracking or compatibility checks. Existing `Diff[T]`
retains its signature and same-type contract. Cross-location comparison is
not part of 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.
Reuse existing public result types such as `Explanation`, `Difference`, and
`ValueSnapshot`. No new confidentiality, deep-copy, or concurrent-mutation
guarantee is implied.
**OD-5 settled:** identify the view's reporting scope by canonical JSON Pointer
location. Normalize the constructor's valid path to that contextual selector;
numeric tokens follow the containing shape when rendering effective output.
Use the same location and segment-aware containment for focused enumeration,
diff filtering, and scope equality, rather than raw string-prefix matching.
For example, `Keys("items", "0")`, `Keys("items").Index(0)`, and a parsed
`/items/0` all select the same reporting scope. This follows historical reporting's
location model and does not require a present value to establish scope identity.
Document this behavior on `InspectSubtree`. Explicit `Value`, `Explain`, and
metadata queries retain their existing key/index intent and contextual traversal
rules; the view does not rewrite those query paths.
## 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.
## Delivery scope and completion
The [implementation plan](implementation.md) owns execution order and validation.
The change includes private typed traversal using existing schema bindings, the
root-owned value accessor and inspection view, focused behavioral coverage,
maintained one-library and two-library examples, and updates to the public
contracts and consumer guidance. Architecture and comparison documentation will
reflect ADR 0024 when its implementation lands.
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.