13 KiB
Result value and focused inspection review
Reviewed implementation: 7a9ce01 (against planning baseline b3799be).
Scope: the nine stages of implementation.md, the settled
result-value roadmap, and accepted
ADR 0024.
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. All findings below remain open.
1. Terminal availability still depends on recursive schema validity
Priority: P2. Status: Open. Plan stages: 1–2.
Relevant code: ResultValue, especially its descriptor construction at line 33; the recursive map/slice/array and struct branches of schemaBuilder.describe.
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):
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, with the existing configuration ownership contract and schema binding rules 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, line 62;
Inspection.Metadata in load.go;
cloneMetadata in load_metadata.go;
and the existing enumeration in
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.shpassed: 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.