refactor(R2d.114): carve internal/api/aiautomation subpackage

Move ai_automation_handler.go + test (nl-automation-builder) into aiautomation subpkg. Distinct from existing automation subpkg (non-AI). Router uses aiautomation.NewHandler; AIHandlers.Automation field accepts it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: atulmgupta

internal/api/aiautomation/doc.go

@@ -0,0 +1,5 @@
+// Package aiautomation owns the AI automation builder HTTP handler and its
+// nl-automation-builder graph validator.
+//
+// Layer: handler
+package aiautomation

internal/api/ai_automation_handler.go internal/api/aiautomation/handler.gointernal/api/ai_automation_handler.go renamed to internal/api/aiautomation/handler.go

@@ -1,8 +1,8 @@
-package api
+package aiautomation
 
 // Phase-50 / 0016 — N2 Natural-language automation builder.
 //
-// ai_automation_handler.go implements the LLM-backed handler at
+// handler.go implements the LLM-backed handler at
 // POST /api/v1/ai/automations/draft. The flow mirrors the
 // nl-alert-builder handler from slice 0015 — same dispatch+stream
 // loop, same propose-only contract, no persistence (one-shot
@@ -53,6 +53,7 @@ package api
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -67,39 +68,40 @@ import (
 	"github.com/ev-dev-labs/teslasync/internal/ai/stream"
 	"github.com/ev-dev-labs/teslasync/internal/ai/tools"
 	apiautomation "github.com/ev-dev-labs/teslasync/internal/api/automation"
+	apihttpx "github.com/ev-dev-labs/teslasync/internal/api/httpx"
 	tsauth "github.com/ev-dev-labs/teslasync/internal/auth"
 )
 
-// aiAutomationBuilderMaxIterations bounds the dispatcher's tool-loop.
+// builderMaxIterations bounds the dispatcher's tool-loop.
 // The nl-automation-builder strategy is a two-tool sequence (draft,
 // then validate), with at most one retry if validate rejects the
 // first draft — a hard ceiling of 6 is generous for an LLM that
 // occasionally re-drafts twice before settling. Mirrors
 // aiAlertBuilderMaxIterations from slice 0015.
-const aiAutomationBuilderMaxIterations = 6
+const builderMaxIterations = 6
 
-// aiAutomationBuilderMaxPromptChars bounds the user-supplied
+// builderMaxPromptChars bounds the user-supplied
 // natural-language prompt at the HTTP boundary. Generous for a
 // multi-sentence rule description; defensive against an enormous
 // payload that would inflate the LLM's context window cost without
 // any plausible legitimate use.
-const aiAutomationBuilderMaxPromptChars = 4096
+const builderMaxPromptChars = 4096
 
-// AIAutomationHandler is the HTTP handler for
+// Handler is the HTTP handler for
 // POST /api/v1/ai/automations/draft.
 //
 // Stateless beyond its constructor inputs; safe for concurrent use
 // across requests. Construction is in router.go so the dispatcher's
 // tool registry + provider registry are wired once at boot.
