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.
|
Applications own construction, startup, credentials, and execution workflows.
|
||||||
Core owns shared CLI parsing, reporting, and delivery.
|
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
|
The [architecture policy](../policy/architecture.md) and
|
||||||
[integration ADR](../adr/0004-optional-integration-modules.md) govern these
|
[integration ADR](../adr/0004-optional-integration-modules.md) govern these
|
||||||
boundaries. Native delegation preserves upstream meaning; it does not require
|
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
|
outcome conventions. A focused inspection does not independently validate a
|
||||||
subtree or make whole-load evidence local to it.
|
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
|
PromptKit uses the shared inspection capability directly. It need not pass
|
||||||
through this new helper if that would require converting its public inspection
|
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
|
type merely to fit the helper. The accepted API and evidence direction is recorded
|
||||||
discussion in OD-2; acceptance of the feature does not select a new result type,
|
in OD-2 below; exact declaration and internal factoring are implementation-plan
|
||||||
loader framework, or diagnostics policy.
|
details within that direction.
|
||||||
|
|
||||||
### Existing commands expose the new upstream evidence
|
### Existing commands expose the new upstream evidence
|
||||||
|
|
||||||
@@ -196,10 +229,10 @@ resources and reports, not just successful engine construction.
|
|||||||
|
|
||||||
### Adapter and example work
|
### Adapter and example work
|
||||||
|
|
||||||
- Design the adapter's public API and evidence handoff, then implement scoped
|
- Implement the accepted result-loader-plus-path API and scoped enumeration
|
||||||
enumeration through the shared configuration provider boundary and the public
|
through the shared configuration provider boundary together. Reuse existing
|
||||||
ckconfig adapter together. Reuse existing acquisition, diagnostics, comparison,
|
acquisition, diagnostics, comparison, and outcome conventions where they serve
|
||||||
and outcome conventions where they serve the native capability.
|
the native capability; finalize the declaration and factoring in the plan.
|
||||||
- Wire PromptKit's native enumeration directly through the shared capability;
|
- Wire PromptKit's native enumeration directly through the shared capability;
|
||||||
avoid an extra conversion layer solely to reuse the new adapter.
|
avoid an extra conversion layer solely to reuse the new adapter.
|
||||||
- Demonstrate registration and inspection of one application subtree, including
|
- 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
|
metadata descriptions still work. A representative whole-load sibling verifies
|
||||||
that the adapter does not substitute full metadata enumeration.
|
that the adapter does not substitute full metadata enumeration.
|
||||||
- [ ] The public ckconfig adapter exposes a native subtree through the standard
|
- [ ] The public ckconfig adapter exposes a native subtree through the standard
|
||||||
scope commands, with a maintained example and focused coverage of acquisition,
|
scope commands using the ordinary typed loader and an explicit path, with a
|
||||||
comparison, and diagnostics/error propagation. Its public handoff is documented.
|
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
|
- [ ] Explicit paths, source evidence, focused rendering, and comparison preserve
|
||||||
native meaning and error handling, including available ancestor evidence.
|
native meaning and error handling, including available ancestor evidence.
|
||||||
- [ ] Reports preserve returned schema fields, repair-budget zero, and the new
|
- [ ] 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
|
standard CLI scopes and direct upstream inspection. Preserve native comparison
|
||||||
semantics for the views accepted by the selected API.
|
semantics for the views accepted by the selected API.
|
||||||
|
|
||||||
The previous deferral recommendation is superseded. The remaining API discussion
|
The previous deferral recommendation is superseded.
|
||||||
does not reopen whether to include the feature.
|
|
||||||
|
|
||||||
## 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
|
Use native paths and comparison, retain whole-load diagnostics and failures,
|
||||||
loader plus an explicit subtree path.** A sibling of `FromConfigKit` can obtain
|
and reuse existing reporting and outcome conventions. Keep the helper focused
|
||||||
diagnostics and source evidence from the result, select `InspectSubtree(path)`,
|
on the selected task; do not add an options framework or another entry point for
|
||||||
and delegate comparison to the native inspection views. On failed loading,
|
arbitrary inspection views in this adoption. Supporting preselected views and
|
||||||
reuse the existing handling of ConfigKit load-error evidence and supported error
|
different root types would require a broader acquisition handoff and is not
|
||||||
identity. This keeps the ordinary application loader reusable and avoids asking
|
needed for the selected application workflow.
|
||||||
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.
|
|
||||||
|
|
||||||
**Viable alternative: accept an already selected `configkit.Inspection` with
|
## Planning readiness
|
||||||
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.
|
|
||||||
|
|
||||||
For either approach, retain the existing distinction between report evidence
|
No significant open decisions remain before preparing the implementation plan.
|
||||||
and a returned error. Discuss how native diagnostics reach detailed validation,
|
The plan should settle the exact Go declarations, shared enumeration capability,
|
||||||
ordinary messages, and terminal explanations without duplicate presentation.
|
internal factoring, example changes, and focused validation within the accepted
|
||||||
Existing error classification remains authoritative; the scope's reporting focus
|
scope. These are engineering details, not additional product decisions or
|
||||||
does not imply that unrelated load failures can be ignored or that validation is
|
authority to expand the contracts. Implementation and release work remain pending.
|
||||||
limited to the selected subtree.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user