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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user