20 KiB
Implementation plan: typed result values and focused inspection
Status: implementation in progress; Stages 1–8 complete.
Scope and working instructions
Implement the agreed end state in result-value.md, including
settled OD-1 through OD-5 and accepted ADR 0024.
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, agent policy, architecture policy, testing policy, and documentation policy. 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
configkitowns 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. Valuereads currentConfig; 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
Resultmethods and genericDiff[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).
- 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 inanywithtrue, as ordinary Go assignment requires. Unsupported terminal values are still returned without conversion or revalidation. - 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.buildSchemaenforces load-root requirements andresolveSchemaPathaccepts some merely schema-valid dynamic paths; neither alone proves runtime presence. - Struct fields use
fieldByName, field index chains, and the inline-map fallback. ReusefieldForDecodewith 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. - Check actual map membership and slice/array bounds. Use
schemaIndexfor 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. - 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. - 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
Configare 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:
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
- 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.
- 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.
/amust not include/ab; escaped slashes and empty keys retain their meaning. ExistingpathHasPrefixcompares segment kinds and is not the reporting-location operation needed here. Do not alter semantic path equality elsewhere or build a new path inventory. - 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. - 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.
- 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.
- 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.
- Pass the selected node and its original application path to the existing
snapshot/redaction boundary (
safeSnapshotDocument/redactedDocument), then write with the existing YAML adapter.pathIsSecretalready checks ancestors; do not reset the selected value to root before sensitivity evaluation. - 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
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.mdowns 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.mdlinks 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.mdrecords actual helper ownership and reuse.docs/development.mdadds 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.