From 320526d3fc92fac7795b4b5e65c623181680452d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 19:08:44 +0000 Subject: [PATCH] Resolve the native inspection adapter API direction --- .../configkit-v1.4.0-promptkit-v0.24.0.md | 100 +++++++++++------- 1 file changed, 63 insertions(+), 37 deletions(-) diff --git a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md index 9c2745b..5220ef5 100644 --- a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md +++ b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md @@ -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.