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
|
|
|
|
|
|
|
|
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,
|
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
|
|
|
|
|
|
|
|
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
|
2026-11-21 03:00:57 +00:00
|
|
|
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.
|
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
|
|
|
|
|
configuration. The earlier broader request remains background. 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.
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
|
|
|
|
|
Provide a small inspection-view object, selected once from a result. The intended
|
|
|
|
|
usage is illustrative pending the public-shape decision below:
|
|
|
|
|
|
|
|
|
|
```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.
|
|
|
|
|
|
|
|
|
|
- **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.
|
|
|
|
|
- **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. Cross-location comparison is not needed for 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.
|
|
|
|
|
Use semantic paths for scope matching, including segment boundaries and existing
|
|
|
|
|
numeric-token behavior, rather than raw string-prefix matching. Reuse existing
|
|
|
|
|
public result types such as `Explanation`, `Difference`, and `ValueSnapshot`.
|
|
|
|
|
No new confidentiality, deep-copy, or concurrent-mutation guarantee is implied.
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Work needed
|
|
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
1. Settle the open decisions and record representative lookup and reporting
|
|
|
|
|
outcomes, including nil values, absent scopes, and the difference between
|
|
|
|
|
typed-value availability and input presence.
|
2026-11-21 02:26:31 +00:00
|
|
|
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,
|
2026-11-21 03:12:59 +00:00
|
|
|
inline fields/maps, dynamic containers and supported structs inside `any`,
|
|
|
|
|
numeric keys versus indices, bounds, missing/nil values, scalar leaves, and
|
|
|
|
|
the settled receiver/mutation rules, including manually constructed results.
|
2026-11-21 02:26:31 +00:00
|
|
|
Verify ordinary aliasing and unchanged frozen inspection without promising
|
|
|
|
|
concurrent mutation safety. Check trusted secret access and existing redaction
|
|
|
|
|
with disposable values.
|
2026-11-21 03:00:57 +00:00
|
|
|
4. Add the root-owned inspection view over existing private inspection state.
|
|
|
|
|
Reuse explanations, metadata, source queries, rendering, and comparison;
|
|
|
|
|
add only subtree rendering and reporting selection where needed. Keep
|
|
|
|
|
whole-result APIs unchanged. Preserve original paths and sensitivity context.
|
|
|
|
|
5. Add focused inspection checks for absent, null, and historical-only sections;
|
|
|
|
|
subtree output and discovery; native-path queries outside the focus; ancestor
|
|
|
|
|
history and differences; source-context continuity; and sensitivity inherited
|
|
|
|
|
from ancestors or either compared result. Check sibling path names and numeric
|
|
|
|
|
path segments. Verify frozen behavior after caller mutation and unchanged
|
|
|
|
|
whole-result inspection. Include a comparison where the section exists on
|
|
|
|
|
only one side.
|
|
|
|
|
6. Add maintained one-library and two-library consumer examples. Demonstrate one
|
2026-11-21 02:26:31 +00:00
|
|
|
load, typed registration, whole-result handoff, composed callbacks and identity
|
|
|
|
|
checks, and resource contexts retained through placement and existing structural
|
2026-11-21 03:00:57 +00:00
|
|
|
operations. Include a library-owned inspection facade that selects its scope
|
|
|
|
|
once and forwards focused reports and explicit queries. Keep library-specific
|
|
|
|
|
runtime construction outside ConfigKit.
|
|
|
|
|
7. Document the APIs beside their declarations, extend the configuration ownership
|
2026-11-21 02:26:31 +00:00
|
|
|
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
|
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.
|
2026-11-21 02:26:31 +00:00
|
|
|
|
|
|
|
|
## Open Decisions
|
|
|
|
|
|
2026-11-21 03:00:57 +00:00
|
|
|
### OD-3: Inspection view and comparison API
|
|
|
|
|
|
|
|
|
|
**Recommendation:** expose a non-generic `Inspection` view through
|
|
|
|
|
`InspectSubtree(path Path) (Inspection, bool)`. Return false for an unavailable
|
|
|
|
|
completed-load snapshot or malformed path, not for an absent selected value.
|
|
|
|
|
Use familiar method names for effective output, explanations, metadata, source
|
|
|
|
|
queries, and focused historical-path enumeration. Keep `Metadata()` unchanged;
|
|
|
|
|
the view's enumeration supplies the reporting focus.
|
|
|
|
|
|
|
|
|
|
Provide comparison between views with the same selected native path, retaining
|
|
|
|
|
the existing same-root-configuration-type comparison boundary. Because the view
|
|
|
|
|
erases the application's Go type, that compatibility check would occur at
|
|
|
|
|
runtime. This allows a library to forward inspection without knowing the root
|
|
|
|
|
type, while avoiding an incidental expansion into cross-type or cross-location
|
|
|
|
|
comparison. The exact method signature and zero-view error behavior should be
|
|
|
|
|
recorded before implementation; existing whole-result `Diff` remains unchanged.
|
|
|
|
|
|
|
|
|
|
**Alternative:** make the view generic in the application's root type and offer
|
|
|
|
|
a generic comparison function, retaining compile-time comparison compatibility.
|
|
|
|
|
This follows the current `Diff[T]` shape, but complicates the consumer-owned
|
|
|
|
|
interface used by a library that does not know the root type. A separate adapter
|
|
|
|
|
or comparison callback would then be needed for that library's inspection API.
|
|
|
|
|
|
|
|
|
|
Another viable alternative is a non-generic view with structural comparison
|
|
|
|
|
regardless of the original Go root types. It avoids runtime type-checking
|
|
|
|
|
machinery and reuses the engine's snapshot comparison, but broadens the new
|
|
|
|
|
comparison API beyond the existing same-type contract. This is a public-scope
|
|
|
|
|
choice, not a correctness requirement imposed by subtree selection.
|
|
|
|
|
|
|
|
|
|
### OD-4: Effective output for an absent selected value
|
|
|
|
|
|
|
|
|
|
**Recommendation:** let the view remain valid, but have `WriteEffective` return
|
|
|
|
|
an error without output when the selected effective value is absent. Continue
|
|
|
|
|
to permit history, explanations, enumeration, and comparison. Render explicit
|
|
|
|
|
null normally. This preserves the distinction between an absent value and a
|
|
|
|
|
renderable null without adding a new output format or presence return value.
|
|
|
|
|
|
|
|
|
|
**Alternative:** treat absence as successful empty output. This is convenient
|
|
|
|
|
for optional-section reports and avoids special caller error handling, but a
|
|
|
|
|
successful render no longer necessarily contains a YAML value. Presence would
|
|
|
|
|
still need to be checked through existing queries when that distinction matters.
|