From c669f146109a37b8db5b2129ff121c0f55222ddf Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 03:29:41 +0000 Subject: [PATCH] Record backend inspection error decision --- docs/roadmap/inspect-backend.md | 38 +++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/roadmap/inspect-backend.md b/docs/roadmap/inspect-backend.md index f46ec4f..1cd7f84 100644 --- a/docs/roadmap/inspect-backend.md +++ b/docs/roadmap/inspect-backend.md @@ -153,7 +153,8 @@ backend scope, pass qualified IDs through, and report the selected full ID. Use the same identity rules for bundled and caller-supplied backends. The new operation should follow existing inspection conventions for invalid engines, invalid selections, and context cancellation, without adding cross-error -precedence guarantees. Missing-backend classification is open decision 1. +precedence guarantees. Missing-backend classification follows accepted decision 1 +below. ### Effective Diagnostic Destinations @@ -233,18 +234,37 @@ remains separate. Live capacity monitoring, provider health guarantees, and source round-tripping are not selected deliverables, rather than permanent prohibitions on future work. -## Open Decisions +## Decisions + +Decision 1 is accepted; decisions 2–5 remain open. Implementation is pending. ### 1. How Should An Unknown Backend Be Classified? -**Recommendation:** Add public `ErrBackendNotFound`, analogous to the existing -prompt/profile sentinels. The registry already identifies missing backends; -public mapping lets consumers distinguish a missing ID without parsing text. -Keep existing operations' classifications unless a change is explicitly chosen. +**Status:** Accepted; implementation pending. -**Alternative:** Use `ErrInvalidRequest`, avoiding another exported sentinel but -combining malformed selection and a well-formed missing identity. Consumers that -need the distinction would require inventory lookup or other error detail. +**Decision:** Add public `ErrBackendNotFound` for an absent backend selected by +`InspectBackend`, following the existing prompt/profile sentinel pattern. +An ordinary missing-backend lookup should match `ErrBackendNotFound` through +`errors.Is` and should not also match `ErrInvalidRequest`. Reuse the registry's +existing internal missing-backend classification at the public boundary. + +Invalid selections follow existing ID rules and match `ErrInvalidRequest`; +invalid engines match `ErrInvalidConfig`. Preserve context cancellation through +the existing inspection conventions. Invalid backend definitions remain an +engine-construction concern. Exact error wording is not a new contract. + +Initially apply the new public classification to `InspectBackend`; do not +implicitly reclassify construction or smoke-test failures. CommandKit owns +operator wording and exit-status selection. + +**Rationale:** This gives consumers a useful distinction with a small addition +consistent with prompt and profile inspection, without a new error hierarchy. + +**Alternatives considered:** Using `ErrInvalidRequest` saves one public sentinel +but combines malformed selections and missing identities. A typed generic +resource-not-found error could carry resource kind and ID, but adds a broader +contract and integration questions for existing sentinels. Neither is selected; +the caller already knows the operation and requested ID. ### 2. How Much Engine-Policy Reporting Belongs In This Round?