211 lines
13 KiB
Markdown
211 lines
13 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 these reviews. Findings 1–2 come
|
||
from the correctness/architecture review; finding 3 comes from the subsequent
|
||
algorithmic review. Completion notes below track remediation after those reviews.
|
||
|
||
## 1. Terminal availability still depends on recursive schema validity
|
||
|
||
**Priority:** P2. **Status:** Complete. **Plan stages:** 1–2.
|
||
|
||
**Completion:** lookup descriptors now describe only the containing shape and
|
||
necessary inline bindings; ordinary children remain opaque until navigation
|
||
continues. Added public regressions for map/slice/array terminals, post-load
|
||
dynamic children and siblings, and continued rejection of ambiguous navigation
|
||
and invalid load schemas. The regression failed before the fix. Focused tests,
|
||
`./scripts/check.sh`, and `go test -race ./...` passed with Go 1.27.4.
|
||
|
||
**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.
|
||
|
||
## 3. Scoped path enumeration unnecessarily copies all effective metadata
|
||
|
||
**Priority:** P3. **Status:** Open. **Plan stage:** 3 (also exercised in stage 6).
|
||
|
||
**Relevant code:** `InspectionView.HistoricalPaths` in
|
||
[inspection_view.go](../../internal/engine/inspection_view.go), line 62;
|
||
`Inspection.Metadata` in [load.go](../../internal/engine/load.go);
|
||
`cloneMetadata` in [load_metadata.go](../../internal/engine/load_metadata.go);
|
||
and the existing enumeration in
|
||
[history_select.go](../../internal/engine/history_select.go).
|
||
|
||
The new enumeration calls `v.inspection.Metadata().HistoricalPaths()`. Metadata
|
||
first clones every effective path and FieldInfo, including origin locations,
|
||
inheritance steps and contributor records. HistoricalPaths then reads only the
|
||
shared frozen history model; none of those copied effective records are used.
|
||
The view discards that complete metadata copy after filtering the returned paths.
|
||
|
||
**Complexity:** let P be the number of distinct historical pointers, B their
|
||
aggregate token/string size, and C the total effective-metadata copy work and
|
||
storage (effective paths, field records and nested origin data). In addition to
|
||
the deliberately reused historical enumeration's O(P log P) string comparisons,
|
||
O(B) parsing and scope-filtering work, each call incurs O(C) unnecessary time
|
||
and temporary storage. String comparison costs additionally depend on pointer
|
||
lengths. K view enumerations repeat that unused copying K times. With flat,
|
||
short paths and small origins, sorting may still dominate; this is an avoidable
|
||
additive metadata/provenance cost, not a claim that all enumeration is quadratic.
|
||
|
||
**Remediation:** enumerate through the retained private metadata directly, for
|
||
example `v.inspection.metadata.HistoricalPaths()`, then retain the same scope
|
||
filter. That existing method already constructs fresh detached Paths from the
|
||
frozen history inventory. It therefore does not need a preceding clone of the
|
||
unrelated effective fields. This removes O(C) work/storage without changing the
|
||
selected enumeration/sorting algorithm, adding a cache or inventory, or exposing
|
||
private records. Keep the public view's Metadata() and the original result's
|
||
Metadata() ownership behavior unchanged. This local bypass does not require the
|
||
broader deferred metadata-handoff redesign in future.md.
|
||
|
||
Existing scoped enumeration, numeric-shape history, root/absent/zero-view and
|
||
metadata-detachment tests are appropriate regression coverage. Do not add timing,
|
||
allocation-threshold or private-call-count tests merely for this simplification.
|
||
|
||
## Correctness review: 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.
|
||
|
||
The original correctness review identified no other required correctness,
|
||
architecture, or strengthened-contract finding. These reviews do not claim real
|
||
downstream adoption, concurrent mutation support, narrower subtree diff cost, or
|
||
a release/publication check.
|
||
|
||
## Algorithmic review: scope and conclusions
|
||
|
||
Reviewed the same implementation (`7a9ce01`, unchanged at audit checkout
|
||
`a57afc7`) stage by stage, without benchmarks or production changes:
|
||
|
||
- Stages 1–2: map and field selection use direct lookups; sequences use checked
|
||
indexing; pointer-loop detection and descriptor caching are operation-local.
|
||
Full descriptor reuse and its schema-construction costs were selected in the
|
||
plan. Finding 1 remains the separately recorded correctness issue.
|
||
- Stage 3: canonical scope construction and segment-aware containment are
|
||
straightforward; finding 3 removes an unselected, unused metadata clone from
|
||
enumeration. Unfiltered detached Metadata remains part of the chosen API.
|
||
- Stage 4: frozen-tree lookup uses the existing mapping index, followed by the
|
||
selected snapshot redaction and rendering machinery. No new finding.
|
||
- Stage 5: whole-result diff followed by scope filtering was explicitly chosen.
|
||
Its comparison/redaction/sorting costs were not reconsidered; filtering is a
|
||
single pass over differences with segment-aware containment. No new finding.
|
||
- Stage 6: history, source-context and explanation queries delegate to their
|
||
existing owners; the enumeration issue is covered by finding 3. Deferred
|
||
narrower explanation replay and shared schema caches remain outside scope.
|
||
- Stages 7–8: example registration composition and owned resource/settings copies
|
||
use ordinary linear operations in the data copied. No nested repeated search
|
||
or new algorithmic correctness issue was identified.
|
||
- Stage 9: documentation introduces no runtime algorithm. Finding 2 remains open.
|
||
|
||
Validation used Go 1.27.4 with local/offline settings. Focused public
|
||
`TestResultValue|TestInspectionView`, engine
|
||
`TestResultValue|TestMetadataHistoricalPaths|TestHistorySelection`, and consumer
|
||
`TestComponentHandoff|TestComposedConsumersShareOneLoad` tests passed with
|
||
`-count=1`. The cost analysis follows the actual call chain and loops; no empirical
|
||
performance claim or new performance guarantee is made.
|