Retire completed result inspection roadmaps

This commit is contained in:
2026-11-21 12:33:28 +00:00
parent 174e030dad
commit eaace5bd10
4 changed files with 6 additions and 822 deletions

View File

@@ -1,353 +0,0 @@
# Implementation plan: typed result values and focused inspection
Status: complete; all stages implemented and validated.
## Scope and working instructions
Implement the agreed end state in [result-value.md](result-value.md), including
settled OD-1 through OD-5 and accepted [ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md).
The runtime baseline is v1.3.0 (`652ddb6`); subsequent documentation commits
settle the API and comparison choices. Inspect the current checkout before editing.
Independent source-version policies and isolation of sibling evidence are
outside this feature.
Audience: a Luna coding agent implementing stages sequentially in one end-to-end
sprint. Intermediate stages may leave compilation temporarily incomplete; do not
add temporary public bridges or duplicate implementations to keep them green.
Private helper names and file boundaries below are implementation suggestions;
public signatures and the roadmap's behavior are selected decisions.
Start with [development guidance](../development.md), [agent policy](../policy/agents.md),
[architecture policy](../policy/architecture.md), [testing policy](../policy/testing.md),
and [documentation policy](../policy/documentation.md). Preserve unrelated work.
Use focused behavioral checks as each part becomes runnable, then perform the
final checks once the complete feature is in place. Commit completed nonempty
units according to agent policy; do not publish a release or modify dependencies.
## Implementation boundaries
- Root `configkit` owns exported declarations and explicit conversions. Engine
helpers remain private to consumers. Keep root-to-engine dependency direction
and avoid exported aliases or anonymous internal embedding.
- `Value` reads current `Config`; inspection borrows the existing frozen load
state. Neither capability loads again, projects a new execution snapshot,
runs codecs or callbacks, reads resources, or resolves secrets.
- Preserve existing `Result` methods and generic `Diff[T]`. The new non-generic
view compares frozen snapshots structurally across root Go types, as ADR 0024
explicitly permits. No runtime root-type tracking is needed.
- Reuse descriptor field bindings, path parsing/index rules, history inventories,
snapshot redaction, and the existing comparison algorithm. No new global
caches, registry, synchronization, conversion framework, or load-time snapshot
is needed. Do not impose new limits or validation on returned terminal values.
- Ordinary Go assignment governs ownership. Maps, slices, and pointers may alias
`Config`; neither deep copying nor concurrent mutation safety is promised.
Typed value availability is independent of YAML presence and load evidence.
- Reporting scope is a canonical JSON Pointer location. Explicit typed lookup,
explanation, and metadata queries retain their existing semantic path intent.
## Stage 1 — Implement private current-value navigation
**Complete.**
Read `internal/engine/schema.go`, `schema_fields.go`, `value_operation.go`,
`decode.go`, and semantic paths before adding a small engine helper, for example
in `internal/engine/result_value.go`. Accept the current Go root, an engine Path,
and the existing root-supplied Secret binding; return `(any, bool)`.
1. Reject invalid paths. For a reached terminal, return its actual Go value before
dereferencing pointers or attempting structural validation. The root selects
the entire current configuration. Nil interfaces return `(nil, true)`;
typed nil pointers/maps/slices retain their typed nil value in `any` with
`true`, as ordinary Go assignment requires. Unsupported terminal values are
still returned without conversion or revalidation.
2. For continued navigation, follow non-nil pointers/interfaces and describe the
containing type using existing operation-local schema machinery. Reuse
`schemaBuilder.describe`, descriptor kinds and field bindings; share small
helpers where needed rather than introducing a second YAML-tag parser.
`buildSchema` enforces load-root requirements and `resolveSchemaPath` accepts
some merely schema-valid dynamic paths; neither alone proves runtime presence.
3. Struct fields use `fieldByName`, field index chains, and the inline-map fallback.
Reuse `fieldForDecode` with allocation disabled if suitable; ordinary named
fields take precedence over inline-map entries. Do not allocate nil embedded
pointers. Keep ignored/unexported fields inaccessible. Convert string map keys
to the declared key type when necessary, preserving named string-key support.
4. Check actual map membership and slice/array bounds. Use `schemaIndex` for
contextual numeric tokens, canonical index spelling, and explicit key/index
intent. Text-codec scalars, duration, Secret, and other scalar descriptors are
leaves, even if represented by structs. Inspect method sets only; do not call
codecs, projection, cloning, or secret-value getters during navigation.
5. For `any`, describe its current dynamic concrete value under existing supported
type/field rules, including supported structs supplied after loading or in a
manually constructed result. Reuse dynamic descriptor machinery where its
semantics fit; do not apply projection's secret-classification admission as a
new lookup validation pass. Existing Secret descriptors remain scalar leaves.
An unsupported containing shape returns false when further navigation needs it.
6. Keep descriptor/cache state local to the call. Traverse the requested path,
using direct field/map/index selection; do not scan or project all runtime
configuration values. Recursive types must work. If pointer/interface unwrapping
can repeat without consuming a segment, detect that loop locally and return
false instead of hanging; do not reject a whole object graph for a cycle on
an unvisited branch or introduce a general cycle-validation phase.
Acceptance: navigation can distinguish missing from present nil and can return
named values without changing the configuration. Descriptor work may inspect
reachable schema types; lookup should not depend on total runtime collection size.
## Stage 2 — Expose Value and verify its public contract
**Complete.**
Add `func (r *Result[T]) Value(path Path) (any, bool)` in a focused root file,
forwarding current `r.Config`, the converted path, and the existing Secret binding.
A nil receiver returns `(nil, false)`. Any non-nil result works independently of
its inspection field, including `&Result[T]{Config: ...}`.
Add focused public tests, for example `facade_result_value_test.go`, protecting:
- Root and nested lookup, YAML/default names, inline structs/pointers/maps,
ignored and unexported fields, and literal escaped/empty keys.
- Named scalars, structs, arrays, pointers at terminals, and non-nil intermediate
pointers. Present zero/false/empty values remain available without input;
metadata separately distinguishes defaulted from explicit values.
- Dynamic maps, sequences, and supported structs in `any`, including post-load
replacements and hand-built results. Unsupported navigation fails cleanly;
reached terminals are not revalidated.
- Numeric mapping keys versus sequence indices, parsed contextual tokens,
negative/invalid indices, bounds, missing entries, and nil intermediates.
A nil interface and typed nil values are tested using their Go semantics.
- Struct/array assignment copies and pointer/map/slice aliasing. Mutations to
current `Config` are visible to Value while existing inspection stays frozen.
- Trusted access to a resolved Secret with a disposable canary and unchanged
redaction through existing inspection. A codec that fails if invoked proves
lookup does not run application codecs after construction.
Use a few readable fixtures/tables rather than one test for every helper branch.
Reuse existing schema/path tests for rules unchanged by this work. Run focused
Value tests and the public boundary tests when this stage is runnable.
## Stage 3 — Add the inspection view and canonical scope selection
**Complete.**
Add a root-owned, non-generic `Inspection` with unexported state retaining the
existing engine Inspection and normalized scope. Put scope-aware implementation
in engine (a small private-to-consumers view/helper is sufficient); do not copy the
frozen result or construct a partially populated `Result`.
Implement these public signatures:
```go
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
func (i Inspection) Metadata() Metadata
func (i Inspection) HistoricalPaths() []Path
func (i Inspection) Sources() []SourceInfo
func (i Inspection) Source(id string) (SourceInfo, bool)
func (i Inspection) SourceContext(id string) (ResourceContext, bool)
func (i Inspection) Explain(path Path) (Explanation, bool)
func (i Inspection) WriteExplanation(output io.Writer, path Path) error
```
1. Constructor failure means nil result, missing completed-load inspection, or
invalid path. A valid absent path succeeds. Normalize only after checking
validity: parse the canonical pointer spelling into contextual tokens so
explicit numeric key/index spellings select the same reporting location.
Empty scope selects the whole result.
2. Centralize a small canonical-location containment operation for enumeration
and later diff filtering. Compare pointer tokens or canonical strings with
slash boundaries and an explicit root case. `/a` must not include `/ab`;
escaped slashes and empty keys retain their meaning. Existing `pathHasPrefix`
compares segment kinds and is not the reporting-location operation needed here.
Do not alter semantic path equality elsewhere or build a new path inventory.
3. HistoricalPaths filters the existing detached, pointer-sorted enumeration to
equal/descendant locations. Preserve its order and uniqueness. Effective
presence remains available via `Metadata().Lookup(path)`; no new effective-path
public API is needed. Metadata itself remains the original unfiltered view.
4. Forward explicit Explain and WriteExplanation paths unchanged, including paths
outside the focus. Forward source catalogs/IDs and contexts without ownership
filtering. Reuse existing root conversions, extracting small shared conversion
helpers only when useful. Ancestor snapshots and dependency evidence remain
intact even when they contain siblings outside the focus.
5. A zero view uses existing unavailable-state results: empty metadata/path
enumeration, nil source catalog, false query results, and explanation-rendering
errors as appropriate. Preserve the existing detached-record and borrowed
ResourceContext ownership rules.
Add constructor/forwarding tests for root, absent scopes, malformed paths, nil and
manual results, zero views, native paths outside scope, equivalent numeric scope
spellings, escaped keys, and sibling-prefix exclusion. Do not require a scope to
exist in either effective or historical data.
## Stage 4 — Render focused effective output with original sensitivity
**Complete.**
Add `func (i Inspection) WriteEffective(output io.Writer) error` and a scoped
engine rendering operation using the saved final tree.
1. Resolve the normalized contextual scope against the frozen document with
existing document traversal. No value means an error before writing bytes;
explicit null is a present node and renders normally. A zero view or nil
writer follows existing effective-rendering failure behavior.
2. Pass the selected node and its original application path to the existing
snapshot/redaction boundary (`safeSnapshotDocument`/`redactedDocument`), then
write with the existing YAML adapter. `pathIsSecret` already checks ancestors;
do not reset the selected value to root before sensitivity evaluation.
3. Output just the selected value, with existing formatting and redaction.
Writer errors propagate normally and may leave partial output. Do not use
trusted Value output or marshal/redecode typed settings for this operation.
Add public behavioral tests for mapping/scalar/sequence/root output, null versus
absent, historical-only scopes, ancestor and descendant sensitivity, numeric
mapping/sequence scopes, and unchanged output after Config mutation. Use a
controlled failing writer for failure propagation; preserve whole-result output
coverage rather than duplicating it comprehensively.
## Stage 5 — Compare focused views using the existing diff
**Complete.**
Implement `func (i Inspection) Diff(other Inspection) ([]Difference, error)`.
Validate both initialized views and equality of normalized reporting locations
before comparison. Errors return no records; do not add root-Go-type checks.
Delegate to `engine.Diff` on the original complete frozen inspections, then
retain each record whose native Path is equal to, beneath, or above the scope.
Use the Stage 3 location helper in both directions. Preserve record order,
original paths, snapshot text, Present/Redacted flags, and HiddenChanged.
Filter before root record conversion where convenient. Reuse the existing root
Difference conversion instead of copying comparison logic.
Do not extract and compare section roots: doing so would change sequence-atomic
regions, ancestor changes, or paired sensitivity. Whole-result comparison cost
is deliberately selected; no narrower algorithm or performance experiment is
part of this implementation.
Add focused tests covering:
- Equal views, ordinary in-scope changes, sibling-only differences filtered out,
same-scope comparisons across different application root Go types, and root scope.
- Scope addition/removal, absent on both sides, explicit null, and mismatched or
zero views. Equivalent numeric scope spellings compare successfully.
- A change to a containing sequence or cross-kind ancestor retains that ancestor
record, even when its cause is outside the selected descendant. This is the
documented consequence of focusing an atomic difference, not proof the selected
value changed. Include mapping-to-sequence shape changes at numeric locations.
- Sensitivity from either side, ancestor sensitivity and sensitive removal, with
disposable canaries absent from returned snapshots and unchanged HiddenChanged
semantics. Whole-result Diff retains its existing same-type API and behavior.
Run focused view-diff tests together with the existing diff tests.
## Stage 6 — Verify history, provenance, and view ownership together
**Complete.**
Use a small loaded fixture to exercise the interactions not covered by stages
3–5. Prefer extending their fixtures rather than creating another test framework.
- Select a component with effective and removed descendants. HistoricalPaths
includes only observed equal/descendant locations, including historical-only
paths; Metadata.History and Explain retain ordinary ancestor records and native
query paths. Check the distinction between constructor success and presence.
- Retain source catalogs, locations and SourceContext through placed inputs and
an existing structural transformation such as inheritance. Assert effective
field origins lead to the original resource base. A source that contributes
siblings remains discoverable; historical-only origins do not restore a lost
effective resource origin.
- Mutate current Config after selecting the view. Value sees that mutation while
view rendering, explanation and comparison still describe the completed load.
Mutating returned query records does not alter later reports. Reuse existing
detached metadata/source tests where forwarding already protects this risk.
- Confirm contextual scope enumeration across historical key/index shape changes
without rewriting explicit query paths or collapsing existing history semantics.
Run the focused history/metadata/render/source-context tests plus the new public
view tests. This stage verifies integration, not a new confidentiality or
concurrent-mutation contract.
## Stage 7 — Demonstrate one-library handoff
**Complete.**
Add a maintained example and focused test under `examples/consumers/`, for example
`result_component.go` and `result_component_test.go`, using representative small
library-owned settings rather than adding an actual PromptKit dependency.
Show an application-owned root and a library-owned consumer interface using
Value, Metadata, and SourceContext. The application passes the whole result;
the library selects its conventional path and asserts its public settings type.
Registration uses an ordinary typed field selector and existing Definition hooks
for defaults, normalization, validation, sensitivity and sequence identities.
Bundled defaults enter as ordinary underlays where needed. Runtime construction
and resource capture remain library/application responsibilities.
Show a library-owned inspection facade selecting InspectSubtree once and
forwarding effective output, explicit native-path queries and view comparison.
Test one normal load followed by handoff, useful typed values, presence/origin,
safe reporting, a relative resource resolved from its effective source, and a
component validation failure during the application load. Do not create a new
ConfigKit registration API or a second library-specific load.
## Stage 8 — Demonstrate two-library composition
**Complete.**
Extend the example with a second small consumer using the same application
result and a smaller consumer-owned interface where sufficient. Compose existing
application and library callbacks with explicit ordering and authoritative
sequence identity registrations. Use fresh per-load state rather than shared
mutable registration captures.
Verify both consumers receive their own named settings from the same result,
application rules still run, explicit values survive absence-based defaults,
invalid component identities fail through the normal lifecycle, and source
contexts remain usable through placement/inheritance. Include repeated loads to
show callback/default state does not leak. Reuse Stage 7's fixtures and existing
source-operation tests; demonstrate representative integration without multiplying
every layering/import/override combination. Do not modify downstream repositories
or claim completion of real PromptKit integration.
## Stage 9 — Document the implemented boundary and validate the sprint
**Complete.**
Update documentation only once the corresponding behavior exists:
- Declaration comments own signatures, nil/absence behavior, ordinary aliasing,
trusted values, current Config versus frozen evidence, and reporting-only scope.
Document canonical scope equivalence on InspectSubtree and errors on unavailable
output or invalid comparisons. Do not add public error codes/sentinels merely
for this feature; use existing error style.
- `docs/config.md` owns shared ownership/inspection and comparison behavior.
Distinguish same-type Diff[T] from cross-root-type view comparison, ancestor
differences and paired redaction, and value availability from input presence.
- `docs/consumers/README.md` links the maintained examples and explains one-load
registration, whole-result handoff, owned runtime settings, and native paths.
Link from README only with a short useful orientation entry.
- `docs/internal/overview.md` records actual helper ownership and reuse.
`docs/development.md` adds focused test guidance and ADR 0024 navigation.
Update the architecture policy's comparison wording to include accepted
ADR 0024 while preserving its existing provenance and other constraints.
- Update roadmap status accurately. Retain historical release records and the
deferred candidates in future.md. Release notes/publication are a separate task.
Run the focused tests introduced above, `go test -race ./...`, and the everyday
`./scripts/check.sh` using an installed compatible toolchain and pre-acquired
dependencies. The everyday check supplies formatting, whitespace, tests, vet and
build validation. Run the consumer examples and existing public API/dependency
boundary checks through their ordinary tests. Review changed Markdown links and
all newly documented behavior against the implementation; no new release gate,
performance threshold or benchmark requirement is introduced.
Completion review must establish that both consumers use one application result,
current typed access follows existing field/path conventions, frozen inspection
preserves native evidence and sensitivity, cross-type view comparison follows
ADR 0024, and whole-result loading/inspection remains compatible. Review the full
diff for accidental stronger contracts, unsafe reflect access and duplicated
machinery. Commit validated, nonempty work with plain-English messages and report
remaining limitations accurately.
## Open Questions
None. OD-1 through OD-5 and ADR 0024 settle the decisions required for this scope.
Private naming and file organization remain ordinary implementation choices.

