Settle canonical reporting scope identity
This commit is contained in:
@@ -1,7 +1,6 @@
|
|||||||
# Typed value access and focused inspection from a result
|
# Typed value access and focused inspection from a result
|
||||||
|
|
||||||
Status: agreed feature scope; OD-1 through OD-4 settled; not implemented.
|
Status: agreed feature scope; OD-1 through OD-5 settled; not implemented.
|
||||||
A path-scope clarification from the coherence review remains below.
|
|
||||||
Baseline: v1.3.0, commit `652ddb6`.
|
Baseline: v1.3.0, commit `652ddb6`.
|
||||||
|
|
||||||
## Purpose and baseline
|
## Purpose and baseline
|
||||||
@@ -170,10 +169,21 @@ behavior for a zero view.
|
|||||||
|
|
||||||
Keep native application paths throughout; for example, `/promptkit/prompts`
|
Keep native application paths throughout; for example, `/promptkit/prompts`
|
||||||
remains `/promptkit/prompts` in queries, explanations, history, and differences.
|
remains `/promptkit/prompts` in queries, explanations, history, and differences.
|
||||||
Use path segment boundaries for scope matching rather than raw string-prefix
|
Reuse existing public result types such as `Explanation`, `Difference`, and
|
||||||
matching. OD-5 addresses numeric scope tokens and scope equality. Reuse existing
|
`ValueSnapshot`. No new confidentiality, deep-copy, or concurrent-mutation
|
||||||
public result types such as `Explanation`, `Difference`, and `ValueSnapshot`.
|
guarantee is implied.
|
||||||
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
|
## Consumer integration
|
||||||
|
|
||||||
@@ -216,7 +226,7 @@ presence-state handling, resource capture, and settings ownership refactoring.
|
|||||||
|
|
||||||
## Work needed
|
## 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
|
outcomes, including nil values, absent scopes, and the difference between
|
||||||
typed-value availability and input presence.
|
typed-value availability and input presence.
|
||||||
2. Add the root-owned method and reuse existing schema bindings and semantic path
|
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
|
subtree output and discovery; native-path queries outside the focus; ancestor
|
||||||
history and differences; source-context continuity; and sensitivity inherited
|
history and differences; source-context continuity; and sensitivity inherited
|
||||||
from ancestors or either compared result. Check sibling path names and numeric
|
from ancestors or either compared result. Check sibling path names and numeric
|
||||||
path segments. Verify frozen behavior after caller mutation and unchanged
|
path segments, including equivalent scope spellings and a container changing
|
||||||
whole-result inspection. Include comparisons between different root Go types,
|
between mapping and sequence. Verify frozen behavior after caller mutation
|
||||||
a section existing on only one side, mismatched scopes, and zero views.
|
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
|
6. Add maintained one-library and two-library consumer examples. Demonstrate one
|
||||||
load, typed registration, whole-result handoff, composed callbacks and identity
|
load, typed registration, whole-result handoff, composed callbacks and identity
|
||||||
checks, and resource contexts retained through placement and existing structural
|
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
|
focused inspection using the same completed result. Independently versioned
|
||||||
source support is not required. The intended release is additive: existing
|
source support is not required. The intended release is additive: existing
|
||||||
loading and inspection callers need not adopt either new capability.
|
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