diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..f5c53c8 --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,128 @@ +# Result value and focused inspection review + +Reviewed implementation: `7a9ce01` (against planning baseline `b3799be`). +Scope: the nine stages of [implementation.md](implementation.md), the settled +[result-value roadmap](result-value.md), and accepted +[ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md). + +No implementation changes were made during this review. Both findings below +remain open. + +## 1. Terminal availability still depends on recursive schema validity + +**Priority:** P2. **Status:** Open. **Plan stages:** 1–2. + +**Relevant code:** [ResultValue](../../internal/engine/result_value.go), especially +its descriptor construction at line 33; the recursive map/slice/array and struct +branches of [schemaBuilder.describe](../../internal/engine/schema.go). + +The roadmap requires a reached terminal to be returned as its actual current Go +value without conversion or revalidation. This applies to manually constructed +results and post-load changes. Unsupported shapes matter when navigation must +continue through them, not simply when returning them. + +Before selecting a map entry or sequence element, ResultValue describes its entire +static type, including its element type. Struct description recursively describes +ordinary child types too. Lookup mode makes unsupported primitive/codec types +opaque leaves, but errors such as ambiguous fields, malformed tags, or invalid +inline declarations still propagate from a descendant. Consequently an otherwise +ordinary map lookup can fail because the terminal's internal schema is invalid. +An unrelated descendant can also prevent lookup of an available sibling value. + +For example, this disposable public-API probe returned `(nil, false)`: + +```go +type Terminal struct { + A int `yaml:"same"` + B int `yaml:"same"` +} +r := &configkit.Result[map[string]Terminal]{ + Config: map[string]Terminal{"item": {A: 1, B: 2}}, +} +value, found := r.Value(configkit.Keys("item")) +``` + +Expected: `Terminal{A: 1, B: 2}` and `true`. No binding inside Terminal is needed +to select or return the existing map entry. Continuing into that ambiguous +struct may legitimately fail. The same probe with a dynamic outer struct having +an ordinary `child Terminal` field and a `good int` field returned false for both +`/dynamic/child` and `/dynamic/good`. These are not inputs that Load must accept; +they exercise the expressly supported current-value and hand-built-result boundary. + +**Impact:** the implementation adds a recursive schema-validity prerequisite to +value availability beyond the selected contract. Existing load validation is not +at issue. The current channel-terminal test passes because lookup mode suppresses +only selected schema errors; it does not protect this broader terminal case. + +**Remediation:** make current-value navigation require only the containing shape +and bindings needed for each step. Collection membership/bounds checks should not +require the terminal element's descriptor. Reuse struct binding rules while +keeping ordinary child types opaque until navigation actually continues into +them; retain necessary validation of the current container's own field bindings +and inline flattening. Do not fix this by accepting ambiguous bindings during +continued navigation or weakening Load's schema checks. Add focused public +regressions for terminal invalid-binding structs in a collection and beneath a +dynamic container, including an available sibling. Existing valid-load and +unsupported-navigation behavior must remain unchanged. + +## 2. The exported Value documentation omits essential settled semantics + +**Priority:** P3. **Status:** Open. **Plan stage:** 9. + +**Relevant documentation:** the declaration comment in +[result_value.go](../../result_value.go), with the existing +[configuration ownership contract](../config.md#completion-and-resource-lifetime) +and [schema binding rules](../config.md#application-schema-binding) as supporting +owners. + +The comment documents current values, trusted access, aliasing and frozen +inspection, but does not explain several consequential API choices: the root +selects Config, a present nil value succeeds, a terminal pointer retains its type, +intermediate nils prevent further navigation, and manually constructed results +work without load evidence. It also supplies no reference to the shared YAML-name, +inline-field and scalar-leaf navigation rules. The configuration reference adds +some of these facts, but still does not establish the full lookup contract. +Important details currently remain primarily in the soon-to-be-retired roadmap. + +**Impact:** consumers cannot reliably distinguish unavailable paths from present +nil values or learn terminal-pointer and field-navigation behavior from the +public API documentation. This is a documentation gap rather than evidence of a +second runtime defect. + +**Remediation:** complete the Value declaration comment with the root, nil, +terminal-pointer, manual-result, and no-conversion/no-revalidation behavior. +Reference shared schema/path rules rather than reproducing their complete tables. +State that scalar descriptors remain leaves and lookup does not run codecs. Keep +ordinary Go typed-nil behavior explicit where needed; do not promise deep copies, +frozen execution settings or concurrent mutation safety. Align the wording with +finding 1's corrected implementation, without redefining the intended contract. + +## Stage-by-stage disposition + +| Stage | Review result | +| --- | --- | +| 1 — Private current-value navigation | Finding 1. Descriptor/field/path reuse, nil-safe field access, operation-local state and pointer-loop handling otherwise follow the plan. | +| 2 — Public Value and tests | Finding 1 is not covered by the existing terminal tests. Current values, named types, ordinary assignment, nil availability and trusted Secret access otherwise follow the selected design. | +| 3 — View and canonical scope | No additional finding. Canonical normalization plus existing token-spelling containment implements reporting scope; explicit queries and catalogs remain unfiltered. | +| 4 — Focused rendering | No additional finding. Frozen document selection preserves native-path ancestor sensitivity, absent/null distinctions and writer failure behavior. | +| 5 — View comparison | No additional finding. Complete original snapshots use existing paired redaction and atomic difference regions before scope filtering; cross-root-type comparison follows ADR 0024. | +| 6 — History/provenance/ownership integration | No additional finding. Tests exercise removed paths, numeric shape changes, source contexts through placement/inheritance, detached query records and frozen reports after Config mutation. | +| 7 — One-library example | No additional finding. One load, typed registration, owned settings capture, effective resource context and a library inspection facade are demonstrated. | +| 8 — Two-library example | No additional finding. Application and component callbacks/identities compose explicitly; tests cover preserved false input, repeated loads, validation and inherited resource context. | +| 9 — Documentation and validation | Finding 2. Architecture comparison wording, consumer navigation and implementation inventory reflect the accepted model. | + +## Validation and limits + +Using the locally installed Go 1.27.4 toolchain with `GOTOOLCHAIN=local`, +`GOPROXY=off` and `GOTELEMETRY=off`: + +- `./scripts/check.sh` passed: formatting, whitespace, full tests, vet and build. +- `go test -race ./...` passed, including engine and consumer examples. +- A disposable program outside the repository reproduced finding 1 through the + public API; no new repository tests or production changes were introduced. +- Local Markdown file targets and heading anchors were checked across the changed + documentation; all 441 checked local links resolved. + +No other required correctness, architecture, or strengthened-contract finding was +identified. This review does not claim real downstream adoption, concurrent +mutation support, narrower subtree diff cost, or a release/publication check.