View File

@@ -1,225 +0,0 @@
# 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:** 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.
**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
| 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.

View File

@@ -1,244 +0,0 @@
# Typed value access and focused inspection from a result
Status: implemented; OD-1 through OD-5 settled. See the current
[configuration contract](../config.md) and declaration comments for behavior.
Baseline: v1.3.0, commit `652ddb6`.
## Purpose and baseline
Let an application load configuration once and pass the whole result to libraries
such as PromptKit and FeedKit. Each library selects its conventional section,
checks its public settings type, and constructs its runtime objects. Libraries
can also offer inspection focused on their section. Section names remain library
conventions, not ConfigKit reserved keys.
At the baseline, [Result.Config](../../lifecycle.go) supplied trusted typed values, but its
generic root type prevented a library from selecting a field without knowing the
application type or adding its own traversal. Existing metadata and
[source contexts](../../resource_context.go) already support field provenance and
resource lookup. Baseline inspection and comparison operated on completed-load
snapshots, but there was no reusable subtree reporting view. Redacted inspection
snapshots are not execution inputs.
PromptKit has accepted the typed-value direction. The subsequently agreed
inspection addition supports libraries such as PromptKit that expose an
`InspectConfiguration()` API and want its ordinary reports to focus on their own
configuration. Independent source-version policies, a component registry, and a
new configuration conversion API remain outside this roadmap.
## Targeted end state
Add two complementary capabilities: trusted access to current typed settings,
and a lightweight reporting view over existing frozen inspection state.
The inspection comparison extension is recorded in
[ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md), which
extends [ADR 0010](../adr/0010-effective-configuration-diff.md).
### Typed value access
Add the public method:
```go
func (r *Result[T]) Value(path Path) (any, bool)
```
The method selects a current value from `r.Config`. It performs no loading,
decoding, defaulting, normalization, validation, resource acquisition, or secret
lookup. It does not invoke application text codecs or render configuration.
Libraries perform ordinary Go type assertions; ConfigKit does not convert the
selected value into a requested component type.
### Values, ownership, and inspection
- Return the actual terminal Go value, preserving named types, pointers, and
resolved `Secret` values. Do not dereference a terminal pointer automatically.
An interface contributes its current dynamic value under ordinary Go semantics.
- Use ordinary Go assignment semantics. Structs and arrays are copied as values;
pointers, maps, and slices can share underlying state with `Result.Config`.
There is no deep-copy or additional frozen execution snapshot guarantee.
- Read current configuration state, including caller changes made after loading.
Existing inspection continues to describe the completed load. Document the
distinction and recommend handoff before mutations invalidate that evidence;
do not add mutation detection or synchronization.
- This is trusted access, like `Result.Config`, and does not redact. Consumers
capture owned settings where needed and use existing inspection for safe output.
- A found nil pointer, map, slice, or interface is distinct from an unavailable
path. In particular, `(nil, true)` is possible. A zero/defaulted struct field
may be found without YAML input; source presence remains a metadata question.
- **OD-1 settled:** return `(nil, false)` for a nil receiver. Any non-nil result
exposes its current `Config` through the same traversal rules, including a
manually constructed result without load or inspection state. Lookup success
establishes value availability only, not validation or corresponding load
evidence. This matches direct field access and supports hand-built fixtures
without coupling typed access to inspection. `InspectSubtree` still requires
completed-load inspection state.
### Path traversal
Use the existing [Path](../../path.go) and
[schema binding](../config.md#application-schema-binding) rules. The root path
selects `Config`. Struct paths use YAML names or the existing default field names,
including flattened inline fields and inline maps. Ignored and unexported fields
do not become navigable paths. Typed scalars, including text-codec types and
`Secret`, remain leaves even when their Go representation is a struct.
Mapping keys and sequence indices retain their semantic distinction; parsed
numeric tokens resolve according to the containing value. Check current map
membership and slice/array bounds. Follow non-nil intermediate pointers and
interfaces only when navigation continues. Do not allocate missing maps or
pointer targets, including nil inline embeddings, to satisfy a lookup.
Return `(nil, false)` for malformed paths, missing keys, out-of-range indices,
incompatible segments, or traversal through nil or a scalar. Declared schema
validity alone does not make a runtime descendant available.
**OD-2 settled:** navigate current values inside `any` using ConfigKit's existing
supported types and field-binding rules, including supported structs and their
YAML field names. Apply the same rules to values supplied during loading,
post-load replacements, and manually constructed results. Reuse existing runtime
type-description machinery as appropriate; do not restrict navigation to
YAML-decoded maps and slices or introduce a second Go-object navigation model.
Intermediate pointers and interfaces follow the rules above, and scalar types
remain leaves. Return `(nil, false)` when continued traversal requires an
unsupported shape. At a reached terminal, return the actual current value
without conversion or revalidation. Lookup does not invoke application codecs
or establish new secret-classification semantics.
### Subtree-focused inspection
**OD-3 settled:** provide a non-generic `Inspection` view, selected once from a
result:
```go
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool)
func (i Inspection) Diff(other Inspection) ([]Difference, error)
```
For example:
```go
inspection, ok := result.InspectSubtree(configkit.Keys("promptkit"))
```
The view retains existing completed-load inspection state and a selected path.
It does not load, decode, resolve, validate, or create another execution snapshot.
Later changes to `Result.Config` do not change its evidence. It is a reporting
focus, not an access-control or isolation boundary.
`InspectSubtree` returns false for a nil result, unavailable completed-load
inspection state, or malformed path. A valid absent scope succeeds. The root
path selects the whole configuration. Use familiar methods: `WriteEffective`,
`Explain`, `WriteExplanation`, `Metadata`, `Sources`, `Source`, and `SourceContext`.
The view's `HistoricalPaths` provides focused enumeration; `Metadata()` retains
its existing unfiltered query behavior. Effective presence is checked with
metadata lookup. Forwarded operations retain their existing unavailable-state
behavior for a zero view.
- **Effective output:** render the selected subtree using existing frozen values
and redaction, without the enclosing application mappings. Preserve sensitivity
inherited from ancestors; do not reclassify an extracted value as a new root.
**OD-4 settled:** if no selected effective value exists, `WriteEffective` returns
an error without output. Explicit null renders normally. An absent value does
not invalidate the view or prevent history, queries, or comparison. Ordinary
writer failures retain existing behavior and may leave partial output.
- **Path discovery:** enumerate existing effective and historical paths at or
beneath the selected path, retaining existing ordering and path semantics.
Reuse historical enumeration and effective lookup rather than introducing
another path inventory.
- **Explicit queries:** explanation, explanation rendering, metadata lookup, and
history queries use native application paths and existing behavior. Explicit
queries may name paths outside the selected subtree. Existing metadata can
remain available unchanged; focused enumeration belongs to the view.
- **Context:** retain existing source IDs, locations, source catalogs, and resource
contexts. Do not determine exclusive source ownership by subtree. Ancestor
snapshots, dependency references, and other contextual evidence may include
configuration outside the focus. Do not trim or rewrite that evidence.
- **Comparison:** compare original frozen configurations with the existing diff
behavior, then retain differences at, beneath, or above the selected path.
Preserve sequence-atomic comparison, ordering, equality, paired redaction, and
existing difference records. An ancestor difference can reflect changes outside
the focus: a nonempty report does not necessarily mean the selected values
themselves changed. Compare views selecting the same native application path;
uninitialized views or mismatched scopes return an error and no differences.
Compare snapshots regardless of the original application Go root types, without
adding runtime root-type tracking or compatibility checks. Existing `Diff[T]`
retains its signature and same-type contract. Cross-location comparison is
not part of this addition.
- **Absent scopes:** selecting a scope does not assert current or historical
presence. A valid path can select an absent, historical-only, or explicit-null
section. This supports optional sections and comparisons where a section was
added or removed. Constructor success must not mean current value presence;
ordinary queries retain their existing absence and null distinctions.
Keep native application paths throughout; for example, `/promptkit/prompts`
remains `/promptkit/prompts` in queries, explanations, history, and differences.
Reuse existing public result types such as `Explanation`, `Difference`, and
`ValueSnapshot`. No new confidentiality, deep-copy, or concurrent-mutation
guarantee is implied.
**OD-5 settled:** identify the view's reporting scope by canonical JSON Pointer
location. Normalize the constructor's valid path to that contextual selector;
numeric tokens follow the containing shape when rendering effective output.
Use the same location and segment-aware containment for focused enumeration,
diff filtering, and scope equality, rather than raw string-prefix matching.
For example, `Keys("items", "0")`, `Keys("items").Index(0)`, and a parsed
`/items/0` all select the same reporting scope. This follows historical reporting's
location model and does not require a present value to establish scope identity.
Document this behavior on `InspectSubtree`. Explicit `Value`, `Explain`, and
metadata queries retain their existing key/index intent and contextual traversal
rules; the view does not rewrite those query paths.
## Consumer integration
A library may define its own input interface; ConfigKit need not introduce a
shared component interface or configuration wrapper:
```go
type Configuration interface {
Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool)
}
```
PromptKit selects `Value(configkit.Keys("promptkit"))` and asserts its settings
type. FeedKit can use a smaller interface if it needs only values. Both receive
the same application result. Paths remain application-root paths. Resource lookup
uses effective field origins and original source contexts; historical evidence
does not restore a lost effective origin.
A library that offers inspection can additionally request `InspectSubtree` through
its consumer-owned interface and retain the returned view. PromptKit can forward
the focused operations through `InspectConfiguration()` without constructing or
loading another configuration. Its adapter may still need changes for native
application paths and the agreed broader contextual evidence; this roadmap does
not promise unchanged downstream method signatures. The view is separate from
`Result[T]`, not a partially populated result or a new typed configuration.
Before loading, library-owned helpers incorporate public settings, defaults,
normalization, validation, sensitivity, and sequence identities into the
application's existing `Definition[T]`. One typed field selector per library is
acceptable registration wiring. Helpers preserve application rules, keep callback
ordering explicit, and avoid shared mutable per-load state. Desired bundled
resources enter the original load as ordinary underlays.
Representative one-library and two-library probes passed using existing lifecycle
APIs and a limited stand-in for `Value`. They establish feasibility, not completion
of real PromptKit integration. PromptKit still owns its public settings model,
presence-state handling, resource capture, and settings ownership refactoring.
## Delivery scope and completion
The [implementation plan](implementation.md) owns execution order and validation.
The change includes private typed traversal using existing schema bindings, the
root-owned value accessor and inspection view, focused behavioral coverage,
maintained one-library and two-library examples, and updates to the public
contracts and consumer guidance. Architecture and comparison documentation will
reflect ADR 0024 when its implementation lands.
Completion means both representative library consumers can obtain their typed
settings and existing provenance from one application result without application
extraction, reshaping, serialization, or a second load, and a library can offer
focused inspection using the same completed result. Independently versioned
source support is not required. The intended release is additive: existing
loading and inspection callers need not adopt either new capability.