From 7a9ce010644cf37b4545ac7c96589144755eb2f5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 04:16:46 +0000 Subject: [PATCH] Document value access and focused inspection --- README.md | 2 ++ docs/config.md | 26 +++++++++++++++++++++ docs/consumers/README.md | 16 +++++++++++++ docs/development.md | 2 ++ docs/internal/overview.md | 4 ++++ docs/policy/architecture.md | 8 ++++--- docs/roadmap/implementation.md | 4 +++- docs/roadmap/result-value.md | 11 +++++---- examples/consumers/result_component_test.go | 4 ++++ facade_result_value_test.go | 11 ++++++++- 10 files changed, 78 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 295df2c..5f1ead7 100644 --- a/README.md +++ b/README.md @@ -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. - [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). +- [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 to maintained examples. The [configuration reference](docs/config.md) defines the diff --git a/docs/config.md b/docs/config.md index 91457c7..924759f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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: diff --git a/docs/consumers/README.md b/docs/consumers/README.md index 26dcb8a..5c65c3d 100644 --- a/docs/consumers/README.md +++ b/docs/consumers/README.md @@ -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. diff --git a/docs/development.md b/docs/development.md index 41295f2..87653cf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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'` | diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 9786d5d..8318548 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -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, diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 715893c..ea77847 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index b7e28d5..6eb81f1 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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, diff --git a/docs/roadmap/result-value.md b/docs/roadmap/result-value.md index 5422ba1..84ae5da 100644 --- a/docs/roadmap/result-value.md +++ b/docs/roadmap/result-value.md @@ -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 diff --git a/examples/consumers/result_component_test.go b/examples/consumers/result_component_test.go index 8d06f2e..fa7d016 100644 --- a/examples/consumers/result_component_test.go +++ b/examples/consumers/result_component_test.go @@ -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" { 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")) if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay { t.Fatal("presence did not retain source distinction") diff --git a/facade_result_value_test.go b/facade_result_value_test.go index fb2ab35..7345c0e 100644 --- a/facade_result_value_test.go +++ b/facade_result_value_test.go @@ -24,6 +24,8 @@ type valueConfig struct { Array [2]int `yaml:"array"` Dynamic any `yaml:"dynamic"` Codec valueCodec `yaml:"codec"` + Pointer *valueEmbedded `yaml:"pointer"` + Nil *valueEmbedded `yaml:"nil"` Ignored string `yaml:"-"` private string } @@ -36,7 +38,7 @@ func TestResultValueCurrentNavigation(t *testing.T) { var nilMap map[string]int result := &configkit.Result[valueConfig]{Config: valueConfig{ 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") 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}, {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("nil"), (*valueEmbedded)(nil), true}, {configkit.Keys("nil", "label"), nil, false}, + {configkit.Keys("pointer", "label"), valueName("pointer"), true}, } { got, ok := result.Value(tc.path) if ok != tc.ok || !reflect.DeepEqual(got, tc.want) { @@ -72,12 +76,17 @@ func TestResultValueCurrentNavigation(t *testing.T) { listValue.([]string)[0] = "changed" mapValue, _ := result.Value(configkit.Keys("dynamic")) 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" { t.Fatal("assignment ownership differs") } if result.Config.Dynamic.(map[string]any)["added"] != true { 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 if _, ok := result.Value(configkit.Keys("label")); ok { t.Fatal("nil inline pointer")