Expose captured resource inspection through the engine

engine.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/promptkit/internal/backend"
 	"go.maximumdirect.net/promptkit/internal/domain"
 	internalengine "go.maximumdirect.net/promptkit/internal/engine"
 	"go.maximumdirect.net/promptkit/internal/observation"
@@ -30,6 +31,8 @@ var (
 	// ErrProfileNotFound identifies a selected profile ID that is absent from
 	// every configured profile source. It does not also match ErrProfileLoad.
 	ErrProfileNotFound = errors.New("profile not found")
+	// ErrBackendNotFound identifies a backend absent from resource inspection.
+	ErrBackendNotFound = errors.New("backend not found")
 	// ErrProfileRequired identifies a request for which neither RunRequest.ProfileID
 	// nor the selected prompt's default profile is present. Such an error also
 	// matches ErrInvalidRequest.
@@ -81,12 +84,12 @@ var (
 	ErrValidation = errors.New("failed to validate output")
 )
 
-// Engine inspects prompts and profiles, enumerates prompt requirements, and
+// Engine inspects resources, enumerates prompt requirements, and
 // prepares and runs Promptkit prompt requests.
 //
 // An Engine is safe for concurrent calls to [Engine.WithNamespaces],
 // [Engine.InspectConfiguration],
-// [Engine.InspectPrompt],
+// [Engine.InspectPrompt], [Engine.InspectBackend],
 // [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.Prepare], [Engine.PrepareExecution],
 // [Engine.Run], [Engine.RunPrepared], [Engine.SmokeTest], [Engine.ListProfiles],
 // [Engine.ListPrompts], [Engine.ListBackends], [Engine.ListNamespaces], and
@@ -267,8 +270,9 @@ func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
 // qualified IDs pass through.
 //
 // A successful result proves that the selected definition and any referenced
-// message content files were structurally loaded. Inputs are returned in
-// definition order. DefaultProfileID is declared metadata only and is not
+// message content files were structurally loaded. Inputs and captured,
+// unrendered messages are returned in definition order. DefaultProfileID is
+// declared metadata only and is not
 // resolved. OutputContract is the normalized declared contract, with a JSON
 // Schema path when declared but without loading or compiling that schema.
 // PromptHash is the same opaque equality value as PreparedRun.PromptHash for
@@ -299,7 +303,7 @@ func (e *Engine) InspectPrompt(
 	if err != nil {
 		return nil, mapPublicError(err)
 	}
-	return fromDomainPromptInspection(inspection), nil
+	return fromPromptResource(inspection), nil
 }
 
 // InspectProfile resolves one explicit profile without selecting a prompt or
@@ -310,8 +314,8 @@ func (e *Engine) InspectPrompt(
 // resource without backend completion, execution defaults, or request overrides.
 //
 // APIKeyEnv in the returned resource is an environment-variable name, never its
-// value. APIKeyRequired reports that a credential is required; an explicit
-// profile environment source can also be present. InspectProfile neither derives
+// value. APIKeyRequired, when present and true, reports that a credential is
+// required; an explicit profile environment source can also be present. InspectProfile neither derives
 // an ID from a prompt default_profile nor checks credential availability, so an
 // absent or blank named environment variable is not an error.
 //
@@ -335,7 +339,32 @@ func (e *Engine) InspectProfile(ctx context.Context, profileID string) (*Profile
 	if err != nil {
 		return nil, mapPublicError(err)
 	}
-	return fromDomainProfileInspection(inspection), nil
+	return fromProfileResource(inspection), nil
+}
+
+// InspectBackend selects a resolved backend by exact ID from the captured
+// configuration, qualifying a slashless ID with the backend namespace. It
+// reports configured resource fields and diagnostics, not credential values,
+// derived diagnostic destinations, or runtime capacity occupancy. References
+// are not resolved and no network request is made. The result and its mutable
+// values are caller-owned. Source changes require a new engine.
+//
+// An invalid engine matches ErrInvalidConfig, an invalid ID matches
+// ErrInvalidRequest, and an absent backend matches ErrBackendNotFound (not
+// ErrInvalidRequest). Cancellation remains detectable via errors.Is. No
+// partial result is returned on error.
+func (e *Engine) InspectBackend(ctx context.Context, backendID string) (*BackendInspection, error) {
+	if e == nil || e.internal == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+	inspection, err := e.internal.InspectBackend(ctx, backendID)
+	if err != nil {
+		if errors.Is(err, backend.ErrBackendNotFound) {
+			return nil, fmt.Errorf("%w: %w", ErrBackendNotFound, err)
+		}
+		return nil, mapPublicError(err)
+	}
+	return fromBackendResource(inspection), nil
 }
 
 // Prepare resolves and renders a prompt request without calling an LLM.