Include native inspection adapter in the adoption scope

This commit is contained in:
2026-11-21 18:55:50 +00:00
parent 71ba758a09
commit 1546122b0b

View File

@@ -28,7 +28,7 @@ Reviewed repository revision: `b1c7962f51eb9e81104a291bc1966a90b4e772a3`.
| Component | Baseline | Adoption target |
| --- | --- | --- |
| CommandKit core | v0.7.0 | No core change required by this scope |
| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0 and native scoped path enumeration support |
| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0, native scoped path enumeration, and a public native-inspection adapter |
| ckprompt | v0.10.0; PromptKit v0.23.2, ConfigKit v1.2.1, ckconfig v0.9.0 | PromptKit v0.24.0, ConfigKit v1.4.0, and the resulting released ckconfig |
| Go | Consumer minimum 1.27.0; release toolchain 1.27.4 | No change required by these upstream releases |
@@ -121,6 +121,28 @@ their native whole-document meaning. An absent effective subtree and explicit
null retain their upstream distinction and errors through the existing report
delivery mechanism. Do not invent an empty configuration to hide absence.
### Public native-inspection adapter
Include a reusable ckconfig adapter in this adoption and the next ckconfig
release. It registers a named configuration scope backed by ConfigKit's native
subtree inspection, reducing application wiring for effective settings, path
discovery, explanations, source evidence, and comparison. Applications retain
configuration acquisition and selection; the adapter supplies standard CLI
integration and delegates domain operations to ConfigKit.
Design this adapter together with the shared native path-enumeration capability.
Demonstrate one application section, such as storage settings, in the maintained
composed example. The section name is illustrative, not a new reserved scope.
Preserve load diagnostics and error evidence through existing reporting and
outcome conventions. A focused inspection does not independently validate a
subtree or make whole-load evidence local to it.
PromptKit uses the shared inspection capability directly. It need not pass
through this new helper if that would require converting its public inspection
type merely to fit the helper. Exact API shape and evidence handoff remain under
discussion in OD-2; acceptance of the feature does not select a new result type,
loader framework, or diagnostics policy.
### Existing commands expose the new upstream evidence
| Operator task | Existing command | Adoption behavior |
@@ -174,8 +196,14 @@ resources and reports, not just successful engine construction.
### Adapter and example work
- Implement scoped enumeration through the shared configuration provider boundary
and wire the native PromptKit method directly.
- Design the adapter's public API and evidence handoff, then implement scoped
enumeration through the shared configuration provider boundary and the public
ckconfig adapter together. Reuse existing acquisition, diagnostics, comparison,
and outcome conventions where they serve the native capability.
- Wire PromptKit's native enumeration directly through the shared capability;
avoid an extra conversion layer solely to reuse the new adapter.
- Demonstrate registration and inspection of one application subtree, including
comparison and preservation of available diagnostics on failure.
- Restructure the composed example around the shared load, with local fixtures
and the existing injected client for smoke demonstrations. Update its consumer
walkthrough and meaningful tests together.
@@ -225,6 +253,9 @@ layout or hash literals. Tests remain offline and credential-independent.
- [ ] Scoped path enumeration uses upstream's listing; existing CLI filters and
metadata descriptions still work. A representative whole-load sibling verifies
that the adapter does not substitute full metadata enumeration.
- [ ] The public ckconfig adapter exposes a native subtree through the standard
scope commands, with a maintained example and focused coverage of acquisition,
comparison, and diagnostics/error propagation. Its public handoff is documented.
- [ ] Explicit paths, source evidence, focused rendering, and comparison preserve
native meaning and error handling, including available ancestor evidence.
- [ ] Reports preserve returned schema fields, repair-budget zero, and the new
@@ -250,33 +281,47 @@ This roadmap selects no new commands, engine-construction convenience API,
automatic configuration migration, core cache, or application execution workflow.
These are scope decisions for this adoption, not additional permanent prohibitions.
## Resolved decisions
### OD-1: Include the native-inspection adapter in this adoption — closed
Include the helper in the next ckconfig release, as part of this roadmap.
Its implementation overlaps the required native enumeration work; designing both
together provides a concrete second use of the shared boundary and avoids
revisiting that boundary immediately after release. Keep the adapter focused on
standard CLI scopes and direct upstream inspection. Preserve native comparison
semantics for the views accepted by the selected API.
The previous deferral recommendation is superseded. The remaining API discussion
does not reopen whether to include the feature.
## Open Decisions
### OD-1: Add a general native-inspection adapter to ckconfig now?
### OD-2: Public API and diagnostics/error handoff
ConfigKit's non-generic `Inspection` could support a reusable public adapter for
applications exposing additional subtree scopes, including native comparison
across different root Go types. This is separate from the required narrow path
enumeration support used by `ckprompt.ConfigScope`.
**Recommendation for discussion: accept the existing typed ConfigKit result
loader plus an explicit subtree path.** A sibling of `FromConfigKit` can obtain
diagnostics and source evidence from the result, select `InspectSubtree(path)`,
and delegate comparison to the native inspection views. On failed loading,
reuse the existing handling of ConfigKit load-error evidence and supported error
identity. This keeps the ordinary application loader reusable and avoids asking
applications to package inspection and diagnostics into a new envelope. The
tradeoff is that a callback returning only an already selected native inspection,
or different root result types across comparison sides, does not fit this typed
loader signature directly. The proposed name and signature are not yet selected.
**Recommendation: defer the additional public adapter from this sprint.** The
existing typed `FromConfigKit` adapter serves the application's result, and
`ckprompt.ConfigScope` serves the engine's inspection. Shared loading itself
does not require a third adapter. Keep the required native enumeration capability
small, and use the revised example to identify any actual remaining boilerplate
before selecting another public contract. The tradeoff is that applications
wanting additional native subtree scopes must currently assemble the existing
scope/provider contract themselves.
**Viable alternative: accept an already selected `configkit.Inspection` with
its associated acquisition evidence.** This directly serves callers holding
native views and allows native comparison across different root Go types.
However, the view itself has no diagnostics method, and a failed load may provide
sources and diagnostics without any usable view. The API would need a way to
carry that evidence, adding application wiring or a public handoff type. Evaluate
that complete handoff against the result-and-path approach before selecting it;
do not require callers to reconstruct provenance or stringify structured errors.
**Viable alternative: include a focused native-inspection adapter now.** This
could standardize useful CLI subtree scopes and avoid repeated acquisition and
comparison wiring across applications. It belongs in ckconfig because it serves
operator commands, not application-internal configuration access. However, native
`Inspection` does not itself carry the result's diagnostics or acquisition
errors; the helper's inputs must account for that evidence without becoming a
second result type or loader framework. Before selecting this alternative,
demonstrate a concrete scope in the maintained example and compare the complete
wiring burden and conceptual cost against using the existing provider API.
This choice does not reopen the agreed requirement to delegate PromptKit path
enumeration and explicit queries to the native upstream methods.
For either approach, retain the existing distinction between report evidence
and a returned error. Discuss how native diagnostics reach detailed validation,
ordinary messages, and terminal explanations without duplicate presentation.
Existing error classification remains authoritative; the scope's reporting focus
does not imply that unrelated load failures can be ignored or that validation is
limited to the selected subtree.