Plan typed result access and focused inspection

This commit is contained in:
2026-11-21 03:54:39 +00:00
parent afe83a6fd2
commit 229ad5bfe7
3 changed files with 533 additions and 40 deletions

View File

@@ -227,47 +227,14 @@ APIs and a limited stand-in for `Value`. They establish feasibility, not complet
of real PromptKit integration. PromptKit still owns its public settings model,
presence-state handling, resource capture, and settings ownership refactoring.
## Work needed
## Delivery scope and completion
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
logic for typed traversal. Keep any supporting implementation private. Do not
route through inspection projection or add another complete load-time snapshot.
3. Add focused public tests for root/nested lookup, named and pointer types,
inline fields/maps, dynamic containers and supported structs inside `any`,
numeric keys versus indices, bounds, missing/nil values, scalar leaves, and
the settled receiver/mutation rules, including manually constructed results.
Verify ordinary aliasing and unchanged frozen inspection without promising
concurrent mutation safety. Check trusted secret access and existing redaction
with disposable values.
4. Add the root-owned inspection view over existing private inspection state.
Reuse explanations, metadata, source queries, rendering, and comparison;
add only subtree rendering and reporting selection where needed. Keep
whole-result APIs unchanged. Preserve original paths and sensitivity context.
5. Add focused inspection checks for absent, null, and historical-only sections;
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, 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
operations. Include a library-owned inspection facade that selects its scope
once and forwards focused reports and explicit queries. Keep library-specific
runtime construction outside ConfigKit.
7. Document the APIs beside their declarations, extend the configuration ownership
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, following
[ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md).
The [implementation plan](implementation.md) owns execution order and validation.
The change includes private typed traversal using existing schema bindings, the
root-owned value accessor and inspection view, focused behavioral coverage,
maintained one-library and two-library examples, and updates to the public
contracts and consumer guidance. Architecture and comparison documentation will
reflect ADR 0024 when its implementation lands.
Completion means both representative library consumers can obtain their typed
settings and existing provenance from one application result without application