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

@@ -0,0 +1,336 @@
# Implementation plan: typed result values and focused inspection
Status: ready for implementation; no stages implemented by this document.
## Scope and working instructions
Implement the agreed end state in [result-value.md](result-value.md), including
settled OD-1 through OD-5 and accepted [ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md).
The runtime baseline is v1.3.0 (`652ddb6`); subsequent documentation commits
settle the API and comparison choices. Inspect the current checkout before editing.
The broader [consumer request](promptkit-resolved-configuration-request.md) is
background, not additional acceptance criteria: independent source-version
policies and isolation of sibling evidence are outside this feature.
Audience: a Luna coding agent implementing stages sequentially in one end-to-end
sprint. Intermediate stages may leave compilation temporarily incomplete; do not
add temporary public bridges or duplicate implementations to keep them green.
Private helper names and file boundaries below are implementation suggestions;
public signatures and the roadmap's behavior are selected decisions.
Start with [development guidance](../development.md), [agent policy](../policy/agents.md),
[architecture policy](../policy/architecture.md), [testing policy](../policy/testing.md),
and [documentation policy](../policy/documentation.md). Preserve unrelated work.
Use focused behavioral checks as each part becomes runnable, then perform the
final checks once the complete feature is in place. Commit completed nonempty
units according to agent policy; do not publish a release or modify dependencies.
## Implementation boundaries
- Root `configkit` owns exported declarations and explicit conversions. Engine
helpers remain private to consumers. Keep root-to-engine dependency direction
and avoid exported aliases or anonymous internal embedding.
- `Value` reads current `Config`; inspection borrows the existing frozen load
state. Neither capability loads again, projects a new execution snapshot,
runs codecs or callbacks, reads resources, or resolves secrets.
- Preserve existing `Result` methods and generic `Diff[T]`. The new non-generic
view compares frozen snapshots structurally across root Go types, as ADR 0024
explicitly permits. No runtime root-type tracking is needed.
- Reuse descriptor field bindings, path parsing/index rules, history inventories,
snapshot redaction, and the existing comparison algorithm. No new global
caches, registry, synchronization, conversion framework, or load-time snapshot
is needed. Do not impose new limits or validation on returned terminal values.
- Ordinary Go assignment governs ownership. Maps, slices, and pointers may alias
`Config`; neither deep copying nor concurrent mutation safety is promised.
Typed value availability is independent of YAML presence and load evidence.
- Reporting scope is a canonical JSON Pointer location. Explicit typed lookup,
explanation, and metadata queries retain their existing semantic path intent.
## Stage 1 — Implement private current-value navigation
Read `internal/engine/schema.go`, `schema_fields.go`, `value_operation.go`,
`decode.go`, and semantic paths before adding a small engine helper, for example
in `internal/engine/result_value.go`. Accept the current Go root, an engine Path,
and the existing root-supplied Secret binding; return `(any, bool)`.
1. Reject invalid paths. For a reached terminal, return its actual Go value before
dereferencing pointers or attempting structural validation. The root selects
the entire current configuration. Nil interfaces return `(nil, true)`;
typed nil pointers/maps/slices retain their typed nil value in `any` with
`true`, as ordinary Go assignment requires. Unsupported terminal values are
still returned without conversion or revalidation.
2. For continued navigation, follow non-nil pointers/interfaces and describe the
containing type using existing operation-local schema machinery. Reuse
`schemaBuilder.describe`, descriptor kinds and field bindings; share small
helpers where needed rather than introducing a second YAML-tag parser.
`buildSchema` enforces load-root requirements and `resolveSchemaPath` accepts
some merely schema-valid dynamic paths; neither alone proves runtime presence.
3. Struct fields use `fieldByName`, field index chains, and the inline-map fallback.
Reuse `fieldForDecode` with allocation disabled if suitable; ordinary named
fields take precedence over inline-map entries. Do not allocate nil embedded
pointers. Keep ignored/unexported fields inaccessible. Convert string map keys
to the declared key type when necessary, preserving named string-key support.
4. Check actual map membership and slice/array bounds. Use `schemaIndex` for
contextual numeric tokens, canonical index spelling, and explicit key/index
intent. Text-codec scalars, duration, Secret, and other scalar descriptors are
leaves, even if represented by structs. Inspect method sets only; do not call
codecs, projection, cloning, or secret-value getters during navigation.
5. For `any`, describe its current dynamic concrete value under existing supported
type/field rules, including supported structs supplied after loading or in a
manually constructed result. Reuse dynamic descriptor machinery where its
semantics fit; do not apply projection's secret-classification admission as a
new lookup validation pass. Existing Secret descriptors remain scalar leaves.
An unsupported containing shape returns false when further navigation needs it.
6. Keep descriptor/cache state local to the call. Traverse the requested path,
using direct field/map/index selection; do not scan or project all runtime
configuration values. Recursive types must work. If pointer/interface unwrapping
can repeat without consuming a segment, detect that loop locally and return
false instead of hanging; do not reject a whole object graph for a cycle on
an unvisited branch or introduce a general cycle-validation phase.
Acceptance: navigation can distinguish missing from present nil and can return
named values without changing the configuration. Descriptor work may inspect
reachable schema types; lookup should not depend on total runtime collection size.
## Stage 2 — Expose Value and verify its public contract
Add `func (r *Result[T]) Value(path Path) (any, bool)` in a focused root file,
forwarding current `r.Config`, the converted path, and the existing Secret binding.
A nil receiver returns `(nil, false)`. Any non-nil result works independently of
its inspection field, including `&Result[T]{Config: ...}`.
Add focused public tests, for example `facade_result_value_test.go`, protecting:
- Root and nested lookup, YAML/default names, inline structs/pointers/maps,
ignored and unexported fields, and literal escaped/empty keys.
- Named scalars, structs, arrays, pointers at terminals, and non-nil intermediate
pointers. Present zero/false/empty values remain available without input;
metadata separately distinguishes defaulted from explicit values.
- Dynamic maps, sequences, and supported structs in `any`, including post-load
replacements and hand-built results. Unsupported navigation fails cleanly;
reached terminals are not revalidated.
- Numeric mapping keys versus sequence indices, parsed contextual tokens,
negative/invalid indices, bounds, missing entries, and nil intermediates.
A nil interface and typed nil values are tested using their Go semantics.
- Struct/array assignment copies and pointer/map/slice aliasing. Mutations to
current `Config` are visible to Value while existing inspection stays frozen.
- Trusted access to a resolved Secret with a disposable canary and unchanged
redaction through existing inspection. A codec that fails if invoked proves
lookup does not run application codecs after construction.
Use a few readable fixtures/tables rather than one test for every helper branch.
Reuse existing schema/path tests for rules unchanged by this work. Run focused
Value tests and the public boundary tests when this stage is runnable.
## Stage 3 — Add the inspection view and canonical scope selection
Add a root-owned, non-generic `Inspection` with unexported state retaining the
existing engine Inspection and normalized scope. Put scope-aware implementation
in engine (a small private-to-consumers view/helper is sufficient); do not copy the
frozen result or construct a partially populated `Result`.
Implement these public signatures:
```go
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
func (i Inspection) Metadata() Metadata
func (i Inspection) HistoricalPaths() []Path
func (i Inspection) Sources() []SourceInfo
func (i Inspection) Source(id string) (SourceInfo, bool)
func (i Inspection) SourceContext(id string) (ResourceContext, bool)
func (i Inspection) Explain(path Path) (Explanation, bool)
func (i Inspection) WriteExplanation(output io.Writer, path Path) error
```
1. Constructor failure means nil result, missing completed-load inspection, or
invalid path. A valid absent path succeeds. Normalize only after checking
validity: parse the canonical pointer spelling into contextual tokens so
explicit numeric key/index spellings select the same reporting location.
Empty scope selects the whole result.
2. Centralize a small canonical-location containment operation for enumeration
and later diff filtering. Compare pointer tokens or canonical strings with
slash boundaries and an explicit root case. `/a` must not include `/ab`;
escaped slashes and empty keys retain their meaning. Existing `pathHasPrefix`
compares segment kinds and is not the reporting-location operation needed here.
Do not alter semantic path equality elsewhere or build a new path inventory.
3. HistoricalPaths filters the existing detached, pointer-sorted enumeration to
equal/descendant locations. Preserve its order and uniqueness. Effective
presence remains available via `Metadata().Lookup(path)`; no new effective-path
public API is needed. Metadata itself remains the original unfiltered view.
4. Forward explicit Explain and WriteExplanation paths unchanged, including paths
outside the focus. Forward source catalogs/IDs and contexts without ownership
filtering. Reuse existing root conversions, extracting small shared conversion
helpers only when useful. Ancestor snapshots and dependency evidence remain
intact even when they contain siblings outside the focus.
5. A zero view uses existing unavailable-state results: empty metadata/path
enumeration, nil source catalog, false query results, and explanation-rendering
errors as appropriate. Preserve the existing detached-record and borrowed
ResourceContext ownership rules.
Add constructor/forwarding tests for root, absent scopes, malformed paths, nil and
manual results, zero views, native paths outside scope, equivalent numeric scope
spellings, escaped keys, and sibling-prefix exclusion. Do not require a scope to
exist in either effective or historical data.
## Stage 4 — Render focused effective output with original sensitivity
Add `func (i Inspection) WriteEffective(output io.Writer) error` and a scoped
engine rendering operation using the saved final tree.
1. Resolve the normalized contextual scope against the frozen document with
existing document traversal. No value means an error before writing bytes;
explicit null is a present node and renders normally. A zero view or nil
writer follows existing effective-rendering failure behavior.
2. Pass the selected node and its original application path to the existing
snapshot/redaction boundary (`safeSnapshotDocument`/`redactedDocument`), then
write with the existing YAML adapter. `pathIsSecret` already checks ancestors;
do not reset the selected value to root before sensitivity evaluation.
3. Output just the selected value, with existing formatting and redaction.
Writer errors propagate normally and may leave partial output. Do not use
trusted Value output or marshal/redecode typed settings for this operation.
Add public behavioral tests for mapping/scalar/sequence/root output, null versus
absent, historical-only scopes, ancestor and descendant sensitivity, numeric
mapping/sequence scopes, and unchanged output after Config mutation. Use a
controlled failing writer for failure propagation; preserve whole-result output
coverage rather than duplicating it comprehensively.
## Stage 5 — Compare focused views using the existing diff
Implement `func (i Inspection) Diff(other Inspection) ([]Difference, error)`.
Validate both initialized views and equality of normalized reporting locations
before comparison. Errors return no records; do not add root-Go-type checks.
Delegate to `engine.Diff` on the original complete frozen inspections, then
retain each record whose native Path is equal to, beneath, or above the scope.
Use the Stage 3 location helper in both directions. Preserve record order,
original paths, snapshot text, Present/Redacted flags, and HiddenChanged.
Filter before root record conversion where convenient. Reuse the existing root
Difference conversion instead of copying comparison logic.
Do not extract and compare section roots: doing so would change sequence-atomic
regions, ancestor changes, or paired sensitivity. Whole-result comparison cost
is deliberately selected; no narrower algorithm or performance experiment is
part of this implementation.
Add focused tests covering:
- Equal views, ordinary in-scope changes, sibling-only differences filtered out,
same-scope comparisons across different application root Go types, and root scope.
- Scope addition/removal, absent on both sides, explicit null, and mismatched or
zero views. Equivalent numeric scope spellings compare successfully.
- A change to a containing sequence or cross-kind ancestor retains that ancestor
record, even when its cause is outside the selected descendant. This is the
documented consequence of focusing an atomic difference, not proof the selected
value changed. Include mapping-to-sequence shape changes at numeric locations.
- Sensitivity from either side, ancestor sensitivity and sensitive removal, with
disposable canaries absent from returned snapshots and unchanged HiddenChanged
semantics. Whole-result Diff retains its existing same-type API and behavior.
Run focused view-diff tests together with the existing diff tests.
## Stage 6 — Verify history, provenance, and view ownership together
Use a small loaded fixture to exercise the interactions not covered by stages
3–5. Prefer extending their fixtures rather than creating another test framework.
- Select a component with effective and removed descendants. HistoricalPaths
includes only observed equal/descendant locations, including historical-only
paths; Metadata.History and Explain retain ordinary ancestor records and native
query paths. Check the distinction between constructor success and presence.
- Retain source catalogs, locations and SourceContext through placed inputs and
an existing structural transformation such as inheritance. Assert effective
field origins lead to the original resource base. A source that contributes
siblings remains discoverable; historical-only origins do not restore a lost
effective resource origin.
- Mutate current Config after selecting the view. Value sees that mutation while
view rendering, explanation and comparison still describe the completed load.
Mutating returned query records does not alter later reports. Reuse existing
detached metadata/source tests where forwarding already protects this risk.
- Confirm contextual scope enumeration across historical key/index shape changes
without rewriting explicit query paths or collapsing existing history semantics.
Run the focused history/metadata/render/source-context tests plus the new public
view tests. This stage verifies integration, not a new confidentiality or
concurrent-mutation contract.
## Stage 7 — Demonstrate one-library handoff
Add a maintained example and focused test under `examples/consumers/`, for example
`result_component.go` and `result_component_test.go`, using representative small
library-owned settings rather than adding an actual PromptKit dependency.
Show an application-owned root and a library-owned consumer interface using
Value, Metadata, and SourceContext. The application passes the whole result;
the library selects its conventional path and asserts its public settings type.
Registration uses an ordinary typed field selector and existing Definition hooks
for defaults, normalization, validation, sensitivity and sequence identities.
Bundled defaults enter as ordinary underlays where needed. Runtime construction
and resource capture remain library/application responsibilities.
Show a library-owned inspection facade selecting InspectSubtree once and
forwarding effective output, explicit native-path queries and view comparison.
Test one normal load followed by handoff, useful typed values, presence/origin,
safe reporting, a relative resource resolved from its effective source, and a
component validation failure during the application load. Do not create a new
ConfigKit registration API or a second library-specific load.
## Stage 8 — Demonstrate two-library composition
Extend the example with a second small consumer using the same application
result and a smaller consumer-owned interface where sufficient. Compose existing
application and library callbacks with explicit ordering and authoritative
sequence identity registrations. Use fresh per-load state rather than shared
mutable registration captures.
Verify both consumers receive their own named settings from the same result,
application rules still run, explicit values survive absence-based defaults,
invalid component identities fail through the normal lifecycle, and source
contexts remain usable through placement/inheritance. Include repeated loads to
show callback/default state does not leak. Reuse Stage 7's fixtures and existing
source-operation tests; demonstrate representative integration without multiplying
every layering/import/override combination. Do not modify downstream repositories
or claim completion of real PromptKit integration.
## Stage 9 — Document the implemented boundary and validate the sprint
Update documentation only once the corresponding behavior exists:
- Declaration comments own signatures, nil/absence behavior, ordinary aliasing,
trusted values, current Config versus frozen evidence, and reporting-only scope.
Document canonical scope equivalence on InspectSubtree and errors on unavailable
output or invalid comparisons. Do not add public error codes/sentinels merely
for this feature; use existing error style.
- `docs/config.md` owns shared ownership/inspection and comparison behavior.
Distinguish same-type Diff[T] from cross-root-type view comparison, ancestor
differences and paired redaction, and value availability from input presence.
- `docs/consumers/README.md` links the maintained examples and explains one-load
registration, whole-result handoff, owned runtime settings, and native paths.
Link from README only with a short useful orientation entry.
- `docs/internal/overview.md` records actual helper ownership and reuse.
`docs/development.md` adds focused test guidance and ADR 0024 navigation.
Update the architecture policy's comparison wording to include accepted
ADR 0024 while preserving its existing provenance and other constraints.
- Update roadmap status accurately. Retain historical release records and the
deferred candidates in future.md. Release notes/publication are a separate task.
Run the focused tests introduced above, `go test -race ./...`, and the everyday
`./scripts/check.sh` using an installed compatible toolchain and pre-acquired
dependencies. The everyday check supplies formatting, whitespace, tests, vet and
build validation. Run the consumer examples and existing public API/dependency
boundary checks through their ordinary tests. Review changed Markdown links and
all newly documented behavior against the implementation; no new release gate,
performance threshold or benchmark requirement is introduced.
Completion review must establish that both consumers use one application result,
current typed access follows existing field/path conventions, frozen inspection
preserves native evidence and sensitivity, cross-type view comparison follows
ADR 0024, and whole-result loading/inspection remains compatible. Review the full
diff for accidental stronger contracts, unsafe reflect access and duplicated
machinery. Commit validated, nonempty work with plain-English messages and report
remaining limitations accurately.
## Open Questions
None. OD-1 through OD-5 and ADR 0024 settle the decisions required for this scope.
Private naming and file organization remain ordinary implementation choices.

