Resolve the native inspection adapter API direction

This commit is contained in:
2026-11-21 19:08:44 +00:00
parent 1546122b0b
commit 320526d3fc

View File

@@ -14,6 +14,11 @@ loading, resolution, validation, preparation, inspection, and comparison.
Applications own construction, startup, credentials, and execution workflows.
Core owns shared CLI parsing, reporting, and delivery.
For this adoption, minimize complexity borne by applications first, then
complexity maintained by ckconfig. These priorities take precedence over a more
tailored operator experience. Prefer native paths, whole-load evidence, and
existing outcome handling to extra machinery for more polished subtree reports.
The [architecture policy](../policy/architecture.md) and
[integration ADR](../adr/0004-optional-integration-modules.md) govern these
boundaries. Native delegation preserves upstream meaning; it does not require
@@ -137,11 +142,39 @@ 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.
Use a small sibling of `FromConfigKit`, with `FromConfigKitSubtree` as the planned
helper name. The application supplies a scope name and summary, an explicit
`configkit.Path`, and its existing typed loader returning
`(*configkit.Result[T], error)` with the same context, selection, input, and state
parameters as `FromConfigKit`. The helper returns the existing `Scope[I, S]`.
Applications need not assemble diagnostic bundles, translate errors, or create
an intermediate inspection representation.
The adapter obtains source and diagnostic evidence from the result and selects
the native view with `InspectSubtree(path)`. For comparison, it acquires each
side's result, selects the same subtree, and calls native `Inspection.Diff`.
Share existing acquisition and diagnostic/error handling where useful without
introducing a general framework solely to remove repeated lines.
Retain whole-load diagnostics and validation outcomes. Successful loads with
warnings remain usable; detailed validation retains native findings and sources
through the existing presentation conventions. On failed loading, preserve
available ConfigKit load-error evidence and supported error identity. Other
application errors remain errors without invented ConfigKit findings. Reuse
existing classification and duplicate-presentation handling; do not silently
filter evidence to the selected subtree, ignore failures elsewhere in the load,
or create an independent subtree-validation result.
This release targets exposing a section from an ordinary typed application
result. An additional entry point for already selected inspection views and
accommodation of different root Go types across comparison sides are outside
this adoption. An options framework is unnecessary for the single path argument.
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.
type merely to fit the helper. The accepted API and evidence direction is recorded
in OD-2 below; exact declaration and internal factoring are implementation-plan
details within that direction.
### Existing commands expose the new upstream evidence
@@ -196,10 +229,10 @@ resources and reports, not just successful engine construction.
### Adapter and example work
- 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.
- Implement the accepted result-loader-plus-path API and scoped enumeration
through the shared configuration provider boundary together. Reuse existing
acquisition, diagnostics, comparison, and outcome conventions where they serve
the native capability; finalize the declaration and factoring in the plan.
- 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
@@ -254,8 +287,9 @@ layout or hash literals. Tests remain offline and credential-independent.
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.
scope commands using the ordinary typed loader and an explicit path, with a
maintained example and focused coverage of acquisition, native comparison, and
whole-load 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
@@ -292,36 +326,28 @@ 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.
The previous deferral recommendation is superseded.
## Open Decisions
### OD-2: Typed result loader, subtree path, and existing evidence handling — closed
### OD-2: Public API and diagnostics/error handoff
Adopt the result-loader-plus-path approach described under
[public native-inspection adapter](#public-native-inspection-adapter).
Prioritize application simplicity, then ckconfig implementation simplicity, over
tailoring the inspection command's presentation. The complete result already
supplies source and diagnostic evidence; accepting the application's ordinary
loader avoids a new handoff envelope or application-owned adaptation layer.
**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.
Use native paths and comparison, retain whole-load diagnostics and failures,
and reuse existing reporting and outcome conventions. Keep the helper focused
on the selected task; do not add an options framework or another entry point for
arbitrary inspection views in this adoption. Supporting preselected views and
different root types would require a broader acquisition handoff and is not
needed for the selected application workflow.
**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.
## Planning readiness
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.
No significant open decisions remain before preparing the implementation plan.
The plan should settle the exact Go declarations, shared enumeration capability,
internal factoring, example changes, and focused validation within the accepted
scope. These are engineering details, not additional product decisions or
authority to expand the contracts. Implementation and release work remain pending.