From 86a90604185d28d7bd579d33b02ab771da317256 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 03:20:20 +0000 Subject: [PATCH] Settle canonical reporting scope identity --- docs/roadmap/result-value.md | 61 +++++++++++++----------------------- 1 file changed, 22 insertions(+), 39 deletions(-) diff --git a/docs/roadmap/result-value.md b/docs/roadmap/result-value.md index ddc9d59..6364507 100644 --- a/docs/roadmap/result-value.md +++ b/docs/roadmap/result-value.md @@ -1,7 +1,6 @@ # Typed value access and focused inspection from a result -Status: agreed feature scope; OD-1 through OD-4 settled; not implemented. -A path-scope clarification from the coherence review remains below. +Status: agreed feature scope; OD-1 through OD-5 settled; not implemented. Baseline: v1.3.0, commit `652ddb6`. ## Purpose and baseline @@ -170,10 +169,21 @@ behavior for a zero view. Keep native application paths throughout; for example, `/promptkit/prompts` remains `/promptkit/prompts` in queries, explanations, history, and differences. -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. +Reuse existing public result types such as `Explanation`, `Difference`, and +`ValueSnapshot`. No new confidentiality, deep-copy, or concurrent-mutation +guarantee is implied. + +**OD-5 settled:** identify 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, rather than raw string-prefix matching. +For example, `Keys("items", "0")`, `Keys("items").Index(0)`, and a parsed +`/items/0` all select the same reporting scope. This follows historical reporting's +location model and does not require a present value to establish scope identity. +Document this behavior on `InspectSubtree`. Explicit `Value`, `Explain`, and +metadata queries retain their existing key/index intent and contextual traversal +rules; the view does not rewrite those query paths. ## Consumer integration @@ -216,7 +226,7 @@ presence-state handling, resource capture, and settings ownership refactoring. ## Work needed -1. Settle OD-5 and record representative lookup and reporting +1. 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 @@ -237,9 +247,11 @@ presence-state handling, resource capture, and settings ownership refactoring. 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 comparisons between different root Go types, - a section existing on only one side, mismatched scopes, and zero views. + path segments, including equivalent scope spellings and a container changing + between mapping and sequence. Verify frozen behavior after caller mutation + and unchanged 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 @@ -261,32 +273,3 @@ 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 - -### OD-5: Scope identity for numeric path segments - -`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. - -**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:** 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.