From eaace5bd10a0b4e151b5a75ed3021c0149dc13bf Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 12:33:28 +0000 Subject: [PATCH] Retire completed result inspection roadmaps --- docs/development.md | 6 + docs/roadmap/implementation.md | 353 --------------------------------- docs/roadmap/remediation.md | 225 --------------------- docs/roadmap/result-value.md | 244 ----------------------- 4 files changed, 6 insertions(+), 822 deletions(-) delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/remediation.md delete mode 100644 docs/roadmap/result-value.md diff --git a/docs/development.md b/docs/development.md index 87653cf..ec70dfd 100644 --- a/docs/development.md +++ b/docs/development.md @@ -95,6 +95,12 @@ and current facade ownership belongs to the [component overview](internal/overvi ## Baseline validation +The completed typed result-value and focused inspection roadmap, implementation +plan, and resolved review findings are preserved at `174e030` under +`docs/roadmap/`. Current behavior belongs to the [configuration contract](config.md) +and the public declaration comments; [ADR 0024](adr/0024-compare-inspection-views-across-application-types.md) +records the inspection comparison decision. + The completed main-relative companion roadmap, Audita request, implementation plan, and remediation report are preserved in Git history at `47547bc` under `docs/roadmap/`. The [layered loading contract](config.md#layered-loading) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 6eb81f1..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index a583132..0000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/result-value.md b/docs/roadmap/result-value.md deleted file mode 100644 index 84ae5da..0000000 --- a/docs/roadmap/result-value.md +++ /dev/null @@ -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.