Add focused inspection to the result access roadmap
This commit is contained in:
@@ -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.
|
Status: agreed feature scope; not implemented. Remaining decisions are below.
|
||||||
Baseline: v1.3.0, commit `652ddb6`.
|
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
|
Let an application load configuration once and pass the whole result to libraries
|
||||||
such as PromptKit and FeedKit. Each library selects its conventional section,
|
such as PromptKit and FeedKit. Each library selects its conventional section,
|
||||||
checks its public settings type, and constructs its runtime objects. Section
|
checks its public settings type, and constructs its runtime objects. Libraries
|
||||||
names remain library conventions, not ConfigKit reserved keys.
|
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
|
Today, [Result.Config](../../lifecycle.go) supplies trusted typed values, but its
|
||||||
generic root type prevents a library from selecting a field without knowing the
|
generic root type prevents a library from selecting a field without knowing the
|
||||||
application type or adding its own traversal. Existing metadata and
|
application type or adding its own traversal. Existing metadata and
|
||||||
[source contexts](../../resource_context.go) already support field provenance 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
|
PromptKit has accepted the typed-value direction. The subsequently agreed
|
||||||
inspection and independent source-version policies is background, not acceptance
|
inspection addition supports libraries such as PromptKit that expose an
|
||||||
criteria for this addition. Those capabilities, a component registry, and a new
|
`InspectConfiguration()` API and want its ordinary reports to focus on their own
|
||||||
configuration conversion API are outside this roadmap.
|
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
|
## 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
|
```go
|
||||||
func (r *Result[T]) Value(path Path) (any, bool)
|
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
|
validity alone does not make a runtime descendant available. Receiver handling
|
||||||
and dynamic values changed after loading are addressed in the open decisions.
|
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
|
## Consumer integration
|
||||||
|
|
||||||
A library may define its own interface; ConfigKit need not introduce a shared
|
A library may define its own input interface; ConfigKit need not introduce a
|
||||||
interface or wrapper:
|
shared component interface or configuration wrapper:
|
||||||
|
|
||||||
```go
|
```go
|
||||||
type Configuration interface {
|
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
|
uses effective field origins and original source contexts; historical evidence
|
||||||
does not restore a lost effective origin.
|
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,
|
Before loading, library-owned helpers incorporate public settings, defaults,
|
||||||
normalization, validation, sensitivity, and sequence identities into the
|
normalization, validation, sensitivity, and sequence identities into the
|
||||||
application's existing `Definition[T]`. One typed field selector per library is
|
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
|
## Work needed
|
||||||
|
|
||||||
1. Settle the open decisions and record representative lookup outcomes, including
|
1. Settle the open decisions and record representative lookup and reporting
|
||||||
nil values and the difference between typed-value availability and input presence.
|
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
|
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
|
logic for typed traversal. Keep any supporting implementation private. Do not
|
||||||
route through inspection projection or add another complete load-time snapshot.
|
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
|
Verify ordinary aliasing and unchanged frozen inspection without promising
|
||||||
concurrent mutation safety. Check trusted secret access and existing redaction
|
concurrent mutation safety. Check trusted secret access and existing redaction
|
||||||
with disposable values.
|
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
|
load, typed registration, whole-result handoff, composed callbacks and identity
|
||||||
checks, and resource contexts retained through placement and existing structural
|
checks, and resource contexts retained through placement and existing structural
|
||||||
operations. Keep library-specific runtime construction outside ConfigKit.
|
operations. Include a library-owned inspection facade that selects its scope
|
||||||
5. Document the method beside its declaration, extend the configuration ownership
|
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
|
contract and consumer guidance, and run the relevant public tests and normal
|
||||||
repository checks. This is an additive API; existing loading, inspection,
|
repository checks. This is an additive API; existing loading, inspection,
|
||||||
comparison, and shared source-version behavior remain as documented.
|
comparison, and shared source-version behavior remain as documented.
|
||||||
|
|
||||||
Completion means both representative library consumers can obtain their typed
|
Completion means both representative library consumers can obtain their typed
|
||||||
settings and existing provenance from one application result without application
|
settings and existing provenance from one application result without application
|
||||||
extraction, reshaping, serialization, or a second load. No new scoped reporting
|
extraction, reshaping, serialization, or a second load, and a library can offer
|
||||||
or independently versioned source support is required for completion.
|
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
|
## 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
|
loading, including new struct types. This offers more flexibility for mutated
|
||||||
results, but requires additional runtime binding and failure rules for values
|
results, but requires additional runtime binding and failure rules for values
|
||||||
the load never supported. Neither demonstrated consumer needs that expansion.
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user