Settle canonical reporting scope identity

This commit is contained in:
2026-11-21 03:20:20 +00:00
parent d11e749428
commit 86a9060418

View File

@@ -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.