2026-11-21 03:00:57 +00:00
|
|
|
# Typed value access and focused inspection from a result
|
2026-11-21 02:26:31 +00:00
|
|
|
|
2026-11-21 04:16:46 +00:00
|
|
|
Status: implemented; OD-1 through OD-5 settled. See the current
|
|
|
|
|
[configuration contract](../config.md) and declaration comments for behavior.
|
2026-11-21 02:26:31 +00:00
|
|
|
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,
|
2026-11-21 03:00:57 +00:00
|
|
|
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.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
2026-11-21 04:16:46 +00:00
|
|
|
At the baseline, [Result.Config](../../lifecycle.go) supplied trusted typed values, but its
|
|
|
|
|
generic root type prevented a library from selecting a field without knowing the
|
2026-11-21 02:26:31 +00:00
|
|
|
application type or adding its own traversal. Existing metadata and
|
|
|
|
|
[source contexts](../../resource_context.go) already support field provenance and
|
2026-11-21 04:16:46 +00:00
|
|
|
resource lookup. Baseline inspection and comparison operated on completed-load
|
|
|
|
|
snapshots, but there was no reusable subtree reporting view. Redacted inspection
|
2026-11-21 03:00:57 +00:00
|
|
|
snapshots are not execution inputs.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
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
|
2026-11-21 04:00:27 +00:00
|
|
|
configuration. Independent source-version policies, a component registry, and a
|
|
|
|
|
new configuration conversion API remain outside this roadmap.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
|
|
|
|
## Targeted end state
|
|
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
Add two complementary capabilities: trusted access to current typed settings,
|
|
|
|
|
and a lightweight reporting view over existing frozen inspection state.
|
2026-11-21 03:37:15 +00:00
|
|
|
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).
|
2026-11-21 03:00:57 +00:00
|
|
|
|
|
|
|
|
### Typed value access
|
|
|
|
|
|
|
|
|
|
Add the public method:
|
2026-11-21 02:26:31 +00:00
|
|
|
|
|
|
|
|
```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.
|
2026-11-21 03:07:14 +00:00
|
|
|
- **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.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
|
|
|
|
### 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
|
2026-11-21 03:12:59 +00:00
|
|
|
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.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
### Subtree-focused inspection
|
|
|
|
|
|
2026-11-21 03:17:32 +00:00
|
|
|
**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:
|
2026-11-21 03:00:57 +00:00
|
|
|
|
|
|
|
|
```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.
|
|
|
|
|
|
2026-11-21 03:17:32 +00:00
|
|
|
`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.
|
|
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
- **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.
|
2026-11-21 03:17:32 +00:00
|
|
|
**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.
|
2026-11-21 03:00:57 +00:00
|
|
|
- **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
|
2026-11-21 03:17:32 +00:00
|
|
|
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.
|
2026-11-21 03:00:57 +00:00
|
|
|
- **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.
|
2026-11-21 03:20:20 +00:00
|
|
|
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.
|
2026-11-21 03:00:57 +00:00
|
|
|
|
2026-11-21 02:26:31 +00:00
|
|
|
## Consumer integration
|
|
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
A library may define its own input interface; ConfigKit need not introduce a
|
|
|
|
|
shared component interface or configuration wrapper:
|
2026-11-21 02:26:31 +00:00
|
|
|
|
|
|
|
|
```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.
|
|
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 02:26:31 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 03:54:39 +00:00
|
|
|
## 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.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
|
|
|
|
Completion means both representative library consumers can obtain their typed
|
|
|
|
|
settings and existing provenance from one application result without application
|
2026-11-21 03:00:57 +00:00
|
|
|
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.
|