From d11e7494285344d9401da72175a2b558347d824d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 03:17:32 +0000 Subject: [PATCH] Settle inspection APIs and review roadmap consistency --- docs/roadmap/result-value.md | 109 ++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 47 deletions(-) diff --git a/docs/roadmap/result-value.md b/docs/roadmap/result-value.md index 793fb36..ddc9d59 100644 --- a/docs/roadmap/result-value.md +++ b/docs/roadmap/result-value.md @@ -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.