Resolve the native inspection adapter API direction
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user