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
|
||||
|
||||
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`.
|
||||
|
||||
## Purpose and baseline
|
||||
@@ -103,8 +104,15 @@ or establish new secret-classification semantics.
|
||||
|
||||
### 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:
|
||||
**OD-3 settled:** provide a non-generic `Inspection` view, selected once from a
|
||||
result:
|
||||
|
||||
```go
|
||||
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
|
||||
func (i Inspection) Diff(other Inspection) ([]Difference, error)
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```go
|
||||
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
|
||||
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
|
||||
and redaction, without the enclosing application mappings. Preserve sensitivity
|
||||
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
|
||||
beneath the selected path, retaining existing ordering and path semantics.
|
||||
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
|
||||
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.
|
||||
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
|
||||
presence. A valid path can select an absent, historical-only, or explicit-null
|
||||
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`
|
||||
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
|
||||
Use path segment boundaries for scope matching rather than raw string-prefix
|
||||
matching. OD-5 addresses numeric scope tokens and scope equality. Reuse existing
|
||||
public result types such as `Explanation`, `Difference`, and `ValueSnapshot`.
|
||||
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
|
||||
|
||||
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
|
||||
typed-value availability and input presence.
|
||||
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
|
||||
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.
|
||||
whole-result inspection. Include comparisons between different root Go types,
|
||||
a section existing on only one side, mismatched scopes, and zero views.
|
||||
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
|
||||
@@ -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
|
||||
repository checks. This is an additive API; existing loading, inspection,
|
||||
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
|
||||
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
|
||||
|
||||
### OD-3: Inspection view and comparison API
|
||||
### OD-5: Scope identity for numeric path segments
|
||||
|
||||
**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.
|
||||
`Keys("items", "0")`, `Keys("items").Index(0)`, and a parsed `/items/0` have
|
||||
the same canonical pointer text but different traversal intent. Existing typed
|
||||
queries preserve that intent, while historical-path enumeration identifies paths
|
||||
by canonical pointer and can include different container shapes at one location.
|
||||
The view needs a consistent meaning for its selected scope, including what
|
||||
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
|
||||
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.
|
||||
**Recommendation:** define the view's reporting scope by canonical JSON Pointer
|
||||
location. Normalize the constructor's valid path to that contextual selector;
|
||||
numeric tokens follow the containing shape when rendering effective output.
|
||||
Use the same location and segment-aware containment for focused enumeration,
|
||||
diff filtering, and scope equality. All three forms above then select the same
|
||||
reporting scope. Document this on `InspectSubtree`. Explicit `Value`, `Explain`,
|
||||
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
|
||||
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.
|
||||
**Alternative:** preserve key/index intent in the scope selector as well as in
|
||||
explicit queries. This more closely resembles typed lookup, but scope equality
|
||||
and history filtering need additional rules for parsed tokens, absent values,
|
||||
and locations whose container kind differs between snapshots. Simply rejecting
|
||||
all different path representations would also reject equivalent selections such
|
||||
as a parsed pointer and an explicit key path. The added precision has no
|
||||
demonstrated benefit for the current library-section reporting use case.
|
||||
|
||||
Reference in New Issue
Block a user