Document value access and focused inspection

This commit is contained in:
2026-11-21 04:16:46 +00:00
parent 37f38f3e54
commit 7a9ce01064
10 changed files with 78 additions and 10 deletions

View File

@@ -226,6 +226,13 @@ describe the configuration as it was when the load finished. Returned source,
diagnostic, and metadata records are copies; changing them cannot change later
queries. Separate loads return independently owned configuration and records.
`Result.Value` selects trusted current Go values by configuration path, including
resolved secrets and zero values without input. It uses ordinary Go assignment:
maps, slices, and pointers can share state with `Config`. Availability does not
establish input presence; use metadata for that distinction. Capture owned
runtime settings before later mutations invalidate the relationship to saved
inspection evidence. A manually constructed result also supports value lookup.
Every source, options, schema, version, defaults, decode, resolution, or
validation failure returns a nil result and a `*LoadError`. Successful results
contain caller-owned `Config`, detached `Metadata`, a defensive source list,
@@ -750,6 +757,7 @@ Use inspection to understand a completed load without reading the files again:
| Inspect earlier values as safe YAML | `Explain` or `WriteExplanation` |
| Show the saved final configuration as safe YAML | `WriteEffective` |
| Compare final values from two loads | `Diff` |
| Focus reporting on one location | `InspectSubtree` |
For example, suppose a typed default sets `workers` to `2`, the main input
supplies `workers: 3`, and an overlay supplies `workers: 4`. The final value is
@@ -758,6 +766,16 @@ earlier default and main contributions. `History` returns attribution records;
`Explain` adds their before/after values. Changing `result.Config.Workers` later
does not change any of these saved inspection results.
An `Inspection` view focuses reporting on a canonical JSON Pointer location.
Its `HistoricalPaths` includes observed paths at or below that location and
`WriteEffective` renders the selected frozen value with original sensitivity.
An absent scope can be selected, but has no effective output. Explicit metadata
and explanation queries keep native application paths and may address values
outside the focus; source catalogs and resource contexts remain available for
the whole load. This is a reporting focus, not a confidentiality boundary. Numeric
key and index spellings with the same pointer select the same focus, while
explicit queries preserve their normal path intent.
#### Presence, origins, and historical paths
`Result.Metadata()` describes every final configuration path. Queries retain explicit
@@ -1011,6 +1029,14 @@ uninitialized results return an error with no records. A failed `Load` retains
its normal nil-result/`LoadError` behavior, which callers handle before invoking
`Diff`.
`Inspection.Diff` compares focused views at the same canonical location, even
when their application root Go types differ. It compares the complete frozen
snapshots with the same paired redaction and retains records at, below, or above
the focus. Because sequences and structural replacements can be atomic, an
ancestor record may reflect a change outside the selected value. Different
scopes or unavailable views return an error and no records. Whole-result
`Diff[T]` remains restricted to results of the same Go type.
## Typed secret references
There are three separate tasks when working with credentials:

View File

