Retire completed result inspection roadmaps
This commit is contained in:
@@ -95,6 +95,12 @@ and current facade ownership belongs to the [component overview](internal/overvi
|
|||||||
|
|
||||||
## Baseline validation
|
## 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
|
The completed main-relative companion roadmap, Audita request, implementation
|
||||||
plan, and remediation report are preserved in Git history at `47547bc` under
|
plan, and remediation report are preserved in Git history at `47547bc` under
|
||||||
`docs/roadmap/`. The [layered loading contract](config.md#layered-loading)
|
`docs/roadmap/`. The [layered loading contract](config.md#layered-loading)
|
||||||
|
|||||||
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
Reference in New Issue
Block a user