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
|
||||
|
||||
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)
|
||||
|
||||
@@ -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