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

@@ -50,6 +50,8 @@ Start with one file. Optional features use the same loading and inspection model
references and choose which configuration fields to hide in inspection output. references and choose which configuration fields to hide in inspection output.
- [Inspect a load](docs/config.md#layered-metadata): examine sources, presence, - [Inspect a load](docs/config.md#layered-metadata): examine sources, presence,
history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs). history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs).
- [Hand settings to libraries](docs/consumers/README.md#component-handoff): share
one result and let each consumer select its own settings and reporting scope.
The [consumer guide](docs/consumers/README.md) walks through these tasks and links The [consumer guide](docs/consumers/README.md) walks through these tasks and links
to maintained examples. The [configuration reference](docs/config.md) defines the to maintained examples. The [configuration reference](docs/config.md) defines the

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 diagnostic, and metadata records are copies; changing them cannot change later
queries. Separate loads return independently owned configuration and records. 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 Every source, options, schema, version, defaults, decode, resolution, or
validation failure returns a nil result and a `*LoadError`. Successful results validation failure returns a nil result and a `*LoadError`. Successful results
contain caller-owned `Config`, detached `Metadata`, a defensive source list, 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` | | Inspect earlier values as safe YAML | `Explain` or `WriteExplanation` |
| Show the saved final configuration as safe YAML | `WriteEffective` | | Show the saved final configuration as safe YAML | `WriteEffective` |
| Compare final values from two loads | `Diff` | | 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 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 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 `Explain` adds their before/after values. Changing `result.Config.Workers` later
does not change any of these saved inspection results. 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 #### Presence, origins, and historical paths
`Result.Metadata()` describes every final configuration path. Queries retain explicit `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 its normal nil-result/`LoadError` behavior, which callers handle before invoking
`Diff`. `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 ## Typed secret references
There are three separate tasks when working with credentials: 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) | | 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) | | 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) | | 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) | | 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 ## Choosing a loading entry point
- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration. - 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) - [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
- [Keep the public facade root-owned](adr/0006-public-facade.md) - [Keep the public facade root-owned](adr/0006-public-facade.md)
- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.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) - [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md) - [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
- [Separate import selection controls](adr/0016-independent-import-controls.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` | | 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` | | 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'` | | 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'` | | 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'` | | 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'` | | 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 - Root `Diff` and `Difference` provide the public comparison boundary and
convert detached engine records to root-owned paths and snapshots; consumer convert detached engine records to root-owned paths and snapshots; consumer
examples own presentation of the safe changed regions. 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/document` owns the parser-independent ordered tree and cloning.
`internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary. `internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
- Engine mechanism tests own source, composition, inheritance, decoding, - 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 Detailed syntax and operation tables belong to the
[current configuration contract](../config.md). [current configuration contract](../config.md).
The frozen inspection boundary also supports comparing completed same-type The frozen inspection boundary supports comparing completed same-type results
results without reopening sources or rerunning the load lifecycle. The and focused views across application root types without reopening sources or
rerunning the load lifecycle. The
[configuration contract](../config.md#effective-configuration-diffs) owns [configuration contract](../config.md#effective-configuration-diffs) owns
comparison and disclosure behavior, the [component overview](../internal/overview.md) comparison and disclosure behavior, the [component overview](../internal/overview.md)
owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.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 ## Collection Identity And Combination

View File

@@ -1,6 +1,6 @@
# Implementation plan: typed result values and focused inspection # 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 ## 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 ## Stage 9 — Document the implemented boundary and validate the sprint
**Complete.**
Update documentation only once the corresponding behavior exists: Update documentation only once the corresponding behavior exists:
- Declaration comments own signatures, nil/absence behavior, ordinary aliasing, - Declaration comments own signatures, nil/absence behavior, ordinary aliasing,

View File

@@ -1,6 +1,7 @@
# 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-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`. Baseline: v1.3.0, commit `652ddb6`.
## Purpose and baseline ## 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 can also offer inspection focused on their section. Section names remain library
conventions, not ConfigKit reserved keys. conventions, not ConfigKit reserved keys.
Today, [Result.Config](../../lifecycle.go) supplies trusted typed values, but its At the baseline, [Result.Config](../../lifecycle.go) supplied trusted typed values, but its
generic root type prevents a library from selecting a field without knowing the generic root type prevented a library from selecting a field without knowing the
application type or adding its own traversal. Existing metadata and application type or adding its own traversal. Existing metadata and
[source contexts](../../resource_context.go) already support field provenance and [source contexts](../../resource_context.go) already support field provenance and
resource lookup. Existing inspection and comparison operate on completed-load resource lookup. Baseline inspection and comparison operated on completed-load
snapshots, but there is no reusable subtree reporting view. Redacted inspection snapshots, but there was no reusable subtree reporting view. Redacted inspection
snapshots are not execution inputs. snapshots are not execution inputs.
PromptKit has accepted the typed-value direction. The subsequently agreed PromptKit has accepted the typed-value direction. The subsequently agreed

View File

@@ -25,6 +25,10 @@ func TestComponentHandoff(t *testing.T) {
if runtime.Settings.Name != "example" || len(runtime.Settings.Entries) != 1 || runtime.Settings.Entries[0].ID != "default" || string(runtime.Resource) != "resource data" { if runtime.Settings.Name != "example" || len(runtime.Settings.Entries) != 1 || runtime.Settings.Entries[0].ID != "default" || string(runtime.Resource) != "resource data" {
t.Fatalf("component runtime = %#v", runtime) t.Fatalf("component runtime = %#v", runtime)
} }
runtime.Settings.Entries[0].ID = "runtime change"
if result.Config.Component.Entries[0].ID != "default" {
t.Fatal("runtime settings share the result's slice")
}
entries, found := result.Metadata().Lookup(configkit.Keys("component", "entries")) entries, found := result.Metadata().Lookup(configkit.Keys("component", "entries"))
if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay { if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay {
t.Fatal("presence did not retain source distinction") t.Fatal("presence did not retain source distinction")

View File

@@ -24,6 +24,8 @@ type valueConfig struct {
Array [2]int `yaml:"array"` Array [2]int `yaml:"array"`
Dynamic any `yaml:"dynamic"` Dynamic any `yaml:"dynamic"`
Codec valueCodec `yaml:"codec"` Codec valueCodec `yaml:"codec"`
Pointer *valueEmbedded `yaml:"pointer"`
Nil *valueEmbedded `yaml:"nil"`
Ignored string `yaml:"-"` Ignored string `yaml:"-"`
private string private string
} }
@@ -36,7 +38,7 @@ func TestResultValueCurrentNavigation(t *testing.T) {
var nilMap map[string]int var nilMap map[string]int
result := &configkit.Result[valueConfig]{Config: valueConfig{ result := &configkit.Result[valueConfig]{Config: valueConfig{
Embedded: &valueEmbedded{Label: "named"}, Extra: map[valueKey]any{"a/b": nil, "": nilMap, "0": 7}, Embedded: &valueEmbedded{Label: "named"}, Extra: map[valueKey]any{"a/b": nil, "": nilMap, "0": 7},
List: []string{"first"}, Array: [2]int{1, 2}, Dynamic: map[string]any{"list": []any{valueEmbedded{Label: "dynamic"}}}, List: []string{"first"}, Array: [2]int{1, 2}, Dynamic: map[string]any{"list": []any{valueEmbedded{Label: "dynamic"}}}, Pointer: &valueEmbedded{Label: "pointer"},
}} }}
parsed, _ := configkit.ParsePath("/dynamic/list/0/label") parsed, _ := configkit.ParsePath("/dynamic/list/0/label")
parsedKey, _ := configkit.ParsePath("/0") parsedKey, _ := configkit.ParsePath("/0")
@@ -59,6 +61,8 @@ func TestResultValueCurrentNavigation(t *testing.T) {
{configkit.Keys("list").Index(1), nil, false}, {configkit.Keys("list").Index(-1), nil, false}, {configkit.Keys("list").Index(1), nil, false}, {configkit.Keys("list").Index(-1), nil, false},
{parsed, valueName("dynamic"), true}, {configkit.Keys("ignored"), nil, false}, {configkit.Keys("private"), nil, false}, {parsed, valueName("dynamic"), true}, {configkit.Keys("ignored"), nil, false}, {configkit.Keys("private"), nil, false},
{configkit.Keys("codec"), valueCodec{}, true}, {configkit.Keys("codec", "text"), nil, false}, {configkit.Keys("codec"), valueCodec{}, true}, {configkit.Keys("codec", "text"), nil, false},
{configkit.Keys("nil"), (*valueEmbedded)(nil), true}, {configkit.Keys("nil", "label"), nil, false},
{configkit.Keys("pointer", "label"), valueName("pointer"), true},
} { } {
got, ok := result.Value(tc.path) got, ok := result.Value(tc.path)
if ok != tc.ok || !reflect.DeepEqual(got, tc.want) { if ok != tc.ok || !reflect.DeepEqual(got, tc.want) {
@@ -72,12 +76,17 @@ func TestResultValueCurrentNavigation(t *testing.T) {
listValue.([]string)[0] = "changed" listValue.([]string)[0] = "changed"
mapValue, _ := result.Value(configkit.Keys("dynamic")) mapValue, _ := result.Value(configkit.Keys("dynamic"))
mapValue.(map[string]any)["added"] = true mapValue.(map[string]any)["added"] = true
pointerValue, _ := result.Value(configkit.Keys("pointer"))
pointerValue.(*valueEmbedded).Label = "changed"
if result.Config.Array[0] != 1 || result.Config.List[0] != "changed" { if result.Config.Array[0] != 1 || result.Config.List[0] != "changed" {
t.Fatal("assignment ownership differs") t.Fatal("assignment ownership differs")
} }
if result.Config.Dynamic.(map[string]any)["added"] != true { if result.Config.Dynamic.(map[string]any)["added"] != true {
t.Fatal("map assignment did not preserve alias") t.Fatal("map assignment did not preserve alias")
} }
if result.Config.Pointer.Label != "changed" {
t.Fatal("pointer assignment did not preserve alias")
}
result.Config.Embedded = nil result.Config.Embedded = nil
if _, ok := result.Value(configkit.Keys("label")); ok { if _, ok := result.Value(configkit.Keys("label")); ok {
t.Fatal("nil inline pointer") t.Fatal("nil inline pointer")