View File

@@ -0,0 +1,190 @@
# PromptKit Request: Consume A Component From One Resolved Application Configuration
Status: upstream feature request for discussion, not an accepted implementation
plan. This document specifies consumer capabilities and leaves API names and
internal implementation to ConfigKit.
## Consumer Need
PromptKit is a Go library used by applications such as Audita and Scriptorium.
Today, an application can load its own settings with ConfigKit, then assemble
separate sources for PromptKit to load again. Audita uses the application main
source's recorded filesystem context to locate companion PromptKit resources.
The desired workflow is one application-owned ConfigKit load. The application
passes the **entire resolved result** to PromptKit, which consumes only the fixed
root-level `promptkit` section. The application should not extract, serialize,
reshape, or reload that section, or reconstruct its resource contexts.
The resulting document can contain both sets of settings:
```yaml
version: 3
application:
output_directory: ./reports
promptkit:
schema_root: ./schemas
collections:
weatherreporter:
prompts:
- id: summarize.alerts
messages:
- role: user
content_file: ./messages/summary.md
output:
format: json
validation_mode: json_schema
schema_path: alerts.json
```
This is an illustrative target configuration, not current PromptKit syntax.
The fixed key is PromptKit's convention, not a proposed ConfigKit reserved key.
Applications retain source discovery, layering, imports, and override policy.
PromptKit retains its field rules and engine construction. ConfigKit retains
composition, effective field contexts, and inspection semantics.
## Verified Baseline
Assessment baseline: ConfigKit v1.3.0, commit
`652ddb649c60208dbba964f0ef919e36725c12c0`. Public-API offline diagnostics verified:
- A typed component field and an inline catch-all map can allow application
siblings while rejecting unknown fields inside the component.
- Application callbacks can default component values after composition;
registered identities can validate nested resource lists.
- Mounted fragments retain field origins and usable `SourceContext` information.
- `Explain` on the component path returns a redacted section snapshot.
- `WriteEffective` and `Diff` still operate on the whole result. A sibling-only
change produces a native difference outside the component.
- One shared source-version rule accepting application version 3 rejects a
PromptKit fragment declaring version 2.
The relevant public contracts are [definitions and results](../../lifecycle.go),
[resource contexts](../../resource_context.go), [inspection](../../inspection.go),
[metadata](../../metadata.go), [comparison](../../diff.go), and
[shared source-version checks](../config.md#shared-source-version-checks).
These findings establish partial feasibility, not a working whole-result
PromptKit integration.
## 1. Resolved Component Access And Scoped Inspection
Provide a public way for a library receiving the whole application result to
select its section for execution and inspection, independently of the application's
particular Go root type. It must retain the original load's effective values and
resource contexts without another configuration load or historical reconstruction.
Execution access must provide usable, trusted configuration values. Existing
redacted inspection YAML is not an execution input. Define ownership explicitly:
`Result.Config` is mutable while inspection describes a frozen snapshot today.
The new contract should state which values a consumer receives and how later
caller mutations relate to those values and their inspection evidence. This
request does not require all existing `Result.Config` values to become immutable.
For the selected section, support:
- Effective configuration output, with native redaction.
- Presence/origin queries, relevant history, and path enumeration.
- Explanations retaining full native paths such as
`/promptkit/collections/weatherreporter/prompts/0/output`.
- Comparison of the section between successful loads, retaining native sensitive
change semantics and excluding changes confined to sibling application values.
- Effective field context lookup so relative message and schema files keep the
filesystem and base directory of the source that contributed the field.
Define absent-section and explicit-null behavior, including comparisons where a
section is added or removed. A component view must not turn an absent section
into a new composition operation. Scope value-bearing reports and history so
selecting a component does not disclose unrelated sibling values through ancestor
records. Relevant source provenance remains useful; no requirement is made to hide
the existence of a shared source document.
This is a request for a native consumer boundary, not a guarantee about which
nodes ConfigKit may visit internally. Whole-result comparison followed by local
filtering can approximate the public diff, but leaves PromptKit maintaining
separate adapters for output, opaque metadata, history, and comparison.
## 2. Independent Source-Version Policies Within One Load
An application's main configuration and imported component collections can have
independent specification versions. For example, the application document above
uses `version: 3`, while a PromptKit collection can begin with:
```yaml
version: 2
prompts:
- id: summarize.alerts
messages:
- role: user
content: Summarize the supplied alerts.
output:
format: text
validation_mode: none
```
The application mounts that standalone collection beneath
`promptkit.collections.weatherreporter`. Its version declaration should be checked
against PromptKit's collection policy, not the application's version policy.
Provide public selection of the appropriate version policy for component sources
and their imports within the same load. Define the selection behavior for direct
inputs, transitive imports, and sources mounted at destinations. Policy assignment
must be explicit and independent of whether a declaration's numeric value happens
to match one checker; accepting both 2 and 3 everywhere does not meet this need.
Preserve optional declarations: a collection may omit its header, but a supplied
header must be checked under the applicable policy before composition consumes it.
Maintain ordinary final-value validation and native diagnostics. Header handling
must not let a collection overwrite the application's main version declaration.
The application must not preparse fragments, strip headers, or load collections
separately to achieve this behavior.
No particular selector syntax or internal routing mechanism is requested. An
application-owned document containing `promptkit` settings is still an application
document; it does not require two competing root version headers.
## 3. Demonstrate A Small Component Integration Contract
Please evaluate this complete consumer sequence alongside the requested APIs:
1. The application declares its own configuration type and includes PromptKit's
supported public settings/registration at `promptkit`.
2. It incorporates PromptKit-owned defaults, normalization, validation, sequence
identities, and sensitivity rules into its ordinary ConfigKit load. Desired
bundled resources enter as ordinary underlays before resolution.
3. ConfigKit loads and resolves the complete configuration once, applying the
application's rules and the component's rules in the supported lifecycle.
4. The application passes that whole result to PromptKit. PromptKit uses the
fixed section and original source contexts to capture resources and construct
its engine. It does not inject defaults through a second load.
5. PromptKit delegates its configuration reports and comparisons to the native
scoped inspection capability.
Existing `Definition[T]` callbacks may be sufficient with a small library helper.
A new component registry is **not** a prerequisite of this request. Please show
how component rules can be composed with an application-owned root type without
the application reproducing those rules or depending on the library's internal
types. If a public extension is needed, keep it limited to the demonstrated gap.
The section handoff should not require a per-application extraction adapter.
## Acceptance Scenarios
- One load contains application fields and a typed PromptKit section; unrelated
fields are governed by the application, while invalid component fields fail.
- Component defaulting, normalization, identities, and sensitivity run through
the normal lifecycle and remain visible in the resolved result and inspection.
- Whole-result handoff works with an application-owned Go configuration type,
with no section serialization/reload or source-context reconstruction.
- Embedded and operator collection fragments retain relative-file contexts after
mounting, inheritance, and overrides, including identical file basenames.
- Component execution access preserves values needed for execution, while public
inspection redacts sensitive values. Ownership/mutation behavior is documented.
- Sibling-only changes do not appear in component comparisons; component changes,
sensitive changes, and section addition/removal follow native reporting rules.
- Application version 3 and PromptKit collection version 2 coexist under their
respective policies; each rejects unsupported declarations independently.
Headerless collections and transitive imports exercise the selected policies.
PromptKit's repair-default change and its domain-specific validation rules are
outside this upstream request. No changes to ConfigKit's internal representation,
algorithms, or package layout are proposed. Please distinguish capabilities already
available through a concise public example from those needing new public APIs.

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, of real PromptKit integration. PromptKit still owns its public settings model,
presence-state handling, resource capture, and settings ownership refactoring. presence-state handling, resource capture, and settings ownership refactoring.
## Work needed ## Delivery scope and completion
1. Record representative lookup and reporting The [implementation plan](implementation.md) owns execution order and validation.
outcomes, including nil values, absent scopes, and the difference between The change includes private typed traversal using existing schema bindings, the
typed-value availability and input presence. root-owned value accessor and inspection view, focused behavioral coverage,
2. Add the root-owned method and reuse existing schema bindings and semantic path maintained one-library and two-library examples, and updates to the public
logic for typed traversal. Keep any supporting implementation private. Do not contracts and consumer guidance. Architecture and comparison documentation will
route through inspection projection or add another complete load-time snapshot. reflect ADR 0024 when its implementation lands.
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).
Completion means both representative library consumers can obtain their typed Completion means both representative library consumers can obtain their typed
settings and existing provenance from one application result without application settings and existing provenance from one application result without application