Record result access review findings

This commit is contained in:
2026-11-21 04:21:25 +00:00
parent 7a9ce01064
commit a57afc7d69

128
docs/roadmap/remediation.md Normal file
View File

@@ -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.