Settle inspection APIs and review roadmap consistency

This commit is contained in:
2026-11-21 03:17:32 +00:00
parent 4c2620c68b
commit d11e749428

View File

@@ -1,6 +1,7 @@
# Typed value access and focused inspection 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; OD-1 through OD-4 settled; not implemented.
A path-scope clarification from the coherence review remains below.
Baseline: v1.3.0, commit `652ddb6`. Baseline: v1.3.0, commit `652ddb6`.
## Purpose and baseline ## Purpose and baseline
@@ -103,8 +104,15 @@ or establish new secret-classification semantics.
### Subtree-focused inspection ### Subtree-focused inspection
Provide a small inspection-view object, selected once from a result. The intended **OD-3 settled:** provide a non-generic `Inspection` view, selected once from a
usage is illustrative pending the public-shape decision below: result:
```go
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
func (i Inspection) Diff(other Inspection) ([]Difference, error)
```
For example:
```go ```go
inspection, ok := result.InspectSubtree(configkit.Keys("promptkit")) inspection, ok := result.InspectSubtree(configkit.Keys("promptkit"))
@@ -115,9 +123,22 @@ It does not load, decode, resolve, validate, or create another execution snapsho
Later changes to `Result.Config` do not change its evidence. It is a reporting Later changes to `Result.Config` do not change its evidence. It is a reporting
focus, not an access-control or isolation boundary. focus, not an access-control or isolation boundary.
`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.
- **Effective output:** render the selected subtree using existing frozen values - **Effective output:** render the selected subtree using existing frozen values
and redaction, without the enclosing application mappings. Preserve sensitivity and redaction, without the enclosing application mappings. Preserve sensitivity
inherited from ancestors; do not reclassify an extracted value as a new root. inherited from ancestors; do not reclassify an extracted value as a new root.
**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.
- **Path discovery:** enumerate existing effective and historical paths at or - **Path discovery:** enumerate existing effective and historical paths at or
beneath the selected path, retaining existing ordering and path semantics. beneath the selected path, retaining existing ordering and path semantics.
Reuse historical enumeration and effective lookup rather than introducing Reuse historical enumeration and effective lookup rather than introducing
@@ -135,7 +156,12 @@ focus, not an access-control or isolation boundary.
Preserve sequence-atomic comparison, ordering, equality, paired redaction, and Preserve sequence-atomic comparison, ordering, equality, paired redaction, and
existing difference records. An ancestor difference can reflect changes outside existing difference records. An ancestor difference can reflect changes outside
the focus: a nonempty report does not necessarily mean the selected values the focus: a nonempty report does not necessarily mean the selected values
themselves changed. Cross-location comparison is not needed for this addition. 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.
- **Absent scopes:** selecting a scope does not assert current or historical - **Absent scopes:** selecting a scope does not assert current or historical
presence. A valid path can select an absent, historical-only, or explicit-null presence. A valid path can select an absent, historical-only, or explicit-null
section. This supports optional sections and comparisons where a section was section. This supports optional sections and comparisons where a section was
@@ -144,8 +170,8 @@ focus, not an access-control or isolation boundary.
Keep native application paths throughout; for example, `/promptkit/prompts` Keep native application paths throughout; for example, `/promptkit/prompts`
remains `/promptkit/prompts` in queries, explanations, history, and differences. remains `/promptkit/prompts` in queries, explanations, history, and differences.
Use semantic paths for scope matching, including segment boundaries and existing Use path segment boundaries for scope matching rather than raw string-prefix
numeric-token behavior, rather than raw string-prefix matching. Reuse existing matching. OD-5 addresses numeric scope tokens and scope equality. Reuse existing
public result types such as `Explanation`, `Difference`, and `ValueSnapshot`. public result types such as `Explanation`, `Difference`, and `ValueSnapshot`.
No new confidentiality, deep-copy, or concurrent-mutation guarantee is implied. No new confidentiality, deep-copy, or concurrent-mutation guarantee is implied.
@@ -190,7 +216,7 @@ presence-state handling, resource capture, and settings ownership refactoring.
## Work needed ## Work needed
1. Settle the open decisions and record representative lookup and reporting 1. Settle OD-5 and record representative lookup and reporting
outcomes, including nil values, absent scopes, and the difference between outcomes, including nil values, absent scopes, and the difference between
typed-value availability and input presence. 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
@@ -212,8 +238,8 @@ presence-state handling, resource capture, and settings ownership refactoring.
history and differences; source-context continuity; and sensitivity inherited history and differences; source-context continuity; and sensitivity inherited
from ancestors or either compared result. Check sibling path names and numeric from ancestors or either compared result. Check sibling path names and numeric
path segments. Verify frozen behavior after caller mutation and unchanged path segments. Verify frozen behavior after caller mutation and unchanged
whole-result inspection. Include a comparison where the section exists on whole-result inspection. Include comparisons between different root Go types,
only one side. a section existing on only one side, mismatched scopes, and zero views.
6. Add maintained one-library and two-library consumer examples. Demonstrate one 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
@@ -224,6 +250,10 @@ presence-state handling, resource capture, and settings ownership refactoring.
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.
Clarify the distinction between same-type `Diff[T]` and structural view
comparison in the architecture policy and comparison documentation. Record
the extension to [ADR 0010](../adr/0010-effective-configuration-diff.md) through
the ADR process, preserving its accepted decision content.
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
@@ -234,44 +264,29 @@ loading and inspection callers need not adopt either new capability.
## Open Decisions ## Open Decisions
### OD-3: Inspection view and comparison API ### OD-5: Scope identity for numeric path segments
**Recommendation:** expose a non-generic `Inspection` view through `Keys("items", "0")`, `Keys("items").Index(0)`, and a parsed `/items/0` have
`InspectSubtree(path Path) (Inspection, bool)`. Return false for an unavailable the same canonical pointer text but different traversal intent. Existing typed
completed-load snapshot or malformed path, not for an absent selected value. queries preserve that intent, while historical-path enumeration identifies paths
Use familiar method names for effective output, explanations, metadata, source by canonical pointer and can include different container shapes at one location.
queries, and focused historical-path enumeration. Keep `Metadata()` unchanged; The view needs a consistent meaning for its selected scope, including what
the view's enumeration supplies the reporting focus. counts as matching scopes for `Diff` when one side is absent or changes shape.
Provide comparison between views with the same selected native path, retaining **Recommendation:** define the view's reporting scope by canonical JSON Pointer
the existing same-root-configuration-type comparison boundary. Because the view location. Normalize the constructor's valid path to that contextual selector;
erases the application's Go type, that compatibility check would occur at numeric tokens follow the containing shape when rendering effective output.
runtime. This allows a library to forward inspection without knowing the root Use the same location and segment-aware containment for focused enumeration,
type, while avoiding an incidental expansion into cross-type or cross-location diff filtering, and scope equality. All three forms above then select the same
comparison. The exact method signature and zero-view error behavior should be reporting scope. Document this on `InspectSubtree`. Explicit `Value`, `Explain`,
recorded before implementation; existing whole-result `Diff` remains unchanged. and metadata queries continue to honor the supplied paths under their existing
rules; they are not rewritten by the view. This reuses historical reporting's
location model without requiring a present value to establish scope identity.
**Alternative:** make the view generic in the application's root type and offer **Alternative:** preserve key/index intent in the scope selector as well as in
a generic comparison function, retaining compile-time comparison compatibility. explicit queries. This more closely resembles typed lookup, but scope equality
This follows the current `Diff[T]` shape, but complicates the consumer-owned and history filtering need additional rules for parsed tokens, absent values,
interface used by a library that does not know the root type. A separate adapter and locations whose container kind differs between snapshots. Simply rejecting
or comparison callback would then be needed for that library's inspection API. all different path representations would also reject equivalent selections such
as a parsed pointer and an explicit key path. The added precision has no
Another viable alternative is a non-generic view with structural comparison demonstrated benefit for the current library-section reporting use case.
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.