Files
configkit/docs/roadmap/remediation.md

226 lines
14 KiB
Markdown
Raw Normal View History

2026-11-21 04:21:25 +00:00
# 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.
2026-11-21 04:21:25 +00:00
## 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.
2026-11-21 04:21:25 +00:00
**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
2026-11-21 12:01:02 +00:00
**Priority:** P3. **Status:** Complete. **Plan stage:** 9.
**Completion:** expanded Value's declaration documentation for root selection,
manual results, presence versus availability, intermediate navigation, present
nil interfaces and typed nil values, preserved terminal types, scalar leaves,
no conversion/revalidation or codec calls, and ordinary assignment ownership.
Referenced the shared schema binding contract and Path semantics. Reviewed
`go doc Result.Value`; formatting and whitespace checks passed. No runtime
behavior changed in this unit.
2026-11-21 04:21:25 +00:00
**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:** Complete. **Plan stage:** 3 (also exercised in stage 6).
**Completion:** scoped HistoricalPaths now enumerates through the retained
private metadata directly, avoiding copies of unrelated effective fields and
origins. The existing enumeration still returns detached Paths, and public
Metadata() behavior is unchanged. Focused inspection/historical-path/metadata
tests and `./scripts/check.sh` passed with Go 1.27.4. No cache, inventory,
performance threshold test, or publication gate was added.
**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
2026-11-21 04:21:25 +00:00
| 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.