-type AIAutomationHandler struct {
+type Handler struct {
 	registry   *provider.Registry
 	tools      *tools.Registry
 	strategy   strategy.Strategy
 	headerName string
 	maxIters   int
 }
 
-// NewAIAutomationHandler constructs the handler. All non-pointer
+// NewHandler constructs the handler. All non-pointer
 // arguments are required; the constructor panics on a nil so the
 // wiring bug surfaces at boot, not at first request.
 //
@@ -111,37 +113,37 @@ type AIAutomationHandler struct {
 //
 // strat:      the nl-automation-builder Strategy (one per process).
 // headerName: forward-auth header name; used to extract subject for audit.
-func NewAIAutomationHandler(
+func NewHandler(
 	registry *provider.Registry,
 	toolReg *tools.Registry,
 	strat strategy.Strategy,
 	headerName string,
-) *AIAutomationHandler {
+) *Handler {
 	switch {
 	case registry == nil:
-		panic("api: NewAIAutomationHandler: nil provider.Registry")
+		panic("aiautomation: NewHandler: nil provider.Registry")
 	case toolReg == nil:
-		panic("api: NewAIAutomationHandler: nil tools.Registry")
+		panic("aiautomation: NewHandler: nil tools.Registry")
 	case strat == nil:
-		panic("api: NewAIAutomationHandler: nil strategy.Strategy")
+		panic("aiautomation: NewHandler: nil strategy.Strategy")
 	}
-	return &AIAutomationHandler{
+	return &Handler{
 		registry:   registry,
 		tools:      toolReg,
 		strategy:   strat,
 		headerName: headerName,
-		maxIters:   aiAutomationBuilderMaxIterations,
+		maxIters:   builderMaxIterations,
 	}
 }
 
-// aiAutomationBuilderRequest is the wire shape for
+// builderRequest is the wire shape for
 // POST /api/v1/ai/automations/draft.
 //
 // VehicleID is required and must be > 0 — the AI handler scopes the
 // drafting to a single vehicle. Prompt is the user's plain-language
 // description of the automation they want, capped at
-// aiAutomationBuilderMaxPromptChars.
-type aiAutomationBuilderRequest struct {
+// builderMaxPromptChars.
+type builderRequest struct {
 	VehicleID int64  `json:"vehicle_id"`
 	Prompt    string `json:"prompt"`
 }
@@ -151,9 +153,9 @@ type aiAutomationBuilderRequest struct {
 // dispatcher's deferred WriteDone. Every error path either writes a
 // structured frame onto the SSE stream (when the writer has been
 // opened) or a plain JSON 4xx/5xx (before it has).
-func (h *AIAutomationHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	// 1) Decode + validate request body.
-	var body aiAutomationBuilderRequest
+	var body builderRequest
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		writeError(w, http.StatusBadRequest, "invalid request body")
 		return
@@ -167,8 +169,8 @@ func (h *AIAutomationHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
 		writeError(w, http.StatusBadRequest, "prompt is required")
 		return
 	}
-	if len(prompt) > aiAutomationBuilderMaxPromptChars {
-		writeError(w, http.StatusBadRequest, fmt.Sprintf("prompt must be at most %d characters", aiAutomationBuilderMaxPromptChars))
+	if len(prompt) > builderMaxPromptChars {
+		writeError(w, http.StatusBadRequest, fmt.Sprintf("prompt must be at most %d characters", builderMaxPromptChars))
 		return
 	}
 
@@ -255,31 +257,40 @@ func (h *AIAutomationHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
 	}
 }
 
-// Compile-time assertion: AIAutomationHandler satisfies http.Handler.
-var _ http.Handler = (*AIAutomationHandler)(nil)
+// Compile-time assertion: Handler satisfies http.Handler.
+var _ http.Handler = (*Handler)(nil)
 
-// AIAutomationGraphValidator is the production implementation of
+func writeError(w http.ResponseWriter, status int, msg string) {
+	apihttpx.WriteError(w, status, msg)
+}
+
+// denyAllConfirm rejects every mutating tool as defence-in-depth.
+func denyAllConfirm(_ context.Context, _ dispatch.ConfirmRequest) (dispatch.ConfirmDecision, error) {
+	return dispatch.ConfirmDenied, nil
+}
+
+// GraphValidator is the production implementation of
 // automationtool.AutomationGraphValidator. It is a thin wrapper around the
 // automation subpackage's canonical typed payload validator so the AI tool
 // registration path can wire the same validation path used by the manual
 // save endpoint.
 //
 // One per process; stateless.
-type AIAutomationGraphValidator struct{}
+type GraphValidator struct{}
 
-// NewAIAutomationGraphValidator returns a ready-to-use validator
+// NewGraphValidator returns a ready-to-use validator
 // wrapper. Exists as a constructor (rather than a value) so a future
 // change that adds wiring (e.g. a custom signal allowlist) does not
 // force every call site to update.
-func NewAIAutomationGraphValidator() *AIAutomationGraphValidator {
-	return &AIAutomationGraphValidator{}
+func NewGraphValidator() *GraphValidator {
+	return &GraphValidator{}
 }
 
 // ValidateAutomationWire implements [automationtool.AutomationGraphValidator].
 // Delegates to the canonical automation input validator — same code path the
 // POST /api/v1/automations handler runs, so a draft accepted here is
 // byte-equivalent to a draft accepted by the canonical handler.
-func (v *AIAutomationGraphValidator) ValidateAutomationWire(wireJSON json.RawMessage) error {
+func (v *GraphValidator) ValidateAutomationWire(wireJSON json.RawMessage) error {
 	if len(wireJSON) == 0 {
 		return fmt.Errorf("empty wire payload")
 	}

…ternal/api/ai_automation_handler_test.go internal/api/aiautomation/handler_test.gointernal/api/ai_automation_handler_test.go renamed to internal/api/aiautomation/handler_test.go internal/api/ai_automation_handler_test.go renamed to internal/api/aiautomation/handler_test.go

@@ -13,9 +13,10 @@
 // F6 eval harness (`go run ./cmd/ai-eval --feature nl-automation-builder`);
 // duplicating that here would require a live database fixture.
 
-package api
+package aiautomation
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -28,6 +29,24 @@ import (
 	"github.com/ev-dev-labs/teslasync/internal/ai/guard"
 )
 
+// stubGuardSettings is a minimal in-memory guard.Settings used to
+// drive the off-mode contract test without a real DB.
+type stubGuardSettings struct {
+	mode string
+	on   map[string]bool
+}
+
+func (s *stubGuardSettings) AIMode(_ context.Context) (string, error) {
+	if s.mode == "" {
+		return "off", nil
+	}
+	return s.mode, nil
+}
+
+func (s *stubGuardSettings) AIFeatureEnabled(_ context.Context, id string) (bool, error) {
+	return s.on[id], nil
+}
+
 // TestNLAutomationBuilderAIOffHidesPanelAndManualBuilderWorks is the
 // load-bearing off-mode contract proof for slice 0016. It mounts the
 // AI automation builder route through the guard with ai_mode='off'
@@ -136,35 +155,35 @@ func TestNLAutomationBuilderAIOffHidesPanelAndManualBuilderWorks(t *testing.T) {
 	}
 }
 
-// TestAIAutomationHandler_PanicsOnNilWiring asserts the handler
+// TestHandler_PanicsOnNilWiring asserts the handler
 // constructor refuses zero-valued dependencies. A wiring bug at boot
 // must surface as a panic, not as a nil-deref on first request.
-func TestAIAutomationHandler_PanicsOnNilWiring(t *testing.T) {
+func TestHandler_PanicsOnNilWiring(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
 		name string
 		fn   func()
 	}{
-		{"all nil", func() { NewAIAutomationHandler(nil, nil, nil, "") }},
+		{"all nil", func() { NewHandler(nil, nil, nil, "") }},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			defer func() {
 				if r := recover(); r == nil {
-					t.Fatalf("NewAIAutomationHandler(%s) did not panic", tc.name)
+					t.Fatalf("NewHandler(%s) did not panic", tc.name)
 				}
 			}()
 			tc.fn()
 		})
 	}
 }
 
-// TestAIAutomationHandler_RejectsBadInput asserts the handler
+// TestHandler_RejectsBadInput asserts the handler
 // validates the request body BEFORE opening the SSE stream — a
 // missing vehicle_id, missing prompt, or oversized prompt must
 // surface as a JSON 400, not a half-opened stream that confuses the
 // frontend.
-func TestAIAutomationHandler_RejectsBadInput(t *testing.T) {
+func TestHandler_RejectsBadInput(t *testing.T) {
 	t.Parallel()
 
 	cases := []struct {
@@ -179,7 +198,7 @@ func TestAIAutomationHandler_RejectsBadInput(t *testing.T) {
 		{"missing prompt", `{"vehicle_id":1}`},
 		{"empty prompt", `{"vehicle_id":1,"prompt":""}`},
 		{"whitespace prompt", `{"vehicle_id":1,"prompt":"   "}`},
-		{"prompt too large", fmt.Sprintf(`{"vehicle_id":1,"prompt":%q}`, strings.Repeat("a", aiAutomationBuilderMaxPromptChars+1))},
+		{"prompt too large", fmt.Sprintf(`{"vehicle_id":1,"prompt":%q}`, strings.Repeat("a", builderMaxPromptChars+1))},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -193,16 +212,16 @@ func TestAIAutomationHandler_RejectsBadInput(t *testing.T) {
 	}
 }
 
-// TestAIAutomationHandler_AcceptsCanonicalInput proves the validator
+// TestHandler_AcceptsCanonicalInput proves the validator
 // does NOT bounce the happy-path shapes — vehicle_id + a
 // normal-length prompt, plus a prompt at the size boundary.
-func TestAIAutomationHandler_AcceptsCanonicalInput(t *testing.T) {
+func TestHandler_AcceptsCanonicalInput(t *testing.T) {
 	t.Parallel()
 
 	cases := []string{
 		`{"vehicle_id":1,"prompt":"start charging when I get home"}`,
 		`{"vehicle_id":1,"prompt":"a"}`,
-		fmt.Sprintf(`{"vehicle_id":1,"prompt":%q}`, strings.Repeat("a", aiAutomationBuilderMaxPromptChars)),
+		fmt.Sprintf(`{"vehicle_id":1,"prompt":%q}`, strings.Repeat("a", builderMaxPromptChars)),
 	}
 	for _, body := range cases {
 		t.Run(body[:min(len(body), 60)], func(t *testing.T) {
@@ -216,17 +235,17 @@ func TestAIAutomationHandler_AcceptsCanonicalInput(t *testing.T) {
 	}
 }
 
-// TestAIAutomationGraphValidator_DelegatesToCanonical asserts the
+// TestGraphValidator_DelegatesToCanonical asserts the
 // production wrapper delegates to the canonical
 // decodeAutomationInputDTO function — same code path the typed
 // handler uses, so a draft accepted by the AI tool is byte-equivalent
 // to a draft accepted by the canonical handler. We pass an
 // obviously-bad payload and confirm the wrapper surfaces the
 // canonical layer's diagnostic; we then pass a known-good payload
 // and confirm acceptance.
-func TestAIAutomationGraphValidator_DelegatesToCanonical(t *testing.T) {
+func TestGraphValidator_DelegatesToCanonical(t *testing.T) {
 	t.Parallel()
-	v := NewAIAutomationGraphValidator()
+	v := NewGraphValidator()
 
 	if err := v.ValidateAutomationWire(nil); err == nil {
 		t.Error("ValidateAutomationWire(nil) err = nil, want non-nil")
@@ -251,11 +270,11 @@ func TestAIAutomationGraphValidator_DelegatesToCanonical(t *testing.T) {
 }
 
 // validateAutomationBuilderOnly mirrors the pre-stream validator
-// branch of AIAutomationHandler.ServeHTTP. Kept as a same-package
+// branch of Handler.ServeHTTP. Kept as a same-package
 // helper so the test does not need to construct a full handler with
 // stub deps.
 func validateAutomationBuilderOnly(w http.ResponseWriter, r *http.Request) {
-	var body aiAutomationBuilderRequest
+	var body builderRequest
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 		writeError(w, http.StatusBadRequest, "invalid request body")
 		return
@@ -269,8 +288,8 @@ func validateAutomationBuilderOnly(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "prompt is required")
 		return
 	}
-	if len(prompt) > aiAutomationBuilderMaxPromptChars {
-		writeError(w, http.StatusBadRequest, fmt.Sprintf("prompt must be at most %d characters", aiAutomationBuilderMaxPromptChars))
+	if len(prompt) > builderMaxPromptChars {
+		writeError(w, http.StatusBadRequest, fmt.Sprintf("prompt must be at most %d characters", builderMaxPromptChars))
 		return
 	}
 	w.WriteHeader(http.StatusOK)

internal/api/router.go

@@ -17,6 +17,7 @@ import (
 	apiadminfb "github.com/ev-dev-labs/teslasync/internal/api/adminfeedback"
 	apiadminls "github.com/ev-dev-labs/teslasync/internal/api/adminlogstream"
 	apiadminmnt "github.com/ev-dev-labs/teslasync/internal/api/adminmaintenance"
+	aiautomation "github.com/ev-dev-labs/teslasync/internal/api/aiautomation"
 	apialertmsg "github.com/ev-dev-labs/teslasync/internal/api/alertmsg"
 	apialerts "github.com/ev-dev-labs/teslasync/internal/api/alerts"
 	apianalytics "github.com/ev-dev-labs/teslasync/internal/api/analytics"
@@ -857,16 +858,16 @@ func NewRouter(db *database.DB, teslaClient *tesla.Client, mqttClient *mqtt.Clie
 		cfg.Auth.ForwardAuthHeader,
 	)
 	// Phase-50 / N2 (slice 0016) nl-automation-builder. Mirrors the
-	// alert-builder wiring above. AIAutomationGraphValidator is a
+	// alert-builder wiring above. aiautomation.GraphValidator is a
 	// thin wrapper around the automation subpackage validator in
 	// internal/api/automation/decode.go — same code path the canonical
 	// POST /api/v1/automations handler uses. Drafts
 	// accepted by the AI tool are byte-equivalent to drafts accepted
 	// by the canonical handler (ADR-015 §I3 baseline-intact).
 	automationtool.RegisterAutomationBuilderTools(aiToolRegistry, automationtool.AutomationBuilderSources{
-		Validator: NewAIAutomationGraphValidator(),
+		Validator: aiautomation.NewGraphValidator(),
 	})
-	aiAutomationHandler := NewAIAutomationHandler(
+	aiAutomationHandler := aiautomation.NewHandler(
 		aiRegistry,
 		aiToolRegistry,
 		nlautomationbuilder.New(),
@@ -1813,7 +1814,7 @@ func NewRouter(db *database.DB, teslaClient *tesla.Client, mqttClient *mqtt.Clie
 	// handler. The strategy REUSES the slice-0016
 	// nl-automation-builder tool pair (draft_automation_graph +
 	// validate_automation_graph) registered earlier in this file
-	// for the AIAutomationHandler — re-registering would panic on
+	// for the aiautomation.Handler — re-registering would panic on
 	// duplicate name. The handler ALSO needs read access to the
 	// user's existing geofence catalog so it can inject a
 	// deterministic id+name+category list into the synthesised