Add focused inspection to the result access roadmap

This commit is contained in:
2026-11-21 03:00:57 +00:00
parent 472ac551c2
commit 48e7f943d9

View File

@@ -1,4 +1,4 @@
# Typed value access from a result
# Typed value access and focused inspection from a result
Status: agreed feature scope; not implemented. Remaining decisions are below.
Baseline: v1.3.0, commit `652ddb6`.
@@ -7,23 +7,33 @@ Baseline: v1.3.0, commit `652ddb6`.
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.
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. Redacted inspection snapshots are not execution inputs.
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 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.
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 one public method:
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:
```go
func (r *Result[T]) Value(path Path) (any, bool)
@@ -73,10 +83,58 @@ 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.
### 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.
## Consumer integration
A library may define its own interface; ConfigKit need not introduce a shared
interface or wrapper:
A library may define its own input interface; ConfigKit need not introduce a
shared component interface or configuration wrapper:
```go
type Configuration interface {
@@ -92,6 +150,14 @@ the same application result. Paths remain application-root paths. Resource looku
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
@@ -106,8 +172,9 @@ 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.
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.
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.
@@ -117,19 +184,34 @@ presence-state handling, resource capture, and settings ownership refactoring.
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
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
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
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
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.
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.
## Open Decisions
@@ -158,3 +240,45 @@ ownership while reusing ConfigKit's existing navigation model.
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.
### 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.