Settle inspection APIs and review roadmap consistency
This commit is contained in:
@@ -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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user