Settle canonical reporting scope identity
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user