feat: Phase 3b — EntityService, postgres EntityRepository, converged mutations

Problem: entity mutations (create/update/state) existed as three drifted
copies — HTTP CreateEntity/PatchEntity, MCP create_entity/
update_entity_attributes/set_entity_state — each with its own inline
SQL, its own validation subset (MCP validated lifecycle states, HTTP
did not; HTTP patched attributes without regenerating derived checks,
MCP did; MCP wrote no audit trail), the exact drift ADR 0016's first
vertical slice exists to collapse.

Change:
- internal/core/ports: DerivedCheck, Idempotency (adapter-owned request
  hash + cached-body renderer so the replay record commits in the
  create's transaction), IdempotentResponse + GetIdempotent read,
  AuditEntry gains Method/Path/CorrelationID, Event gains
  CorrelationID; EntityUpdateInput carries ExpectedVersion +
  RederiveChecks (derivation for updates runs repo-side: the graph
  host fallback reads relationships through the open tx).
- internal/adapters/postgres/repositories.go: EntityRepo (Create/
  Update/SetState/reads/idempotency) preserving the load-bearing
  check-then-act invariants in-tx: version WHERE-clause, declared
  transitions + preconditions (ValidateTransition), duplicate-slug
  mapping, audit/event/writeCheck all inside one BEGIN…COMMIT.
  OntologyRepo: TTL-cached OntologyStore.
- internal/core/app/entities.go: EntityService — ontology validation
  (type exists, concrete, state declared — the stricter MCP rule now
  governs both surfaces), default-state resolution, id generation,
  derivation for creates, audit/event construction, idempotency
  pass-through.
- httpapi CreateEntity/PatchEntity rewired to the service; PATCH now
  regenerates derived checks (the A2 parity gap). MCP create/update/
  set-state tools call the same service — and now write audit + event
  rows like the HTTP surface always did.
- Integration-test seed paths fixed for the adapters/postgres package
  depth (../../../seeds).

Pre-existing failures documented: TestAPIEndToEnd (entity_types 60 vs
59; 501-endpoint now 200), TestClientLifecycleEndToEnd, TestPhase3*
rows — verified failing identically at ec11956 (scratch approval-
notifier commit test drift), unrelated to this change. All mutation
integration tests (create/patch/idempotency/audit/regeneration) pass.

Verification: make test-db (postgres + mcp green, httpapi green except
the pre-existing set), full non-DB suite (19 pkgs), golangci on new
packages — 0 issues.

internal/httpapi/entity_mutations.go

@@ -4,18 +4,14 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"strconv"
-	"strings"
 
-	"github.com/dtoro/oikos/internal/adapters/postgres"
-	"github.com/dtoro/oikos/internal/adapters/postgres/sqlcgen"
+	"github.com/dtoro/oikos/internal/core/app"
 	"github.com/dtoro/oikos/internal/core/domain"
+	"github.com/dtoro/oikos/internal/core/ports"
 	"github.com/dtoro/oikos/internal/httpapi/gen"
-	"github.com/dtoro/oikos/internal/observability"
 	"github.com/google/uuid"
-	"github.com/jackc/pgx/v5"
 )
 
 func (s *Server) CreateEntity(ctx context.Context, req gen.CreateEntityRequestObject) (gen.CreateEntityResponseObject, error) {
@@ -25,25 +21,21 @@ func (s *Server) CreateEntity(ctx context.Context, req gen.CreateEntityRequestOb
 
 	// Check idempotency if a key was provided. The idempotency scope is the
 	// calling actor, so replays are per-caller.
-	actorType, actorLabel := actorInfo(ctx)
-	actor := actorLabel
-	var bodyHash string
+	actorType, actor := actorInfo(ctx)
+	var idem *ports.Idempotency
 	if req.Params.IdempotencyKey != nil && *req.Params.IdempotencyKey != "" {
+		bodyJSON, _ := json.Marshal(req.Body)
+		hash := fmt.Sprintf("%x", sha256.Sum256(bodyJSON))
 		key := *req.Params.IdempotencyKey
-		q := sqlcgen.New(s.pool)
-		cached, err := q.GetIdempotentResponse(ctx, sqlcgen.GetIdempotentResponseParams{
-			Actor: actor,
-			Key:   key,
-		})
+
+		cached, err := s.entityRepo.GetIdempotent(ctx, actor, key)
 		if err == nil {
 			// Verify the request body hasn't changed.
-			bodyJSON, _ := json.Marshal(req.Body)
-			bodyHash = fmt.Sprintf("%x", sha256.Sum256(bodyJSON))
-			if cached.RequestHash != bodyHash {
+			if cached.RequestHash != hash {
 				return nil, fmt.Errorf("%w: idempotency key %s used with different request body", domain.ErrConflict, key)
 			}
 			// Replay the cached response.
-			if cached.ResponseCode != nil && *cached.ResponseCode == 201 {
+			if cached.ResponseCode == 201 {
 				var entity gen.Entity
 				if len(cached.ResponseBody) > 0 {
 					if err := json.Unmarshal(cached.ResponseBody, &entity); err != nil {
@@ -57,123 +49,38 @@ func (s *Server) CreateEntity(ctx context.Context, req gen.CreateEntityRequestOb
 			}
 			// Forward cached error response.
 			return gen.CreateEntitydefaultApplicationProblemPlusJSONResponse{
-				Body:       gen.Problem{Status: int(*cached.ResponseCode), Title: "replayed error"},
-				StatusCode: int(*cached.ResponseCode),
+				Body:       gen.Problem{Status: cached.ResponseCode, Title: "replayed error"},
+				StatusCode: cached.ResponseCode,
 			}, nil
 		}
-	}
-
-	id, err := uuid.NewV7()
-	if err != nil {
-		return nil, err
-	}
-	slug := req.Body.Slug
-	if slug == "" {
-		slug = req.Body.Type + ":" + req.Body.Name
-	}
-
-	tx, err := s.pool.Begin(ctx)
-	if err != nil {
-		return nil, err
-	}
-	defer tx.Rollback(ctx)
-	q := sqlcgen.New(tx)
-
-	// Validate type exists and is NOT abstract.
-	var isAbstract bool
-	if err := tx.QueryRow(ctx, `SELECT is_abstract FROM entity_types WHERE name = $1`, req.Body.Type).Scan(&isAbstract); err != nil {
-		if err == pgx.ErrNoRows {
-			return nil, fmt.Errorf("%w: entity type %q", domain.ErrNotFound, req.Body.Type)
+		idem = &ports.Idempotency{
+			Actor: actor, Key: key, RequestHash: hash,
+			// RenderBody serializes the adapter's wire shape inside the
+			// create's transaction, so a replay returns the original
+			// response atomically with the insert.
+			RenderBody: func(e domain.Entity) []byte {
+				b, _ := json.Marshal(domainToGen(e))
+				return b
+			},
 		}
-		return nil, err
-	}
-	if isAbstract {
-		return nil, fmt.Errorf("%w: %s", domain.ErrAbstractType, req.Body.Type)
 	}
 
-	// Get default state from lifecycle.
-	var defaultState *string
-	var lcDefault string
-	if err := tx.QueryRow(ctx, `SELECT ld.default_state FROM lifecycle_defs ld
-		JOIN entity_types et ON et.lifecycle_id = ld.id
-		WHERE et.name = $1`, req.Body.Type).Scan(&lcDefault); err == nil {
-		defaultState = &lcDefault
-	}
-
-	state := req.Body.State
-	if state == nil && defaultState != nil {
-		state = defaultState
-	}
-
-	// attributes is NOT NULL; the column default only applies when omitted,
-	// not when an explicit NULL is bound — so default to an empty object.
-	attrsJSON := []byte("{}")
-	if req.Body.Attributes != nil {
-		attrsJSON, _ = json.Marshal(req.Body.Attributes)
-	}
-
-	// Insert the entity.
-	inserted, err := q.InsertEntity(ctx, sqlcgen.InsertEntityParams{
-		ID:         id,
-		Slug:       slug,
-		Type:       req.Body.Type,
-		Name:       req.Body.Name,
-		State:      state,
-		Attributes: attrsJSON,
+	created, _, err := s.entities.Create(ctx, app.CreateEntityCmd{
+		Slug:        req.Body.Slug,
+		Type:        req.Body.Type,
+		Name:        req.Body.Name,
+		State:       derefStr(req.Body.State),
+		Attributes:  derefAttrs(req.Body.Attributes),
+		ActorType:   actorType,
+		Actor:       actor,
+		Method:      "POST",
+		Path:        "/api/v1/entities",
+		Idempotency: idem,
 	})
 	if err != nil {
-		// Duplicate slug.
-		if strings.Contains(err.Error(), "unique") || strings.Contains(err.Error(), "duplicate") {
-			return nil, fmt.Errorf("%w: slug %q already exists", domain.ErrAlreadyExists, slug)
-		}
 		return nil, err
 	}
-
-	// Convert sqlcgen.Entity → gen.Entity.
-	entity := sqlcEntityToGen(inserted)
-
-	// Cache idempotent response.
-	if req.Params.IdempotencyKey != nil && *req.Params.IdempotencyKey != "" {
-		respBody, _ := json.Marshal(entity)
-		code := int32(201)
-		if bodyHash == "" {
-			bodyJSON, _ := json.Marshal(req.Body)
-			bodyHash = fmt.Sprintf("%x", sha256.Sum256(bodyJSON))
-		}
-		if putErr := q.PutIdempotentResponse(ctx, sqlcgen.PutIdempotentResponseParams{
-			Actor:        actor,
-			Key:          *req.Params.IdempotencyKey,
-			RequestHash:  bodyHash,
-			ResponseCode: &code,
-			ResponseBody: respBody,
-		}); putErr != nil {
-			return nil, putErr
-		}
-	}
-
-	// Audit.
-	entityID := inserted.ID
-	if auditErr := observability.Audit(ctx, q, actorType, actor, "create",
-		&entityID, "POST", "/api/v1/entities", "",
-		nil,
-		map[string]any{"type": req.Body.Type, "slug": slug}); auditErr != nil {
-		return nil, auditErr
-	}
-
-	if eventErr := observability.Event(ctx, q, "entity.created", &entityID,
-		"info", "oikos-api", "",
-		map[string]any{"slug": slug, "type": req.Body.Type}); eventErr != nil {
-		return nil, eventErr
-	}
-
-	if err := ensureDefaultChecks(ctx, tx, inserted.ID, slug, req.Body.Type, inserted.Name, attrsJSON); err != nil {
-		return nil, err
-	}
-
-	if err := tx.Commit(ctx); err != nil {
-		return nil, err
-	}
-
+	entity := domainToGen(created)
 	return gen.CreateEntity201JSONResponse{
 		Body:    entity,
 		Headers: gen.CreateEntity201ResponseHeaders{ETag: `"` + strconv.Itoa(entity.Version) + `"`},
@@ -185,106 +92,87 @@ func (s *Server) PatchEntity(ctx context.Context, req gen.PatchEntityRequestObje
 		return nil, fmt.Errorf("%w: request body is required", domain.ErrInvalidInput)
 	}
 
-	id, err := s.resolveEntityID(ctx, req.Id)
-	if err != nil {
-		return nil, err
-	}
-
 	// Parse If-Match header (quoted version string).
-	ifMatch := strings.Trim(req.Params.IfMatch, `"`)
+	ifMatch := trimQuotes(req.Params.IfMatch)
 	expectedVersion, err := strconv.Atoi(ifMatch)
 	if err != nil {
 		return nil, fmt.Errorf("%w: invalid If-Match header %q", domain.ErrInvalidInput, req.Params.IfMatch)
 	}
 
-	tx, err := s.pool.Begin(ctx)
-	if err != nil {
-		return nil, err
-	}
-	defer tx.Rollback(ctx)
-
-	// Get current entity for version check + lifecycle validation.
-	current, err := sqlcgen.New(tx).GetEntityByID(ctx, id)
-	if err != nil {
-		if err == pgx.ErrNoRows {
-			return nil, fmt.Errorf("%w: %s", domain.ErrNotFound, req.Id)
-		}
-		return nil, err
-	}
-
-	if int(current.Version) != expectedVersion {
-		return nil, fmt.Errorf("%w: expected version %d, current version %d",
-			domain.ErrConflict, expectedVersion, current.Version)
-	}
-
-	// Validate lifecycle transition if state is being changed.
-	if req.Body.State != nil && *req.Body.State != "" {
-		fromState := ""
-		if current.State != nil {
-			fromState = *current.State
-		}
-		if err := db.ValidateTransition(ctx, tx, id, current.Type, fromState, *req.Body.State); err != nil {
-			if errors.Is(err, db.ErrTransitionInvalid) {
-				return nil, fmt.Errorf("%w: %v", domain.ErrInvalidTransition, err)
-			}
-			return nil, err
-		}
-	}
-
-	// Check idempotency (note: the spec doesn't define Idempotency-Key for PATCH,
-	// but we handle it if the generated code ever adds it).
-	// For now, no idempotency check on PATCH.
-
-	// Marshal attributes if provided.
-	var attrsJSON []byte
-	if req.Body.Attributes != nil {
-		attrsJSON, _ = json.Marshal(req.Body.Attributes)
-	}
-
-	// Perform the update via sqlcgen.
-	q := sqlcgen.New(tx)
-	updated, err := q.UpdateEntity(ctx, sqlcgen.UpdateEntityParams{
-		Name:             req.Body.Name,
-		State:            req.Body.State,
-		Attributes:       attrsJSON,
-		SetMaintenance:   req.Body.MaintenanceUntil != nil,
-		MaintenanceUntil: req.Body.MaintenanceUntil,
-		ID:               id,
-		Version:          int32(expectedVersion),
+	patchActorType, patchActor := actorInfo(ctx)
+	updated, _, err := s.entities.Update(ctx, app.UpdateEntityCmd{
+		SlugOrID:     req.Id,
+		ExpectedVer:  expectedVersion,
+		Name:         derefStr(req.Body.Name),
+		State:        derefStr(req.Body.State),
+		Attributes:   derefAttrs(req.Body.Attributes),
+		AttrsReplace: true,
+		Maintenance:  req.Body.MaintenanceUntil,
+		SetMaint:     req.Body.MaintenanceUntil != nil,
+		// Attribute changes propagate to derived checks (the A2 parity fix:
+		// previously only the MCP surface regenerated checks on attribute
+		// changes).
+		RederiveChecks: true,
+		ActorType:      patchActorType,
+		Actor:          patchActor,
+		Method:         "PATCH",
+		Path:           "/api/v1/entities/" + req.Id,
 	})
 	if err != nil {
-		if err == pgx.ErrNoRows {
-			// Version mismatch or entity not found.
-			return nil, fmt.Errorf("%w: entity was modified concurrently", domain.ErrConflict)
-		}
-		return nil, err
-	}
-
-	entity := sqlcEntityToGen(updated)
-
-	// Audit.
-	patchActorType, patchActor := actorInfo(ctx)
-	if auditErr := observability.Audit(ctx, q, patchActorType, patchActor, "patch",
-		&id, "PATCH", "/api/v1/entities/"+req.Id, "",
-		nil,
-		map[string]any{"version": expectedVersion}); auditErr != nil {
-		return nil, auditErr
-	}
-
-	if eventErr := observability.Event(ctx, q, "entity.updated", &id,
-		"info", "oikos-api", "",
-		map[string]any{"slug": entity.Slug, "type": entity.Type, "version": updated.Version}); eventErr != nil {
-		return nil, eventErr
-	}
-
-	if err := tx.Commit(ctx); err != nil {
 		return nil, err
 	}
 
+	entity := domainToGen(updated)
 	s.entityCache.Invalidate(entity.Slug, entity.Id.String())
 
 	return gen.PatchEntity200JSONResponse{
 		Body:    entity,
 		Headers: gen.PatchEntity200ResponseHeaders{ETag: `"` + strconv.Itoa(entity.Version) + `"`},
 	}, nil
-}
+}
+
+func derefStr(p *string) string {
+	if p == nil {
+		return ""
+	}
+	return *p
+}
+
+func derefAttrs(p *map[string]any) map[string]any {
+	if p == nil {
+		return nil
+	}
+	return *p
+}
+
+func trimQuotes(s string) string {
+	if len(s) >= 2 && s[0] == '"' && s[len(s)-1] == '"' {
+		return s[1 : len(s)-1]
+	}
+	return s
+}
+
+// domainToGen converts a domain entity to the wire shape.
+func domainToGen(e domain.Entity) gen.Entity {
+	id, _ := uuid.Parse(string(e.ID))
+	out := gen.Entity{
+		Id:        id,
+		Slug:      e.Slug,
+		Type:      e.Type,
+		Name:      e.Name,
+		Version:   e.Version,
+		CreatedAt: e.CreatedAt,
+		UpdatedAt: e.UpdatedAt,
+	}
+	if e.State != "" {
+		out.State = &e.State
+	}
+	if e.MaintenanceUntil != nil {
+		out.MaintenanceUntil = e.MaintenanceUntil
+	}
+	if len(e.Attributes) > 0 {
+		attrs := e.Attributes
+		out.Attributes = &attrs
+	}
+	return out
+}

internal/httpapi/server.go

@@ -26,6 +26,7 @@ import (
 	"github.com/dtoro/oikos/internal/actuator"
 	"github.com/dtoro/oikos/internal/config"
 	"github.com/dtoro/oikos/internal/adapters/postgres"
+	"github.com/dtoro/oikos/internal/core/app"
 	"github.com/dtoro/oikos/internal/httpapi/gen"
 	mcphandler "github.com/dtoro/oikos/internal/mcp"
 	"github.com/dtoro/oikos/internal/safego"
@@ -59,6 +60,12 @@ type Server struct {
 	sseBroker      *sseBroker
 	sseSubs        map[*sseSubscriber]struct{}
 	sseMu          sync.Mutex
+
+	// entities is the entity-aggregate use-case service (Phase 3 of the
+	// hexagonal refactor); entityRepo exposes the idempotency reads the
+	// replay path needs. Wired here until main becomes the composition root.
+	entities   *app.EntityService
+	entityRepo *db.EntityRepo
 }
 
 // NewHandler builds the full HTTP handler: /healthz (unauthenticated,
@@ -76,6 +83,8 @@ func NewHandler(ctx context.Context, pool *db.Pool, cfg config.Config) http.Hand
 		sseBroker:   newSSEBroker(10000),
 		sseSubs:     make(map[*sseSubscriber]struct{}),
 	}
+	s.entityRepo = db.NewEntityRepo(pool)
+	s.entities = app.NewEntityService(s.entityRepo, db.NewOntologyRepo(pool, time.Minute))
 
 	// Wire secrets backend: Infisical primary with SOPS DR fallback.
 	if cfg.InfisicalSiteURL != "" {
@@ -318,7 +327,7 @@ func NewHandler(ctx context.Context, pool *db.Pool, cfg config.Config) http.Hand
 	if nomosAgentID == uuid.Nil && cfg.NomosAgentSlug != "" {
 		_ = pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", cfg.NomosAgentSlug).Scan(&nomosAgentID)
 	}
-	r.With(combinedAuth(cfg, false)).Handle("/mcp", mcphandler.NewHandler(pool, cfg.MCPBearerToken, nomosAgentID, s.secretsManager))
+	r.With(combinedAuth(cfg, false)).Handle("/mcp", mcphandler.NewHandler(pool, cfg.MCPBearerToken, nomosAgentID, s.secretsManager, s.entities))
 
 	if nomosURL := os.Getenv("NOMOS_PROXY_URL"); nomosURL != "" {
 		target, _ := url.Parse(nomosURL)