Use stable usecase sentinels for HTTP invalid-request mapping

internal/usecase/runner.go

@@ -24,12 +24,14 @@ import (
 )
 
 var (
-	ErrInvalidRequest = errors.New("invalid run request")
-	ErrProfileLoad    = errors.New("failed to load prompt definition")
-	ErrArtifactLoad   = errors.New("failed to load artifact")
-	ErrPromptRender   = errors.New("failed to render prompt")
-	ErrLLMGenerate    = errors.New("failed to generate output")
-	ErrValidation     = errors.New("failed to validate output")
+	ErrInvalidRequest   = errors.New("invalid run request")
+	ErrProfileRequired  = errors.New("profile selection is required")
+	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
+	ErrProfileLoad      = errors.New("failed to load prompt definition")
+	ErrArtifactLoad     = errors.New("failed to load artifact")
+	ErrPromptRender     = errors.New("failed to render prompt")
+	ErrLLMGenerate      = errors.New("failed to generate output")
+	ErrValidation       = errors.New("failed to validate output")
 )
 
 // Runner executes the Scriptorium core use case.
@@ -177,7 +179,7 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 		selectedProfileID = strings.TrimSpace(def.DefaultProfile)
 	}
 	if selectedProfileID == "" {
-		return nil, fmt.Errorf("%w: profile id is required either in request or prompt default_profile", ErrInvalidRequest)
+		return nil, fmt.Errorf("%w: %w: profile id is required either in request or prompt default_profile", ErrInvalidRequest, ErrProfileRequired)
 	}
 
 	execProfile, err := r.profiles.GetProfile(ctx, selectedProfileID)
@@ -376,7 +378,7 @@ func validateAPIKeyEnv(apiKeyEnv string) error {
 		return nil
 	}
 	if strings.TrimSpace(os.Getenv(envName)) == "" {
-		return fmt.Errorf("api key environment variable %q is not set", envName)
+		return fmt.Errorf("%w: api key environment variable %q is not set", ErrAPIKeyEnvMissing, envName)
 	}
 	return nil
 }

internal/usecase/runner_test.go

@@ -234,6 +234,9 @@ func TestRunnerPrepareMissingExplicitProfileAndMissingDefaultProfileFails(t *tes
 	if !errors.Is(err, ErrInvalidRequest) {
 		t.Fatalf("expected ErrInvalidRequest, got %v", err)
 	}
+	if !errors.Is(err, ErrProfileRequired) {
+		t.Fatalf("expected ErrProfileRequired, got %v", err)
+	}
 }
 
 func TestRunnerPrepareSelectedProfileDoesNotExistFails(t *testing.T) {
@@ -862,6 +865,9 @@ func TestRunnerRunAPIKeyEnvMissingEnvironmentValueFailsClearly(t *testing.T) {
 	if !errors.Is(err, ErrInvalidRequest) {
 		t.Fatalf("expected ErrInvalidRequest, got %v", err)
 	}
+	if !errors.Is(err, ErrAPIKeyEnvMissing) {
+		t.Fatalf("expected ErrAPIKeyEnvMissing, got %v", err)
+	}
 	if !strings.Contains(err.Error(), "SCRIPTORIUM_MISSING_KEY") {
 		t.Fatalf("expected missing env name in error, got %v", err)
 	}