129 lines
7.9 KiB
Markdown
129 lines
7.9 KiB
Markdown
# 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.
|