@@ -28,8 +28,24 @@ Start with one file, then choose the tasks your application needs:
| Reuse settings or combine record lists | [Inheritance](#named-sibling-inheritance) and [identified sequences](#identified-prompt-sequences) |
| Handle credentials | [Typed-secret reference](../config.md#typed-secret-references), [configured startup](#configured-secrets-startup), and the [direct-directory example](../../examples/consumers/consumers_test.go) |
| Inspect sources, earlier values, or changes | [Inspect a completed load](#inspect-a-completed-load) and [diffs](#effective-configuration-diffs) |
| Hand one result to library consumers | [Component handoff](#component-handoff) |
| Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) |
## Component handoff
Register application and library rules in one definition, then load once and
pass the whole result to each consumer. A consumer can select its named settings
with `Value`, assert its own type, and follow effective field origins through
`Metadata` and `SourceContext` to capture resources. It owns any runtime copy it
needs. The maintained [one-library example](../../examples/consumers/result_component.go)
shows registration, underlay defaults, handoff, and a focused inspection facade;
the [two-library example](../../examples/consumers/result_composition.go) composes
callbacks and identity registrations for two consumers.
Views focus reports while explicit metadata and explanation queries retain native
application-root paths. See the [configuration contract](../config.md#layered-metadata)
for ownership, scope, and frozen inspection behavior.
## Choosing a loading entry point
- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration.

View File

@@ -58,6 +58,7 @@ Accepted decisions:
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
- [Keep the public facade root-owned](adr/0006-public-facade.md)
- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md)
- [Compare inspection views across application types](adr/0024-compare-inspection-views-across-application-types.md)
- [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
- [Separate import selection controls](adr/0016-independent-import-controls.md)
@@ -309,6 +310,7 @@ code changes. Use the component overview to find the corresponding implementatio
| Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'`, `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'`, and `go test ./examples/consumers` |
| Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` |
| Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
| Current values and focused inspection | [Value tests](../facade_result_value_test.go), [view tests](../facade_inspection_view_test.go), [comparison tests](../facade_inspection_diff_test.go), and [history integration](../facade_inspection_history_test.go) | `go test . -run 'TestResultValue\|TestInspectionView'` and `go test ./internal/engine -run 'TestResultValue\|Diff\|History'` |
| Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
| Resolution sequence matching and inspection | [Correspondence](../internal/engine/resolution_correspondence_test.go), [auditing and history](../internal/engine/resolution_compare_test.go), [public integration](../facade_resolution_sequences_test.go) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` |
| Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |

View File

@@ -45,6 +45,10 @@ Implemented component owners:
- Root `Diff` and `Difference` provide the public comparison boundary and
convert detached engine records to root-owned paths and snapshots; consumer
examples own presentation of the safe changed regions.
- `Result.Value` delegates current Go-value navigation to an operation-local
engine schema builder and existing field/path bindings. Root `Inspection`
wraps an engine view borrowing the frozen inspection and canonical scope;
it reuses history enumeration, document redaction, and whole-result diff.
- `internal/document` owns the parser-independent ordered tree and cloning.
`internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
- Engine mechanism tests own source, composition, inheritance, decoding,

View File

@@ -316,12 +316,14 @@ See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
Detailed syntax and operation tables belong to the
[current configuration contract](../config.md).
The frozen inspection boundary also supports comparing completed same-type
results without reopening sources or rerunning the load lifecycle. The
The frozen inspection boundary supports comparing completed same-type results
and focused views across application root types without reopening sources or
rerunning the load lifecycle. The
[configuration contract](../config.md#effective-configuration-diffs) owns
comparison and disclosure behavior, the [component overview](../internal/overview.md)
owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.md)
records the accepted decision.
and [ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md)
record the accepted decisions.
## Collection Identity And Combination

View File

@@ -1,6 +1,6 @@
# Implementation plan: typed result values and focused inspection
Status: implementation in progress; Stages 1–8 complete.
Status: complete; all stages implemented and validated.
## Scope and working instructions
@@ -309,6 +309,8 @@ or claim completion of real PromptKit integration.
## Stage 9 — Document the implemented boundary and validate the sprint
**Complete.**
Update documentation only once the corresponding behavior exists:
- Declaration comments own signatures, nil/absence behavior, ordinary aliasing,

View File

@@ -1,6 +1,7 @@
# Typed value access and focused inspection from a result
Status: agreed feature scope; OD-1 through OD-5 settled; not implemented.
Status: implemented; OD-1 through OD-5 settled. See the current
[configuration contract](../config.md) and declaration comments for behavior.
Baseline: v1.3.0, commit `652ddb6`.
## Purpose and baseline
@@ -11,12 +12,12 @@ checks its public settings type, and constructs its runtime objects. Libraries
can also offer inspection focused on their section. Section names remain library
conventions, not ConfigKit reserved keys.
Today, [Result.Config](../../lifecycle.go) supplies trusted typed values, but its
generic root type prevents a library from selecting a field without knowing the
At the baseline, [Result.Config](../../lifecycle.go) supplied trusted typed values, but its
generic root type prevented a library from selecting a field without knowing the
application type or adding its own traversal. Existing metadata and
[source contexts](../../resource_context.go) already support field provenance and
resource lookup. Existing inspection and comparison operate on completed-load
snapshots, but there is no reusable subtree reporting view. Redacted inspection
resource lookup. Baseline inspection and comparison operated on completed-load
snapshots, but there was no reusable subtree reporting view. Redacted inspection
snapshots are not execution inputs.
PromptKit has accepted the typed-value direction. The subsequently agreed