From d6fcfc62d96a3c4b0c2150083d3a094d0418ff2a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 12:01:02 +0000 Subject: [PATCH] Clarify result value lookup semantics --- docs/roadmap/remediation.md | 10 +++++++++- result_value.go | 26 +++++++++++++++++++++----- 2 files changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 9118e6a..be671f9 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -75,7 +75,15 @@ unsupported-navigation behavior must remain unchanged. ## 2. The exported Value documentation omits essential settled semantics -**Priority:** P3. **Status:** Open. **Plan stage:** 9. +**Priority:** P3. **Status:** Complete. **Plan stage:** 9. + +**Completion:** expanded Value's declaration documentation for root selection, +manual results, presence versus availability, intermediate navigation, present +nil interfaces and typed nil values, preserved terminal types, scalar leaves, +no conversion/revalidation or codec calls, and ordinary assignment ownership. +Referenced the shared schema binding contract and Path semantics. Reviewed +`go doc Result.Value`; formatting and whitespace checks passed. No runtime +behavior changed in this unit. **Relevant documentation:** the declaration comment in [result_value.go](../../result_value.go), with the existing diff --git a/result_value.go b/result_value.go index 590c67c..315368c 100644 --- a/result_value.go +++ b/result_value.go @@ -2,11 +2,27 @@ package configkit import "go.maximumdirect.net/configkit/internal/engine" -// Value returns the current Config value at path, including values absent from -// input. It returns false for a nil result, invalid path, or missing value. -// Values are trusted application data and may include resolved secrets. Ordinary -// Go assignment applies: maps, slices, and pointers can alias Config. Inspection -// methods continue to report the frozen completed load, not later mutations. +// Value returns the current Config value at path. The root [Path] selects Config. +// A non-nil result supports lookup even when constructed manually without load +// or inspection state. Success means value availability, not input presence or +// validation; use Metadata to inspect presence in the completed load. +// +// Navigation follows the shared YAML field names, inline bindings and supported +// shapes described in docs/config.md#application-schema-binding, with [Path]'s +// key/index rules. It follows non-nil intermediate pointers and interfaces, +// checks map membership and sequence bounds, and never allocates missing values. +// Scalars, including text-codec types and Secret, remain leaves. +// A nil receiver, invalid path, missing value, or unavailable traversal returns +// (nil, false). A present nil succeeds: a nil interface returns (nil, true), while +// typed nil pointers, maps and slices retain their types in the returned any. +// +// The terminal retains its actual Go type, including named types and pointers; +// terminal pointers are not dereferenced. Lookup performs no conversion or +// revalidation of the terminal and does not invoke codecs or resolve secrets. +// Values are trusted application data and may include resolved Secret values. +// Ordinary Go assignment applies: structs and arrays are copied, while maps, +// slices and pointers can alias Config. Inspection methods continue to report +// the frozen completed load, not later caller mutations. func (r *Result[T]) Value(path Path) (any, bool) { if r == nil { return nil, false