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